Deviance

Methods described in this section relate to the deviance API. These methods can be accessed at TenableIE.deviance.

class DevianceAPI(api: APISession)

get_history_details(infrastructure_id: str, directory_id: str, deviance_id: str) → Dict

Retrieve ad-object-deviance-history instance by id.

Parameters:

• infrastructure_id (str) – The infrastructure instance identifier.

• directory_id (str) – The directory instance identifier.

• deviance_id (str) – The deviance identifier.

Returns:

The deviance object.

Return type:

dict

Example

>>> tie.deviance.history_details(
...     infrastructure_id='1',
...     directory_id='1',
...     deviance_id='1'
...     )

list(infrastructure_id: str, directory_id: str, **kwargs) → List[Dict] | DevianceIterator

Retrieve all deviances for a directory

Parameters:

• infrastructure_id (str) – The infrastructure instance identifier.

• directory_id (str) – The directory instance identifier.

• page (optional, int) – The page number user wants to retrieve.

• per_page (optional, int) – The number of records per page user wants to retrieve.

• batch_size (optional, int) – The total number of records user wants to retrieve.

• last_identifier_seen (optional, int) – The deviance identifier after which the deviance should be considered.

• resolved (optional, bool) – is the deviance resolved?

• max_items (optional, int) – The maximum number of items to return before stopping iteration.

• max_pages (optional, int) – The maximum number of pages to request before throwing stopping iteration.

Returns:

An iterator that handles the page management of the requested records.

Return type:

list[dict] or DevianceIterator

Examples

return an iterator to loop through all records

>>> for deviance in tie.deviance.list(
...     infrastructure_id='1',
...     directory_id='1',
...     resolved=True,
...     last_identifier_seen=1,
...     page=1,
...     per_page=10,
...     max_pages=11,
...     max_items=100
...     ):
...     pprint(deviance)

return a list of requested records using batch_size

>>> tie.deviance.list(
...     infrastructure_id='1',
...     directory_id='1',
...     resolved=True,
...     last_identifier_seen=1,
...     batch_size=100
...     )

list_by_checker(profile_id: str, checker_id: str, expression: Mapping, **kwargs) → List[Dict] | DevianceIterator

Retrieve all deviances by checker

Parameters:

• profile_id (str) – The profile instance identifier.

• checker_id (str) – The checker instance identifier.

• expression (mapping) – An object describing a filter for searched items.

• batch_size (optional, int) – The total number of records user wants to retrieve.

• last_identifier_seen (optional, int) – The deviance identifier after which the deviance should be considered.

• page (optional, int) – The page number user wants to retrieve.

• per_page (optional, int) – The number of records per page user wants to retrieve.

• max_items (optional, int) – The maximum number of items to return before stopping iteration.

• max_pages (optional, int) – The maximum number of pages to request before throwing stopping iteration.

Returns:

An iterator that handles the page management of the requested records.

Return type:

list[dict] or DevianceIterator

Examples

return an iterator to loop through all records

>>> for deviance in tie.deviance.list_by_checker(
...     profile_id='1',
...     checker_id='1',
...     expression={'OR': [{
...         'whencreated': '2021-07-29T12:27:50.0000000Z'
...     }]},
...     last_identifier_seen=1,
...     page=1,
...     per_page=10,
...     max_pages=11,
...     max_items=100
...     ):
...     pprint(deviance)

return a list of requested records using batch_size

>>> tie.deviance.list_by_checker(
...     profile_id='1',
...     checker_id='1',
...     expression={'OR': [{
...         'whencreated': '2021-07-29T12:27:50.0000000Z'
...     }]},
...     last_identifier_seen=1,
...     batch_size=100
...     )

list_by_directory_and_checker(profile_id: str, infrastructure_id: str, directory_id: str, checker_id: str, **kwargs) → DevianceIterator

Retrieve all deviances related to a single directory and checker

Parameters:

