Alerts

class py42.clients.alerts.AlertsClient(alert_service, alert_rules_client)

Bases: object

A client to expose alert API.

get_aggregate_data(alert_id)

Gets alert summary with details about observations.

Parameters: alert_id (str) – Gets the details for the alert with the given ID.
Returns: py42.response.Py42Response

get_all_alert_details(query)

Helper method that combines search_all_pages() and get_details() methods to get alert objects with alert “observations” details populated. Returns an iterator of alert detail objects.

Note: automatically overrides the page_size property on the query object to limit search to 100 results per page, as that is the max that get_details() can request at a time.

Parameters: query (py42.sdk.queries.alerts.alert_query.AlertQuery) – An alert query.
Returns: An object that iterates over alert detail items.
Return type: generator

get_details(alert_ids)

Gets the details for the alerts with the given IDs, including the file event query that, when passed into a search, would result in events that could have triggered the alerts.

Rest Documentation

Parameters: alert_ids (str or list[str]) – The identification number(s) of the alerts for which you want to get details for. Note: The alerts backend accepts a maximum of 100 alerts per request.
Returns: A response containing the alert details.
Return type: py42.response.Py42Response

reopen(alert_ids, reason=None)

Reopens the resolved alerts with the given IDs.

Parameters

alert_ids (str or list[str]) – The identification number(s) for the alerts to reopen. Note: The alerts backend accepts a maximum of 100 alerts per request.
reason (str, optional) – The reason the alerts are reopened. Defaults to None.

Returns

py42.response.Py42Response

resolve(alert_ids, reason=None)

Resolves the alerts with the given IDs.

Parameters

alert_ids (str or list[str]) – The identification number(s) for the alerts to resolve. Note: The alerts backend accepts a maximum of 100 alerts per request.
reason (str, optional) – The reason the alerts are now resolved. Defaults to None.

Returns

py42.response.Py42Response

property rules

A collection of methods for managing alert rules.

Returns: py42.services.alertrules.AlertRulesClient

search(query, page_num=1, page_size=None)

Searches alerts using the given py42.sdk.queries.alerts.alert_query.AlertQuery.

Rest Documentation

Parameters

query (py42.sdk.queries.alerts.alert_query.AlertQuery) – An alert query. See the Executing Searches User Guide to learn more about how to construct a query.
page_num (int, optional) – The page number to get. Defaults to 1.
page_size (int, optional) – The number of items per page. Defaults to py42.settings.items_per_page.

Returns

A response containing the alerts that match the given query.

Return type

py42.response.Py42Response

search_all_pages(query)

Searches alerts using the given py42.sdk.queries.alerts.alert_query.AlertQuery.

Rest Documentation

Parameters: query (py42.sdk.queries.alerts.alert_query.AlertQuery) – An alert query. See the Executing Searches User Guide to learn more about how to construct a query.
Returns: An object that iterates over py42.response.Py42Response objects that each contain a page of alerts that match the given query.
Return type: generator

update_note(alert_id, note)

Updates an alert’s note.

Parameters

alert_id (str) – The identification number of an alert to add a note to.
note (str) – A note to attach to the alert. Must be less than 2000 characters. Defaults to None.

Returns

py42.response.Py42Response

update_state(status, alert_ids, note=None)

Updates the status of alerts.

Parameters

status (str) – Status to set from OPEN, RESOLVED, PENDING, IN_PROGRESS
alert_ids (str or list[str]) – The identification number(s) for the alerts to reopen. Note: The alerts backend accepts a maximum of 100 alerts per request.
note (str, optional) – A note to attach to the alerts. Must be less than 2000 characters. Defaults to None.

Returns

py42.response.Py42Response

Filter Classes

The following classes construct filters for file event queries. Each filter class corresponds to an alert detail. Call the appropriate classmethod on your desired filter class with the value you want to match and it will return a FilterGroup object that can be passed to AlertQuery’s all() or any() methods to create complex queries that match multiple filter rules.

