Scans¶

The following methods allow for interaction into the Tenable Vulnerability Management scans API endpoints.

Methods available on tio.scans:

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

This will contain all methods related to scans

attachment(scan_id, attachment_id, key, fobj=None)[source]¶

Retrieve an attachment associated to a scan.

scans: attachments

Parameters

scan_id (int) – The unique identifier for the scan.
attachment_id (int) – The unique identifier for the attachment
key (str) – The attachment access token.
fobj (FileObject, optional) – a file-like object you wish for the attachment to be written to. If none is specified, a BytesIO object will be returned with the contents of the attachment.

Returns

A file-like object with the attachment written into it.

Return type

FileObject

Examples

>>> with open('example.file', 'wb') as fobj:
...     tio.scans.attachment(1, 1, 'abc', fobj)

check_auto_targets(limit, matched_resource_limit, network_uuid=None, tags=None, targets=None)[source]¶

Evaluates a list of targets and/or tags against the scan route configuration of scanner groups.

scan: check-auto-targets

Parameters

limit (int) – Limit the number of missed targets returned in the response.
matched_resource_limit (int) – Limit the number of matched resource UUIDs returned in the response.
network_uuid (uuid, optional) – The UUID of the network.
tags (list, optional) – A list of asset tags UUIDs.
targets (list, optional) – A list of valid targets.

Returns

Return the list of missed targets (if any), and the list of matched scanner groups (if any).

Return type

dict

Examples

>>> scan_routes_info = tio.scans.check_auto_targets(10, 5, targets=['127.0.0.1'])

configure(scan_id, **kw)[source]¶

Overwrite the parameters specified on top of the existing scan record.

scans: configure

Parameters

scan_id (int) – The unique identifier for the scan.
template (str, optional) – The scan policy template to use. If no template is specified then the default of basic will be used.
policy (int, optional) – The id or title of the scan policy to use (if not using one of the pre-defined templates). Specifying a a policy id will override the the template parameter.
targets (list, optional) – If defined, then a list of targets can be specified and will be formatted to an appropriate text_target attribute.
credentials (dict, optional) – A list of credentials to use.
compliance (dict, optional) – A list of compliance audiots to use.
scanner (str, optional) – Define the scanner or scanner group uuid or name.
schedule_scan (dict, optional) – Define updated schedule for scan
**kw (dict, optional) – The various parameters that can be passed to the scan creation API. Examples would be name, email, scanner_id, etc. For more detailed information, please refer to the API documentation linked above. Further, any keyword arguments passed that are not explicitly documented will be automatically appended to the settings document. There is no need to pass settings directly.

Returns

The scan resource record.

Return type

dict

Examples

>>> tio.scans.configure(1, name='New Scan Name')

# configure a schedule for existing scan

>>> configure_schedule = api.scans.configure_scan_schedule(1, interval=2)
>>> tio.scans.configure(1, schedule_scan=configure_schedule)

configure_scan_schedule(scan_id, enabled=None, frequency=None, interval=None, weekdays=None, day_of_month=None, starttime=None, timezone=None)[source]¶

Create dictionary of keys required for scan schedule

Parameters

scan_id (int) – The id of the Scan object in Tenable Vulnerability Management
enabled (bool, optional) – To enable/disable scan schedule
frequency (str, optional) – The frequency of the rule. The string inputted will be up-cased. Valid values are: ONETIME, DAILY, WEEKLY, MONTHLY, YEARLY. Default value is ONETIME.
interval (int, optional) – The interval of the rule. The default interval is 1
weekdays (list, optional) – List of 2-character representations of the days of the week to repeat the frequency rule on. Valid values are: SU, MO, TU, WE, TH, FR, SA Default values: ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA']
day_of_month (int, optional) – The day of the month to repeat a MONTHLY frequency rule on. The default is today.
starttime (datetime, optional) – When the scan should start.
timezone (str, optional) – The timezone to use for the scan. The default if none is specified is to use UTC. For the list of usable timezones, please refer to devportalscans-timezones

Returns

Dictionary of the keys required for scan schedule.

Return type

dict

copy(scan_id, folder_id=None, name=None)[source]¶

Duplicates a scan and returns the details of the copy.

scans: copy

Parameters

scan_id (int) – The unique identifier for the scan.
folder_id (int, optional) – The unique identifier for the folder.
name (str, optional) – The name for the copied scan.

Returns

The scan resource record for the copied scan.

Return type

dict

Examples

>>> new_scan = tio.scans.copy(1, 'New Scan Name')

create(**kw)[source]¶

Create a new scan.

scans: create

Parameters

