Scans

The following methods allow for interaction into the Tenable Security Center Scan API. While the api endpoints obliquely refers to the model in which this collection of actions modifies as “Scans”, Tenable Security Center is actually referring to the scan definitions, which are the un-launched and/or scheduled scans typically seen within the Active Scans section within Tenable Security Center.

Methods available on sc.scans:

class ScanAPI(api: restfly.session.APISession)[source]
copy(id, name, user_id)[source]

Copies an existing scan definition.

scan: copy

Parameters

  • id (int) – The scan definition identifier to copy.

  • name (str) – The name of the copy that’s created.

  • user_id (int) – The user id to assign as the owner of the new scan definition.

Returns

Scan definition resource.

Return type

dict

Examples

>>> sc.scans.copy(1, name='Cloned Scan')
create(name, repo, **kw)[source]

Creates a scan definition.

scan: create

Parameters

  • name (str) – The name of the scan.

  • repo (int) – The repository id for the scan.

  • auto_mitigation (int, optional) – How many days to hold on to data before mitigating it? The default value is 0.

  • asset_lists (list, optional) – A list of asset list ids to run the scan against. A logical OR will be performed to compute what hosts to scan against.

  • creds (list, optional) – A list of credential ids to use for the purposes of this scan. This list should be treated as an un-ordered list of credentials.

  • description (str, optional) – A description for the scan.

  • email_complete (bool, optional) – Should we notify the owner upon completion of the scan? The default is False.

  • email_launch (bool, optional) – Should we notify the owner upon launching the scan? The default is False.

  • host_tracking (bool, optional) – Should DHCP host tracking be enabled? The default is False.

  • max_time (int, optional) – The maximum amount of time that the scan may run in seconds. 0 or less for unlimited. The default is 3600 seconds.

  • policy_id (int, optional) – The policy id to use for a policy-based scan.

  • reports (list, optional) – What reports should be run upon completion of the scan? Each report dictionary requires an id for the report definition and the source for which to run the report against. Example: {'id': 1, 'reportSource': 'individual'}.

  • rollover (str, optional) – How should rollover scans be created (assuming the scan is configured to create a rollover scan with the timeout action). The available actions are to automatically start the nextDay at the same time the scan was originally configured to run, and to generate a rollover template. The default action is to generate a template.

  • scan_zone (int, optional) – The zone identifier to use for the scan. If non is selected then the default of “0” or “All Zones” is selected.

  • schedule (dict, optional) – A dictionary detailing the repeating schedule of the scan.

  • targets (list, optional) – A list of valid targets. These targets could be IPs, FQDNs, CIDRs, or IP ranges.

  • timeout (str, optional) – How should an incomplete scan be handled? The available actions are discard, import, and rollover. The default action is import.

  • vhosts (bool, optional) – Should virtual host logic be enabled for the scan? The default is False.

  • inactivity_timeout (int) – Inactivity Timeout in seconds. The value should be between 3600 and 432000.

Returns

The scan resource for the created scan.

Return type

dict

Examples

Creating a scan for a single host:

>>> sc.scans.create('Example scan', 1, policy_id=1001,
...     targets=['127.0.0.1'])
delete(id)[source]

Removes the specified scan from SecurityCenter.

scan: delete

Parameters

id (int) – The identifier for the scan to delete.

Returns

The list of scan id removed.

Return type

list

Examples

>>> sc.scans.delete(1)
details(id, fields=None)[source]

Returns the details for a specific scan.

scan: details

Parameters

  • id (int) – The identifier for the scan.

  • fields (list, optional) – A list of attributes to return.

Returns

The scan resource record.

Return type

dict

Examples

>>> scan = sc.scans.detail(1)
>>> pprint(scan)
edit(id, **kw)[source]

Edits an existing scan definition.

scan: update

Parameters

  • id (int) – The identifier for the scan.

  • auto_mitigation (int, optional) – How many days to hold on to data before mitigating it?

  • asset_lists (list, optional) – A list of asset list ids to run the scan against. A logical OR will be performed to compute what hosts to scan against.

  • creds (list, optional) – A list of credential ids to use for the purposes of this scan. This list should be treated as an un-ordered list of credentials.

  • description (str, optional) – A description for the scan.

  • email_complete (bool, optional) – Should we notify the owner upon completion of the scan?

  • email_launch (bool, optional) – Should we notify the owner upon launching the scan?

  • host_tracking (bool, optional) – Should DHCP host tracking be enabled?

  • max_time (int, optional) – The maximum amount of time that the scan may run in seconds. 0 or less for unlimited.

  • name (str, optional) – The name of the scan.

  • policy_id (int, optional) – The policy id to use for a policy-based scan.

  • plugin_id (int, optional) – The plugin id to use for a plugin-based scan.

  • reports (list, optional) – What reports should be run upon completion of the scan? Each report dictionary requires an id for the report definition and the source for which to run the report against. Example: {'id': 1, 'reportSource': 'individual'}.

  • repo (int, optional) – The repository id for the scan.

  • rollover (str, optional) – How should rollover scans be created (assuming the scan is configured to create a rollover scan with the timeout action). The available actions are to automatically start the nextDay at the same time the scan was originally configured to run, and to generate a rollover template.

  • scan_zone (int, optional) – The zone identifier to use for the scan.

  • schedule (dict, optional) – A dictionary detailing the repeating schedule of the scan.

  • targets (list, optional) – A list of valid targets. These targets could be IPs, FQDNs, CIDRs, or IP ranges.

  • timeout (str, optional) – How should an incomplete scan be handled? The available actions are discard, import, and rollover.

  • vhosts (bool, optional) – Should virtual host logic be enabled for the scan?

Returns

The scan resource for the created scan.

Return type

dict

Examples

Editing an existing scan’s name:

>>> sc.scans.edit(1, name='Example scan')
launch(id, diagnostic_target=None, diagnostic_password=None)[source]

Launches a scan definition.

scan: launch

Parameters

  • id (int) – The scan definition identifier to launch.

  • diagnostic_target (str, optional) – A valid IP or hostname to launch a diagnostic scan against. The diagnostic_password must also be specified or else this parameter will be ignored.

  • diagnostic_password (str, optional) – A password to use for the diagnostic scan. The diagnostic_target must also be specified or else this parameter will be ignored.

Returns

A scan result resource for the newly launched scan.

Return type

dict

Examples

>>> running = sc.scans.launch(1)
>>> print('The Scan Result ID is {}'.format(
...     running['scanResult']['id']))
list(fields=None)[source]

Retrieves the list of scan definitions.

scan: list

Parameters

fields (list, optional) – A list of attributes to return for each scan.

Returns

A list of scan resources.

Return type

list

Examples

>>> for scan in sc.scans.list():
...     pprint(scan)