Skip to content

Alert Querying

Use the AlertQuery class to create a query for searching and filtering Incydr alerts. More details on how to use the AlertQuery class can be found in the Query Building section below.

class _incydr_sdk.queries.alerts.AlertQuery(start_date=None, end_date=None, on=None, *, tenantId=None, groupClause='AND', groups=None, pgNum=0, pgSize=100, srtDirection='DESC', srtKey='CreatedAt', **kwargs)

Class to build an alert query. Use the class methods to attach additional filter operators.

Usage examples:

Construct a query that finds all alerts created in the past 10 days that are now marked RESOLVED:

>>> import incydr
>>> from datetime import timedelta
>>> from incydr.enums.alerts import AlertState, AlertTerm
>>> query = incydr.AlertQuery(start_date=timedelta(days=10)).equals(AlertTerm.STATE, AlertState.RESOLVED)

Construct a query that finds alerts triggered by actor user@example.com with a risk severity of either HIGH or CRITICAL:

>>> import incydr
>>> query = incydr.AlertQuery().equals("Actor", "user@example.com").equals("RiskSeverity", ["HIGH", "CRITICAL"])

Parameters:

  • start_date: int | float | str | datetime | timedelta - Start of the date range to query for alerts. Accepts int|float unix timestamp, string representation of the date (%Y-%m-%d %H:%M:%S or %Y-%m-%d formats), or datetime object for absolute dates, or if a timedelta is provided it will be relative to the current time when the query object was instantiated. Defaults to None.
  • end_date: int | float | str | datetime - End of the date range to query for alerts. Defaults to None.
  • on: str | date | datetime - Retrieve alerts that occurred on a specific date (incompatible with either start_date or end_date arguments).
equals(self, term, values)

Adds an equals filter to the query. The opposite of the not_equals filter.

Causes the query to return alerts where the field corresponding to the term equals the indicated value(s).

Example: AlertQuery().equals('Status', 'PENDING') will return all alerts with a status of 'PENDING'.

Parameters:

  • term: str - The term which corresponds to an alert field. List of valid terms can be found in the incydr.enums.alerts.AlertTerm enum object.
  • values: str, List[str] - The value(s) for the term to match.
not_equals(self, term, values)

Adds an not_equals filter to the query. The opposite of the equals filter.

When passed as part of a query, returns alerts where the field corresponding to the filter term does not equal the indicated value(s).

Example: AlertQuery().not_equals('State', 'RESOLVED') creates a query which will return alerts that are not in a RESOLVED state.

Parameters:

  • term: str - The term which corresponds to an alert field.
  • values: str, List[str] - The value(s) for the term to not match.
contains(self, term, value)

Adds a contains filter to the query. The opposite of the does_not_contain filter.

When passed as part of a query, returns alerts where the field corresponding to the filter term contains the provided string value.

Example: AlertQuery().contains('Description', 'removable media') creates a query which will return alerts where the alert rule description contains the string "removable media".

Parameters:

  • term: str - The term which corresponds to an alert field.
  • value: str - The value for the term to match.
does_not_contain(self, term, value)

Adds a does_not_contain filter to the query. The opposite of the contains filter.

When passed as part of a query, returns alerts where the field corresponding to the filter term does not contain the provided string value.

Example: AlertQuery().does_not_contain('Description', 'removable media') creates a query which will return alerts where the alert rule description does not contain the string "removable media".

Parameters:

  • term: str - The term which corresponds to an alert field.
  • value: str - The value for the term to not match.
matches_any(self)

Sets operator to combine multiple filters with OR.

Returns alerts that match at least one of the filters in the query.

Default operator is AND, which returns only alerts that match all filters in the query.

Query Building

The AlertQuery class can be imported directly from the incydr module.

# import the AlertQuery class
from incydr import AlertQuery

The AlertQuery class can be constructed with arguments to define the date range for the query. The start_date argument sets the beginning of the date range to query, it can accept the following:

  • a Unix epoch timestamp as an int or float
  • a string representation of the date in either %Y-%m-%d %H:%M:%S or %Y-%m-%d formats.
  • a datetime.datetime object
  • a datetime.timedelta (converts to datetime relative to the current time when the query object was instantiated)

The end_date argument sets the (optional) end of the range to query, and accepts the same arguments as start_date.

The on argument tells the alerts service to retrieve all alerts created on the date given, it accepts: - a datetime.date or datetime.datetime object (date value will be extracted from datetime and hour/minute/seconds data will be discarded) - a string representation of a date in either %Y-%m-%d %H:%M:%S or %Y-%m-%d formats (again if time data is supplied it will have no effect on the query)

To create a query which filters alerts which have a state of OPEN or PENDING and were created in the past 3 days: 

query = AlertQuery(start_date=timedelta(days=3)).equals('State', ['OPEN', 'PENDING'])

All filter methods take a term string as their first argument, which indicates which field to filter on (ex: 'RiskSeverity'), and the second arg is the value (or list of values) to search for.

The following filter methods are available: * .equals(term, value) * .not_equals(term, value) * .contains(term, value) * .does_not_contain(term, value)

By default, all filters in a query will be combined in an AND group, meaning only results matching all filters will be returned. If you want to OR the filters, call the .matches_any() method on the query.

Pass the event constructed query object to the client.alerts.v1.search() method to get execute the search.

Pagination

If a query results in more results than the configured page size of the query (max page size is 500), increment the .page_num value of the query and re-run the .search() method:

from datetime import timedelta
from incydr import Client, AlertQuery

client = Client(**kwargs)

query = AlertQuery(start_date=timedelta(days=10))
first_page = client.alerts.v1.search(query)
if first_page.total_count > query.page_size:
    query.page_num += 1
second_page = client.alerts.v1.search(query)
...  # continue until all alerts are retrieved

Alternately, the client.alerts.v1.iter_all() method will automatically request pages until all the results are complete and will yield each Alert individually, so you don't need to think about paging at all:

from datetime import timedelta
import incydr
client = incydr.Client(**kwargs)

query = incydr.AlertQuery(start_date=timedelta(days=10))
for alert in client.alerts.v1.iter_all(query):
    ... # process alert here