Findings¶

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

class FindingsAPI(api: APISession)[source]¶

Retrieve findings

Args:

page_number (optional, int):
For offset-based pagination, the requested page to retrieve. If this parameter is omitted, Tenable uses the default value of 1.

next_token (optional, str):
For cusrsor-based pagination, the cursor position for the next page. For the initial request, don’t populate. For subsequent requests, set this parameter to the value found in the next property of the previous response. When getting null without specify a page number it means there are no more pages.

limit (optional, int):
The number of records to retrieve. If this parameter is omitted, Tenable uses the default value of 50. The maximum number of events that can be retrieved is 10,000. For example: limit=10000.

filter (optional, dict):
A document as defined by Tenable APA online documentation. Filters to allow the user to get to a specific subset of Findings. For a more detailed listing of what filters are available, please refer to the API documentation linked above, however some examples are as such:

{"operator":"==", "key":"state", "value":"open"}

{"operator":">", "key":"last_updated_at", "value":"2024-05-30T12:28:11.528118"}

sort_filed (optional, str):
The field you want to use to sort the results by. Accepted values are last_updated_at, state, vectorCount, status, name, procedureName, priority, and mitre_id.

sort_order (optional, str):
The sort order Accepted values are desc or acs

return_iterator (bool, optional):
Should we return the response instead of iterable?

Returns:

List of findings records

Return type:

FindingIterator

Examples:

>>> findings = tapa.findings.list()
>>> for f in findings:
...     pprint(f)

Examples:

>>> tapa.findings.list(
...     limit='10',
...     sort_filed='last_updated_at',
...     sort_order='desc',
...     filter='value',
...     return_iterator=False
...     )

Search attack techniques

Parameters:

filters (optional, dict) – Filter conditions for searching attack techniques. Supports complex filtering with AND/OR operators. Examples: - {"operator":"==", "property":"priority", "value":"high"} - {"operator":"and", "value":[{"operator":"==", "property":"priority", "value":"high"}, {"operator":"==", "property":"state", "value":"open"}]}
offset (optional, int) – Number of items to skip for pagination. If omitted, the default value is 0.
limit (optional, int) – Number of items per page. If omitted, the default value is 1000. The minimum value is 100 and the maximum value is 10000.
sort (optional, str) –
Sort parameter in format “{sort_field}:{sort_order}” with multiple variations: - Ascending: “asc”, “ASC”, “ascending”, “ASCENDING”, “Ascending” - Descending: “desc”, “DESC”, “descending”, “DESCENDING”, “Descending” - Examples: “priority:desc”, “name:asc”, “last_updated_at:ASCENDING”, “state:DESCENDING”

Supported sort fields: last_updated_at, priority, mitre_id, name, procedureName, status, state, vectorCount
exclude_resolved (bool, optional) – When True (default), excludes techniques with status ‘done’ or ‘accepted’ and state ‘archive’. Set to False to include all techniques.
return_iterator (bool, optional) – Should we return the response instead of iterable?

Returns:

List of attack technique records

Return type:

FindingIterator or dict

Examples

>>> attack_techniques = tapa.findings.search_attack_techniques()
>>> for technique in attack_techniques:
...     pprint(technique)

Examples

>>> tapa.findings.search_attack_techniques(
...     limit=100,
...     sort='priority:desc',
...     filters={'operator': '==', 'property': 'priority', 'value': 'high'},
...     return_iterator=False
... )

Include resolved techniques:

>>> tapa.findings.search_attack_techniques(
...     exclude_resolved=False,
...     return_iterator=False
... )