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 keyself._term
contains the given value. Useful for creatingCONTAINS
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 keyself._term
equals the providedvalue
.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 keyself._term
is in the providedvalue_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 keyself._term
does not contain the given value. Useful for creatingDOES_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 keyself._term
does not equal the providedvalue
.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 keyself._term
is not in the providedvalue_list
.Parameters: value_list (list) – The list of values to exclude on. Returns: FilterGroup
-
classmethod
-
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 keyself._term
contains the given value. Useful for creatingCONTAINS
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 keyself._term
equals the providedvalue
.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 keyself._term
is in the providedvalue_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 keyself._term
does not contain the given value. Useful for creatingDOES_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 keyself._term
does not equal the providedvalue
.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 keyself._term
is not in the providedvalue_list
.Parameters: value_list (list) – The list of values to exclude on. Returns: FilterGroup
-
classmethod
-
class
py42.sdk.queries.alerts.filters.alert_filter.
AlertState
¶ Bases:
py42.sdk.queries.query_filter.QueryFilterStringField
Class that filters alerts based on alert state.
- Available options are:
AlertState.OPEN
AlertState.DISMISSED
AlertState.PENDING
AlertState.IN_PROGRESS
-
classmethod
eq
(value)¶ Returns a
FilterGroup
that is useful for finding results where the value with keyself._term
equals the providedvalue
.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 keyself._term
is in the providedvalue_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 keyself._term
does not equal the providedvalue
.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 keyself._term
is not in the providedvalue_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.query_filter.QueryFilterTimestampField
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 keyself._term
is in range between the providedstart_value
andend_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:
-
classmethod
on_or_after
(value)¶ Returns a
FilterGroup
that is useful for finding results where the value with keyself._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 keyself._term
is on or before the providedvalue
.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 keyself._term
is within the same calendar day as the providedvalue
.Parameters: value (str or int or float or datetime) – The value used to filter results. Returns: FilterGroup
-
classmethod
-
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 keyself._term
contains the given value. Useful for creatingCONTAINS
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 keyself._term
equals the providedvalue
.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 keyself._term
is in the providedvalue_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 keyself._term
does not contain the given value. Useful for creatingDOES_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 keyself._term
does not equal the providedvalue
.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 keyself._term
is not in the providedvalue_list
.Parameters: value_list (list) – The list of values to exclude on. Returns: FilterGroup
-
classmethod
-
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 keyself._term
equals the providedvalue
.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 keyself._term
is in the providedvalue_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 keyself._term
does not equal the providedvalue
.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 keyself._term
is not in the providedvalue_list
.Parameters: value_list (list) – The list of values to exclude on. Returns: FilterGroup
-
classmethod
-
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 keyself._term
contains the given value. Useful for creatingCONTAINS
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 keyself._term
equals the providedvalue
.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 keyself._term
is in the providedvalue_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 keyself._term
does not contain the given value. Useful for creatingDOES_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 keyself._term
does not equal the providedvalue
.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 keyself._term
is not in the providedvalue_list
.Parameters: value_list (list) – The list of values to exclude on. Returns: FilterGroup
-
classmethod
-
class
py42.sdk.queries.alerts.filters.alert_filter.
RuleSource
¶ Bases:
py42.sdk.queries.query_filter.QueryFilterStringField
Class that filters alerts based on rule source.
- Available options are:
RuleSource.ALERTING
RuleSource.DEPARTING_EMPLOYEE
RuleSource.HIGH_RISK_EMPLOYEE
-
classmethod
eq
(value)¶ Returns a
FilterGroup
that is useful for finding results where the value with keyself._term
equals the providedvalue
.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 keyself._term
is in the providedvalue_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 keyself._term
does not equal the providedvalue
.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 keyself._term
is not in the providedvalue_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
Class that filters alerts based on rule type.
- Available options are:
RuleType.ENDPOINT_EXFILTRATION
RuleType.CLOUD_SHARE_PERMISSIONS
RuleType.FILE_TYPE_MISMATCH
-
classmethod
eq
(value)¶ Returns a
FilterGroup
that is useful for finding results where the value with keyself._term
equals the providedvalue
.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 keyself._term
is in the providedvalue_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 keyself._term
does not equal the providedvalue
.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 keyself._term
is not in the providedvalue_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
Class that filters alerts based on severity.
- Available options are:
Severity.HIGH
Severity.MEDIUM
Severity.LOW
-
classmethod
eq
(value)¶ Returns a
FilterGroup
that is useful for finding results where the value with keyself._term
equals the providedvalue
.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 keyself._term
is in the providedvalue_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 keyself._term
does not equal the providedvalue
.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 keyself._term
is not in the providedvalue_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 keyterm
contains the given value. Useful for creatingCONTAINS
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: - term – (str): The term of the filter, such as
-
py42.sdk.queries.alerts.filters.alert_filter.
create_not_contains_filter_group
(term, value)¶ Creates a
FilterGroup
for filtering results where the value with keyterm
does not contain the given value. Useful for creatingDOES_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: - term – (str): The term of the filter, such as
-
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()
andany()
take one or moreFilterGroup
objects to construct a query that can be passed to theAlertService.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 asall()
.Usage example:
state_filter = AlertState.eq(AlertState.OPEN) rule_name_filter = RuleName.contains("EmailRule") query = AlertQuery.all(state_filter, rule_name_filter)
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_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.
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:
-
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:
-
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
.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: - query (
-
search_all_pages
(query)¶ Searches alerts using the given
py42.sdk.queries.alerts.alert_query.AlertQuery
.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:
-
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:
-