• profile_id (str) – The profile instance identifier.

• infrastructure_id (str) – The infrastructure instance identifier.

• directory_id (str) – The directory instance identifier.

• checker_id (str) – The checker instance identifier.

• page (optional, str) – The page number user wants to retrieve.

• per_page (optional, str) – The number of records per page user wants to retrieve.

• max_items (optional, int) – The maximum number of items to return before stopping iteration.

• max_pages (optional, int) – The maximum number of pages to request before throwing stopping iteration.

Returns:

An iterator that handles the page management of the requested records.

Return type:

DevianceIterator

Examples

>>> for deviance in tie.deviance.list_by_directory_and_checker(
...     profile_id='1',
...     infrastructure_id='1',
...     dashboard_id='1',
...     checker_id='1',
...     page=1,
...     per_page=10,
...     max_pages=11,
...     max_items=100
...     ):
...     pprint(deviance)

search(profile_id: str, checker_id: str, ad_object_id: str, show_ignored: bool, **kwargs) → DevianceIterator

Search all deviances by profile by checker by AD object.

Parameters:

• profile_id (str) – The profile instance identifier.

• checker_id (str) – The checker identifier.

• ad_object_id (str) – The AD object identifier.

• show_ignored (bool) – Whether ignored deviances should be included?

• date_start (optional, str(datetime)) – The date after which the deviances should have been emitted.

• date_end (optional, str(datetime)) – The date before which the deviances should have been emitted.

• page (optional, int) – The page number user wants to retrieve.

• per_page (optional, int) – The number of records per page user wants to retrieve.

• max_items (optional, int) – The maximum number of items to return before stopping iteration.

• max_pages (optional, int) – The maximum number of pages to request before throwing stopping iteration.

Returns:

An iterator that handles the page management of the requested records.

Return type:

DevianceIterator

Example

>>> for deviance in tie.deviance.search(
...     profile_id='1',
...     checker_id='1',
...     ad_object_id='1',
...     show_ignored=True,
...     page=1,
...     per_page=10,
...     max_pages=11,
...     max_items=100
...     ):
...     pprint(deviance)

update_by_checker(profile_id: str, checker_id: str, ignore_until: str) → None

Update instances matching a checker id.

Parameters:

• profile_id (str) – The profile instance identifier.

• checker_id (str) – The checker instance identifier.

• ignore_until (str(datetime)) – Ignore deviance until defined date.

Return type:

None

Example

>>> tie.deviance.update_by_checker(
...     profile_id='1',
...     checker_id='1',
...     ignore_until='2022-01-27T23:59:59.999Z'
...     )

update_history_details(infrastructure_id: str, directory_id: str, deviance_id: str, **kwargs) → Dict

Retrieve ad-object-deviance-history instance by id.

Parameters:

• infrastructure_id (str) – The infrastructure instance identifier.

• directory_id (str) – The directory instance identifier.

• deviance_id (str) – The deviance identifier.

• ignore_until (optional, str(datetime)) – Ignore deviance until defined date.

Returns:

The deviance object.

Return type:

dict

Example

>>> tie.deviance.history_details(
...     infrastructure_id='1',
...     directory_id='1',
...     deviance_id='1',
...     ignore_until='2022-01-27T23:59:59.999Z'
...     )

update_on_ado_and_checker(profile_id: str, checker_id: str, ad_object_id: str, ignore_until: str) → None

Update the deviances emitted on a specific AD object and for specific checker.

Parameters:

• profile_id (str) – the profile instance identifier.

• checker_id (str) – The checker instance identifier.

• ad_object_id (str) – The AD object instance identifier.

• ignore_until (str(datetime)) – Ignore deviance until defined date.

Return type:

None

Example

>>> tie.deviance.update_on_ado_and_checker(
...     profile_id='1',
...     checker_id='1',
...     ad_object_id='1',
...     ignore_until='2022-01-27T23:59:59.999Z'
...     )