Shared Query Filters

class py42.sdk.queries.query_filter.FilterGroup(filter_list, filter_clause='AND')

Bases: object

Class for constructing a logical sub-group of related filters from a list of QueryFilter objects. Takes a list of QueryFilter objects and combines them logically using the passed in filter clause (AND or OR).

When str() is called on a FilterGroup instance, the combined filter items are transformed into a JSON string to be used as part of a Forensic Search or Alert query.

When dict() is called on a FilterGroup instance, the combined filter items are transformed into the Python dict equivalent of their JSON representation. This can be useful for programmatically manipulating a FilterGroup after it’s been created.

filter_clause

The clause joining the filters, such as AND or OR.

filter_list

The list of QueryFilter objects in this group.

classmethod from_dict(_dict)

Creates an instance of FilterGroup from the values found in _dict. _dict must contain keys filters and filterClause.

Parameters:_dict (dict) – A dictionary containing keys term, operator, and value.
Returns:FilterGroup
class py42.sdk.queries.query_filter.QueryFilter(term, operator, value=None)

Bases: object

Class for constructing a single filter object for use in a search query.

When str() is called on a QueryFilter instance, the (term, operator, value) attribute combination is transformed into a JSON string to be used as part of a Forensic Search or Alert query.

When dict() is called on a QueryFilter instance, the (term, operator, value) attribute combination is transformed into the Python dict equivalent of their JSON representation. This can be useful for programmatically manipulating a QueryFilter after it’s been created.

classmethod from_dict(_dict)

Creates an instance of QueryFilter from the values found in _dict. _dict must contain keys term, operator, and value.

Parameters:_dict (dict) – A dictionary containing keys term, operator, and value.
Returns:QueryFilter
operator

The operator between term and value, such as IS or IS_NOT.

term

The term of the filter, such as actor or sharedWith.

value

The value used to filter results.

class py42.sdk.queries.query_filter.QueryFilterBooleanField

Bases: object

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

classmethod is_false()

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

Returns:FilterGroup
classmethod is_true()

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

Returns:FilterGroup
class py42.sdk.queries.query_filter.QueryFilterStringField

Bases: object

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

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.query_filter.QueryFilterTimestampField

Bases: object

Helper class for creating 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
py42.sdk.queries.query_filter.create_eq_filter_group(term, value)

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

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

FilterGroup

py42.sdk.queries.query_filter.create_filter_group(query_filter_list, filter_clause)

Creates a FilterGroup object. Useful for programmatically crafting query filters, such as filters not yet defined in py42. Alternatively, if you want to create custom filter groups with already defined operators (such as IS or IS_IN), see the other methods in this module, such as create_eq_filter_group().

Parameters:
  • query_filter_list (list) – a list of QueryFilter objects.
  • filter_clause (str) – The clause joining the filters, such as AND or OR.
Returns:

FilterGroup

py42.sdk.queries.query_filter.create_in_range_filter_group(term, start_value, end_value)

“Creates a FilterGroup for filtering results where the value with key term is in the given range. Examples include values describing dates. Useful for creating a combination of ON_OR_AFTER and ON_OR_BEFORE filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters:
  • term – (str): The term of the filter, such as eventTimestamp.
  • start_value (str or int) – The start value used to filter results.
  • end_value (str or int) – The end value used to filter results.
Returns:

FilterGroup

py42.sdk.queries.query_filter.create_is_in_filter_group(term, value_list)

“Creates a FilterGroup for filtering results where the value with key term is one of several values. Useful for creating IS_IN filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters:
  • term – (str): The term of the filter, such as actor or sharedWith.
  • value_list (list) – The list of values to match on.
Returns:

FilterGroup

py42.sdk.queries.query_filter.create_not_eq_filter_group(term, value)

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

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

FilterGroup

py42.sdk.queries.query_filter.create_not_in_filter_group(term, value_list)

“Creates a FilterGroup for filtering results where the value with key term is not one of several values. Useful for creating NOT_IN filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters:
  • term – (str): The term of the filter, such as actor or sharedWith.
  • value_list (list) – The list of values to exclude on.
Returns:

FilterGroup

py42.sdk.queries.query_filter.create_on_or_after_filter_group(term, value)

“Creates a FilterGroup for filtering results where the value with key term is on or after the given value. Examples include values describing dates. Useful for creating ON_OR_AFTER filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters:
  • term – (str): The term of the filter, such as eventTimestamp.
  • value (str or int) – The value used to filter results.
Returns:

FilterGroup

py42.sdk.queries.query_filter.create_on_or_before_filter_group(term, value)

“Creates a FilterGroup for filtering results where the value with key term is on or before the given value. Examples include values describing dates. Useful for creating ON_OR_BEFORE filters that are not yet supported in py42 or programmatically crafting filter groups.

Parameters:
  • term – (str): The term of the filter, such as eventTimestamp.
  • value (str or int) – The value used to filter results.
Returns:

FilterGroup

py42.sdk.queries.query_filter.create_query_filter(term, operator, value=None)

Creates a QueryFilter object. Useful for programmatically crafting query filters, such as filters not yet defined in py42.

Parameters:
  • term (str) – The term of the filter, such as actor or sharedWith.
  • operator (str) – The operator between term and value, such as IS or IS_NOT.
  • value (str) – The value used to filter results.
Returns:

QueryFilter

py42.sdk.queries.query_filter.create_within_the_last_filter_group(term, value)

Returns a FilterGroup that is useful for finding results where the key term is an EventTimestamp._term and the value is one of the EventTimestamp attributes as value.

Parameters:value (str) – EventTimestamp attribute.
Returns:FilterGroup