Alerts¶

The following methods allow for interaction into the Tenable.sc Alert API.

Methods available on sc.alerts:

class AlertAPI(api: restfly.session.APISession)[source]¶

create(*filters, **kw)[source]¶

Creates a new alert. The fields below are explicitly checked, however any additional parameters mentioned in the API docs can be passed to the document constructor.

Sc-api:’alert

create <Alert.html#alert_POST>`

Parameters

*filters (tuple) – A filter expression. Refer to the detailed description within the analysis endpoint documentation for more details on how to formulate filter expressions.
data_type (str) – The type of filters being used. Must be of type lce, ticket, user, or vuln. If no data-type is specified, then the default of vuln will be set.
name (str) – The name of the alert.
description (str, optional) – A description for the alert.
trigger (tuple) – A tuple in the filter-tuple format detailing what would constitute a trigger. For example: ('sumip', '=', '1000').
always_exec_on_trigger (bool, optional) – Should the trigger always execute when the trigger fires, or only execute when the returned data changes? Default is False.
schedule (dict, optional) – This is the schedule dictionary that will inform Tenable.sc how often to run the alert. If left unspecified then we will default to {'type': 'never'}.

action (list) –

The action(s) that will be performed when the alert trigger fires. Each action is a dictionary detailing what type of action to take, and the details surrounding that action. The supported type of actions are email, notifications, report, scan, syslog, and ticket. The following examples lay out each type of action as an example:

Email action type:

{'type': 'email',
 'subject': 'Example Email Subject',
 'message': 'Example Email Body'
 'addresses': 'user1@company.com\nuser2@company.com',
 'users': [{'id': 1}, {'id': 2}],
 'includeResults': 'true'}

Notification action type:

{'type': 'notification',
 'message': 'Example notification',
 'users': [{'id': 1}, {'id': 2}]}

Report action type:

{'type': 'report',
 'report': {'id': 1}}

Scan action type:

{'type': 'scan',
 'scan': {'id': 1}}

Syslog action type:

{'type': 'syslog',
 'host': '127.0.0.1',
 'port': '514',
 'message': 'Example Syslog Message',
 'severity': 'Critical'}

Ticket action type:

{'type': 'ticket',
 'assignee': {'id': 1},
 'name': 'Example Ticket Name',
 'description': 'Example Ticket Description',
 'notes': 'Example Ticket Notes'}

Returns

The alert resource created.

Return type

dict

Examples

>>> sc.alerts.create(
...     ('severity', '=', '3,4'),
...     ('exploitAvailable', '=', 'true'),
...     trigger=('sumip', '>=', '100'),
...     name='Too many High or Critical and Exploitable',
...     action=[{
...         'type': 'notification',
...         'message': 'Too many High or Crit Exploitable Vulns',
...         'users': [{'id': 1}]
...     }])

delete(id)[source]¶

Deletes the specified alert.

alert: delete

Parameters: id (int) – The alert identifier.
Returns: The response code of the action.
Return type: str

Examples

>>> sc.alerts.delete(1)

details(id, fields=None)[source]¶

Returns the details for a specific alert.

alert: details

Parameters

id (int) – The identifier for the alert.
fields (list, optional) – A list of attributes to return.

Returns

The alert resource record.

Return type

dict

Examples

>>> alert = sc.alerts.detail(1)
>>> pprint(alert)

edit(id, *filters, **kw)[source]¶

Updates an existing alert. All fields are optional and will overwrite the existing value.

alert: update

Parameters

if (int) – The alert identifier.
*filters (tuple) – A filter expression. Refer to the detailed description within the analysis endpoint documentation for more details on how to formulate filter expressions.
data_type (str) – The type of filters being used. Must be of type lce, ticket, user, or vuln. If no data-type is specified, then the default of vuln will be set.
name (str, optional) – The name of the alert.
description (str, optional) – A description for the alert.
trigger (tuple, optional) – A tuple in the filter-tuple format detailing what would constitute a trigger. For example: ('sumip', '=', '1000').
always_exec_on_trigger (bool, optional) – Should the trigger always execute when the trigger fires, or only execute when the returned data changes? Default is False.
schedule (dict, optional) – This is the schedule dictionary that will inform Tenable.sc how often to run the alert. If left unspecified then we will default to {'type': 'never'}.
action (list) – The action(s) that will be performed when the alert trigger fires. Each action is a dictionary detailing what type of action to take, and the details surrounding that action.

Returns

The modified alert resource.

Return type

dict

Examples

>>> sc.alerts.update(1, name='New Alert Name')

execute(id)[source]¶

Executes the specified alert.

alert: execute

Parameters: id (int) – The alert identifier.
Returns: The alert resource.
Return type: dict

list(fields=None)[source]¶

Retrieves the list of alerts.

alert: list

Parameters: fields (list, optional) – A list of attributes to return for each alert.
Returns: A list of alert resources.
Return type: dict

Examples

>>> for alert in sc.alerts.list()['manageable']:
...     pprint(alert)