See Executing Searches for more on building search queries.

class py42.sdk.queries.alerts.filters.alert_filter.Actor

Bases: py42.sdk.queries.alerts.filters.alert_filter.AlertQueryFilterStringField

Class that filters alerts based on the username that originated the event(s) that triggered the alert.

classmethod contains(value)

Creates a FilterGroup for filtering results where the value with key self._term contains the given value. Useful for creating CONTAINS filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters: value (str) – The value used to match on.
Returns: FilterGroup

classmethod eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term equals the provided value.

Parameters: value (str) – The value to match on.
Returns: FilterGroup

classmethod is_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is in the provided value_list.

Parameters: value_list (list) – The list of values to match on.
Returns: FilterGroup

classmethod not_contains(value)

Creates a FilterGroup for filtering results where the value with key self._term does not contain the given value. Useful for creating DOES_NOT_CONTAIN filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters: value (str) – The value used to exclude on.
Returns: FilterGroup

classmethod not_eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term does not equal the provided value.

Parameters: value (str) – The value to exclude on.
Returns: FilterGroup

classmethod not_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is not in the provided value_list.

Parameters: value_list (list) – The list of values to exclude on.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.AlertQueryFilterStringField

Bases: py42.sdk.queries.query_filter.QueryFilterStringField

classmethod contains(value)

Creates a FilterGroup for filtering results where the value with key self._term contains the given value. Useful for creating CONTAINS filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters: value (str) – The value used to match on.
Returns: FilterGroup

classmethod eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term equals the provided value.

Parameters: value (str) – The value to match on.
Returns: FilterGroup

classmethod is_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is in the provided value_list.

Parameters: value_list (list) – The list of values to match on.
Returns: FilterGroup

classmethod not_contains(value)

Creates a FilterGroup for filtering results where the value with key self._term does not contain the given value. Useful for creating DOES_NOT_CONTAIN filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters: value (str) – The value used to exclude on.
Returns: FilterGroup

classmethod not_eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term does not equal the provided value.

Parameters: value (str) – The value to exclude on.
Returns: FilterGroup

classmethod not_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is not in the provided value_list.

Parameters: value_list (list) – The list of values to exclude on.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.AlertQueryFilterTimestampField

Bases: py42.sdk.queries.query_filter.QueryFilterTimestampField

Helper class for creating alert filters where the search value is a timestamp.

classmethod in_range(start_value, end_value)

Returns a FilterGroup that is useful for finding results where the value with key self._term is in range between the provided start_value and end_value.

Parameters

start_value (str or int or float or datetime) – The start value used to filter results.
end_value (str or int or float or datetime) – The end value used to filter results.

Returns

FilterGroup