name (str) – The name of the scan to create.
template (str, optional) – The scan policy template to use. If no template is specified then the default of basic will be used.
policy (int, optional) – The id or title of the scan policy to use (if not using one of the pre-defined templates). Specifying a a policy id will override the the template parameter.
targets (list, optional) – If defined, then a list of targets can be specified and will be formatted to an appropriate text_target attribute.
credentials (dict, optional) – A list of credentials to use.
compliance (dict, optional) – A list of compliance audits to use.
scanner (str, optional) – Define the scanner or scanner group uuid or name.
schedule_scan (dict, optional) – Define schedule for scan
**kw (dict, optional) – The various parameters that can be passed to the scan creation API. Examples would be name, email, scanner_id, etc. For more detailed information, please refer to the API documentation linked above. Further, any keyword arguments passed that are not explicitly documented will be automatically appended to the settings document. There is no need to pass settings directly.

Returns

The scan resource record of the newly created scan.

Return type

dict

Examples

Create an un-credentialed basic scan:

>>> scan = tio.scans.create(
...     name='Example Scan',
...     targets=['127.0.0.1'])

Creating a scan with a set of managed credentials:

>>> scan = tio.scans.create(
...     name='Example Managed Cred Scan',
...     targets=['127.0.0.1'],
...     credentials={'Host': {'SSH': [{'id': 'CREDENTIAL-UUID'}]}}

Creating a scan with a set of embedded credentials:

>>> scan = tio.scans.create(
...     name='Example Embedded Cred Scan',
...     targets=['127.0.0.1'],
...     credentials={'Host': {'Windows': [{
...         'domain': '',
...         'username': 'Administrator',
...         'password': 'sekretsquirrel',
...         'auth_method': 'Password'
...     }]}}
... )

Create an un-credentialed basic scheduled scan:

>>> schedule = api.scans.create_scan_schedule(
...     enabled=True, frequency='daily', interval=2, starttime=datetime.utcnow())
>>> scan = tio.scans.create(
...     name='Example Scan',
...     targets=['127.0.0.1']
...     schedule_scan=schedule)

For further information on credentials, what settings to use, etc, refer to this doc on the developer portal.

create_scan_schedule(enabled=False, frequency=None, interval=None, weekdays=None, day_of_month=None, starttime=None, timezone=None)[source]¶

Create dictionary of keys required for scan schedule

Parameters

enabled (bool, optional) – To enable/disable scan schedule
frequency (str, optional) – The frequency of the rule. The string inputted will be up-cased. Valid values are: ONETIME, DAILY, WEEKLY, MONTHLY, YEARLY. Default value is ONETIME.
interval (int, optional) – The interval of the rule. The default interval is 1
weekdays (list, optional) – List of 2-character representations of the days of the week to repeat the frequency rule on. Valid values are: SU, MO, TU, WE, TH, FR, SA Default values: ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA']
day_of_month (int, optional) – The day of the month to repeat a MONTHLY frequency rule on. The default is today.
starttime (datetime, optional) – When the scan should start.
timezone (str, optional) – The timezone to use for the scan. The default if none is specified is to use UTC. For the list of usable timezones, please refer to devportalscans-timezones

Returns

Dictionary of the keys required for scan schedule.

Return type

dict

delete(scan_id)[source]¶

Remove a scan.

scans: delete

Parameters: scan_id (int or uuid) – The unique identifier for the scan.
Returns: The scan was successfully deleted.
Return type: None

Examples

>>> tio.scans.delete(1)

delete_history(scan_id, history_id)[source]¶

Remove an instance of a scan from a scan history.

scans: delete-history

Parameters

scan_id (int or uuid) – The unique identifier for the scan.
history_id (int or uuid) – The unique identifier for the instance of the scan.

Returns

Scan history successfully deleted.

Return type

None

Examples

>>> tio.scans.delete_history(1, 1)

details(scan_id)[source]¶

Calls the editor API and parses the scan config details to return a document that closely matches what the API expects to be POSTed or PUTed via the create and configure methods. The compliance audits and credentials are populated into the ‘current’ sub-document for the relevant resources.

Important

Please note that the details method is reverse-engineered from the responses from the editor API, and while we are reasonably sure that the response should align almost exactly to what the API expects to be pushed to it, this method by very nature of what it’s doing isn’t guaranteed to always work.

Note

If you’re looking for the results of the most recent scan, and what matches to the GET /scans/{id} call, then take a look at the results method.

Parameters: scan_id (int or uuid) – The unique identifier for the scan.
Returns: The scan configuration resource.
Return type: dict

Examples

>>> scan = tio.scans.details(1)
>>> pprint(scan)

export(scan_id, *filters, stream_hook=None, **kw)[source]¶

Export the scan report.

scans: export

Parameters

scan_id (int or uuid) – The unique identifier of the scan.
*filters (tuple, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘plugin.id’, ‘eq’, ‘19506’). For a complete list of the available filters and options, please refer to the API documentation linked above.
stream_hook (callable, optional) –
If set, send the streaming response to this callable. The callable is responsible for iterating over the stream but does not need to close the file object. The signature for the callable is:
```
def f(response: requests.Response,
      fobj: BytesIO,
      chunk_size: int) -> BytesIO:
```
history_id (int, optional) – The unique identifier for the instance of the scan.
history_uuid (uuid, optional) – The UUID for the instance of the scan.
format (str, optional) – What format would you like the resulting data to be in. The default would be nessus output. Available options are nessus, csv, html, pdf, db. Default is nessus.
password (str, optional) – If the export format is db, then what is the password used to encrypt the NessusDB file. This is a require parameter for NessusDB exports.
chapters (list, optional) – A list of the chapters to write for the report. The chapters list is only required for PDF and HTML exports. Available chapters are vuln_hosts_summary, vuln_by_host, compliance_exec, remediations, vuln_by_plugin, and compliance. List order will denote output order. Default is vuln_by_host.
filter_type (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and.
scan_type (str, optional) – This parameter is required only when using the API with Web Application Scanning. Available option is ‘web-app’.
fobj (FileObject, optional) – The file-like object to be returned with the exported data. If no object is specified, a BytesIO object is returned with the data. While this is an optional parameter, it is highly recommended to use this parameter as exported files can be quite large, and BytesIO objects are stored in memory, not on disk.

Returns

The file-like object of the requested export.

Return type

FileObject

Examples

Export the full report of the latest instance of the scan:

>>> with open('example.nessus', 'wb') as reportobj:
...     tio.scans.export(1, fobj=reportobj)

Export a specific instance of the scan:

>>> with open('example.nessus', 'wb') as reportobj:
...     tio.scans.export(1, history_id=1, fobj=reportobj)

history(scan_id, limit=None, offset=None, pages=None, sort=None)[source]¶

Get the scan history of a given scan from Tenable Vulnerability Management.

scans: history

Parameters

scan_id (int or uuid) – The unique identifier for the scan.
limit (int, optional) – The number of records to retrieve. Default is 50
offset (int, optional) – The starting record to retrieve. Default is 0.
sort (tuple, optional) – A tuple of tuples identifying the the field and sort order of the field.

Returns

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

Return type

ScanHistoryIterator

Examples

>>> for history in tio.scans.history(1):
...     pprint(history)

host_details(scan_id, host_id, history_id=None, history_uuid=None)[source]¶

Retrieve the host details from a specific scan.

scans: host-details

Parameters

scan_id (int) – The unique identifier for the scan.
host_id (int) – The unique identifier for the host within the scan.
history_id (int, optional) – The unique identifier for the instance of the scan.
history_uuid (str, optional) – The unique identifier for the scan instance.

Returns

The information related to the host requested.

Return type

dict

Examples

>>> host = tio.scans.host_details(1, 1)

import_scan(fobj, folder_id=None, password=None, aggregate=None)[source]¶

Import a scan report into Tenable Vulnerability Management.

scans: import

Parameters

fobj (FileObject) – The File-like object of the scan to import.
folder_id (int, optional) – The unique identifier for the folder to place the scan into.
password (str, optional) – The password needed to decrypt the file. This is only necessary for NessusDB files uploaded.
aggregate (bool, optional) – should the Nessus report be aggregated into the aggregate results? The default is True.

Returns

The scan resource record for the imported scan.

Return type

dict

Examples

Import a .nessusv2 report:

>>> with open('example.nessus', 'rb') as reportobj:
...     tio.scans.import(reportobj)

Import a NessusDB report.

>>> with open('example.db', 'rb') as reportobj:
...     tio.scans.import(reportobj, password='sekret')

info(scan_id, history_uuid)[source]¶

Retrieves information about the status of the specified instance of the scan.

scan: get-scan-history

Parameters

scan_id (int or uuid) – The unique identifier for the scan.
history_uuid (str) – The unique identifier for the scan instance.

Returns

The metadata about the scan instance specified.

Return type

dict

Examples

>>> info = tio.scans.info(1, 'BA0ED610-C27B-4096-A8F4-3189279AFFE7')

launch(scan_id, targets=None)[source]¶

Launches a scan.

scans: launch

Parameters

scan_id (int or uuid) – The unique identifier for the scan.
targets (list, optional) – A list of targets to be scanned instead of the default targets in the scan.

Response:

str:: The uuid of the scan instance (history).

Examples

Launch the scan with the configured targets:

>>> tio.scans.launch(1)

Launch the scan with some custom targets:

>>> tio.scans.launch(1, targets=['127.0.0.1'])

list(folder_id=None, last_modified=None)[source]¶

Retrieve the list of configured scans.

scans: list

Parameters

folder_id (int, optional) – Only return scans within this folder.
last_modified (datetime, optional) – Only return scans that have been modified since the time specified.

Returns

A list containing the list of scan resource records.

Return type

list

Examples

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

pause(scan_id, block=False)[source]¶

Pauses a running scan.

scans: pause

Parameters

scan_id (int or uuid) – The unique identifier of the scan to pause.
block (bool, optional) – Block until the scan is actually paused. Default is False.

Returns

The scan was successfully requested to be paused.

Return type

None

Examples

>>> tio.scans.pause(1)

plugin_output(scan_id, host_id, plugin_id, history_id=None, history_uuid=None)[source]¶

Retrieve the plugin output for a specific instance of a vulnerability on a host.

scans: plugin-output

Parameters

scan_id (int or uuid) – The unique identifier of the scan.
host_id (int) – The unique identifier of the scanned host.
plugin_id (int) – The plugin id.
history_id (int, optional) – The unique identifier of the scan instance.

Returns

The plugin resource record for that plugin on that host.

Return type

dict

Examples

>>> output = tio.scans.plugin_output(1, 1, 1)
>>> pprint(output)

results(scan_id, history_id=None, history_uuid=None)[source]¶

Return the scan results from either the latest scan or a specific scan instance in the history.

scans: details

Parameters

scan_id (int or uuid) – The unique identifier for the scan.
history_id (int, optional) – The unique identifier for the instance of the scan.
history_uuid (uuid, optional) – The UUID for the instance of the scan.

Returns

The scan result dictionary.

Return type

dict

Examples

Retrieve the latest results:

>>> results = tio.scans.results(419)

Retrieve a specific instance of the result set using history_id:

>>> results = tio.scans.results(419, history_id=15184619)

Retrieve a specific instance of the result set using history_uuid:

>>> results = tio.scans.results(419, history_uuid="123e4567-e89b-12d3-a456-426614174000")

resume(scan_id)[source]¶

Resume a paused scan.

scans: resume

Parameters: scan_id (int or uuid) – The unique identifier for the scan.
Returns: The scan was successfully requested to resume.
Return type: None

Examples

>>> tio.scans.resume(1)

schedule(scan_id, enabled)[source]¶

Enables or disables the scan schedule.

scans: schedule

Parameters

scan_id (int) – The unique identifier for the scan.
enabled (bool) – Enables or Disables the scan scheduling.

Returns

The schedule resource record for the scan.

Return type

dict

Examples

Enable a scan schedule:

>>> tio.scans.schedule(1, True)

schedule_const¶: alias of tenable.constants.IOConstants.ScanScheduleConst

set_read_status(scan_id, read_status)[source]¶

Sets the read status of the scan. This is generally used to toggle the unread status of the scan within the UI.

scans: read-status

Parameters

scan_id (int or uuid) – The unique identifier for the scan.
read_status (bool) – Is the scan in a read or unread state? True would denote read, whereas False is unread.

Returns

The status of the scan was updated.

Return type

None

Examples

Set a scan to unread:

>>> tio.scans.set_read_status(1, False)

status(scan_id)[source]¶

Get the status of the latest instance of the scan.

scans: get-latest-status

Parameters: scan_id (int or uuid) – The unique identifier for the scan.
Returns: The current status of the last instance.
Return type: str

Examples

>>> tio.scans.status(1)
u'completed'

stop(scan_id, block=False)[source]¶

Stop a running scan.

scans: stop

Parameters

scan_id (int) – The unique identifier for the scan.
block (bool, optional) – Block until the scan is actually stopped. Default is False.

Returns

The scan was successfully requested to stop.

Return type

None

Examples

Stop the scan asynchronously:

>>> tio.scans.stop(1)

Stop the scan and wait for the scan to stop:

>>> tio.scans.stop(1, True)

timezones()[source]¶

Retrieves the list of timezones.

scans: timezones

Returns: List of allowed timezone strings accepted by Tenable.IO
Return type: list

Examples

>>> for item in tio.scans.timezones():
...     pprint(item)

upsert_aws_credentials(scan)[source]¶

Checks the credential dict of scan dict to derive operation add or edit. This function assumes there are no edit credentials in the credentials dict. If there is any edit credentials,it would override the same. :param scan: scan object to update edit credential if it matches criteria

Returns: The scan with updated credentials.
Return type: dict