classmethod on_or_after(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term` is on or after the provided ``value.

Parameters: value (str or int or float or datetime) – The value used to filter results.
Returns: FilterGroup

classmethod on_or_before(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term is on or before the provided value.

Parameters: value (str or int or float or datetime) – The value used to filter results.
Returns: FilterGroup

classmethod on_same_day(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term is within the same calendar day as the provided value.

Parameters: value (str or int or float or datetime) – The value used to filter results.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.AlertState

Bases: py42.sdk.queries.query_filter.QueryFilterStringField, py42.choices.Choices

Class that filters alerts based on alert state.

Available options are:

AlertState.OPEN
AlertState.DISMISSED
AlertState.PENDING
AlertState.IN_PROGRESS

classmethod choices()

Returns attribute values for the given class.

Returns: A list containing the attribute values of the given class.
Return type: (list)

classmethod eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term equals the provided value.

Parameters: value (str) – The value to match on.
Returns: FilterGroup

classmethod is_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is in the provided value_list.

Parameters: value_list (list) – The list of values to match on.
Returns: FilterGroup

classmethod not_eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term does not equal the provided value.

Parameters: value (str) – The value to exclude on.
Returns: FilterGroup

classmethod not_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is not in the provided value_list.

Parameters: value_list (list) – The list of values to exclude on.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.DateObserved

Bases: py42.sdk.queries.alerts.filters.alert_filter.AlertQueryFilterTimestampField

Class that filters alerts based on the timestamp the alert was triggered.

classmethod in_range(start_value, end_value)

Returns a FilterGroup that is useful for finding results where the value with key self._term is in range between the provided start_value and end_value.

Parameters

start_value (str or int or float or datetime) – The start value used to filter results.
end_value (str or int or float or datetime) – The end value used to filter results.

Returns

FilterGroup

classmethod on_or_after(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term` is on or after the provided ``value.

Parameters: value (str or int or float or datetime) – The value used to filter results.
Returns: FilterGroup

classmethod on_or_before(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term is on or before the provided value.

Parameters: value (str or int or float or datetime) – The value used to filter results.
Returns: FilterGroup

classmethod on_same_day(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term is within the same calendar day as the provided value.

Parameters: value (str or int or float or datetime) – The value used to filter results.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.Description

Bases: py42.sdk.queries.alerts.filters.alert_filter.AlertQueryFilterStringField

Class that filters alerts based on rule description text.

classmethod contains(value)

Creates a FilterGroup for filtering results where the value with key self._term contains the given value. Useful for creating CONTAINS filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters: value (str) – The value used to match on.
Returns: FilterGroup

classmethod eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term equals the provided value.

Parameters: value (str) – The value to match on.
Returns: FilterGroup

classmethod is_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is in the provided value_list.

Parameters: value_list (list) – The list of values to match on.
Returns: FilterGroup

classmethod not_contains(value)

Creates a FilterGroup for filtering results where the value with key self._term does not contain the given value. Useful for creating DOES_NOT_CONTAIN filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters: value (str) – The value used to exclude on.
Returns: FilterGroup

classmethod not_eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term does not equal the provided value.

Parameters: value (str) – The value to exclude on.
Returns: FilterGroup

classmethod not_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is not in the provided value_list.

Parameters: value_list (list) – The list of values to exclude on.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.RuleId

Bases: py42.sdk.queries.query_filter.QueryFilterStringField

Class that filters alerts based on rule identifier.

classmethod eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term equals the provided value.

Parameters: value (str) – The value to match on.
Returns: FilterGroup

classmethod is_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is in the provided value_list.

Parameters: value_list (list) – The list of values to match on.
Returns: FilterGroup

classmethod not_eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term does not equal the provided value.

Parameters: value (str) – The value to exclude on.
Returns: FilterGroup

classmethod not_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is not in the provided value_list.

Parameters: value_list (list) – The list of values to exclude on.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.RuleName

Bases: py42.sdk.queries.alerts.filters.alert_filter.AlertQueryFilterStringField

Class that filters alerts based on rule name.

classmethod contains(value)

Creates a FilterGroup for filtering results where the value with key self._term contains the given value. Useful for creating CONTAINS filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters: value (str) – The value used to match on.
Returns: FilterGroup

classmethod eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term equals the provided value.

Parameters: value (str) – The value to match on.
Returns: FilterGroup

classmethod is_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is in the provided value_list.

Parameters: value_list (list) – The list of values to match on.
Returns: FilterGroup

classmethod not_contains(value)

Creates a FilterGroup for filtering results where the value with key self._term does not contain the given value. Useful for creating DOES_NOT_CONTAIN filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters: value (str) – The value used to exclude on.
Returns: FilterGroup

classmethod not_eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term does not equal the provided value.

Parameters: value (str) – The value to exclude on.
Returns: FilterGroup

classmethod not_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is not in the provided value_list.

Parameters: value_list (list) – The list of values to exclude on.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.RuleSource

Bases: py42.sdk.queries.query_filter.QueryFilterStringField, py42.choices.Choices

Class that filters alerts based on rule source.

Available options are:

RuleSource.ALERTING
RuleSource.DEPARTING_EMPLOYEE
RuleSource.HIGH_RISK_EMPLOYEE

classmethod choices()

Returns attribute values for the given class.

Returns: A list containing the attribute values of the given class.
Return type: (list)

classmethod eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term equals the provided value.

Parameters: value (str) – The value to match on.
Returns: FilterGroup

classmethod is_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is in the provided value_list.

Parameters: value_list (list) – The list of values to match on.
Returns: FilterGroup

classmethod not_eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term does not equal the provided value.

Parameters: value (str) – The value to exclude on.
Returns: FilterGroup

classmethod not_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is not in the provided value_list.

Parameters: value_list (list) – The list of values to exclude on.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.RuleType

Bases: py42.sdk.queries.query_filter.QueryFilterStringField, py42.choices.Choices

Class that filters alerts based on rule type.

Available options are:

RuleType.ENDPOINT_EXFILTRATION
RuleType.CLOUD_SHARE_PERMISSIONS
RuleType.FILE_TYPE_MISMATCH

classmethod choices()

Returns attribute values for the given class.

Returns: A list containing the attribute values of the given class.
Return type: (list)

classmethod eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term equals the provided value.

Parameters: value (str) – The value to match on.
Returns: FilterGroup

classmethod is_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is in the provided value_list.

Parameters: value_list (list) – The list of values to match on.
Returns: FilterGroup

classmethod not_eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term does not equal the provided value.

Parameters: value (str) – The value to exclude on.
Returns: FilterGroup

classmethod not_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is not in the provided value_list.

Parameters: value_list (list) – The list of values to exclude on.
Returns: FilterGroup

class py42.sdk.queries.alerts.filters.alert_filter.Severity

Bases: py42.sdk.queries.query_filter.QueryFilterStringField, py42.choices.Choices

Class that filters alerts based on severity.

Available options are:

Severity.CRITICAL
Severity.HIGH
Severity.MODERATE
Severity.LOW

classmethod choices()

Returns attribute values for the given class.

Returns: A list containing the attribute values of the given class.
Return type: (list)

classmethod eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term equals the provided value.

Parameters: value (str) – The value to match on.
Returns: FilterGroup

classmethod is_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is in the provided value_list.

Parameters: value_list (list) – The list of values to match on.
Returns: FilterGroup

classmethod not_eq(value)

Returns a FilterGroup that is useful for finding results where the value with key self._term does not equal the provided value.

Parameters: value (str) – The value to exclude on.
Returns: FilterGroup

classmethod not_in(value_list)

Returns a FilterGroup that is useful for finding results where the value with the key self._term is not in the provided value_list.

Parameters: value_list (list) – The list of values to exclude on.
Returns: FilterGroup

py42.sdk.queries.alerts.filters.alert_filter.create_contains_filter_group(term, value)

Creates a FilterGroup for filtering results where the value with key term contains the given value. Useful for creating CONTAINS filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters

term – (str): The term of the filter, such as actor.
value (str) – The value used to match on.

Returns

FilterGroup

py42.sdk.queries.alerts.filters.alert_filter.create_not_contains_filter_group(term, value)

Creates a FilterGroup for filtering results where the value with key term does not contain the given value. Useful for creating DOES_NOT_CONTAIN filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters

term – (str): The term of the filter, such as actor.
value (str) – The value used to exclude on.

Returns

FilterGroup

class py42.sdk.queries.alerts.alert_query.AlertQuery(*args, **kwargs)

Bases: py42.sdk.queries.BaseQuery

Helper class for building Code42 Alert queries.

An AlertQuery instance’s all() and any() take one or more FilterGroup objects to construct a query that can be passed to the AlertService.search() method. all() returns results that match all of the provided filter criteria, any() will return results that match any of the filters.

For convenience, the AlertQuery constructor does the same as all().

Usage example:

state_filter = AlertState.eq(AlertState.OPEN)
rule_name_filter = RuleName.contains("EmailRule")
query = AlertQuery.all(state_filter, rule_name_filter)