Scan Instances¶

The following methods allow for interaction into the Tenable Security Center Scan Result API. While the Tenable Security Center API refers to the model these endpoints interact with as ScanResult, were actually interacting with an instance of a scan definition stored within the Scan API endpoints. These scan instances could be running scans, stopped scans, errored scans, or completed scans. These items are typically seen under the Scan Results section of Tenable Security Center.

Methods available on sc.scan_instances:

class ScanResultAPI(api: APISession)[source]¶

copy(id, *users)[source]¶

Clones the scan instance.

scan-result: copy

Parameters:

id (int) – The identifier of the scan instance to clone.
*users (int) – A user id to associate to the scan instance.

Returns:

The cloned scan instance record.

Return type:

dict

Examples

>>> sc.scan_instances.copy(1)

delete(id)[source]¶

Removes the scan instance from TenableSC.

scan-result: delete

Parameters:: id (int) – The identifier of the scan instance to delete.
Returns:: An empty string.
Return type:: str

Examples

>>> sc.scan_instances.delete(1)

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

Retrieves the details for the specified scan instance.

scan-result: details

Parameters:

id (int) – The identifier for the scan instance to be retrieved.
fields (list, optional) – List of fields to return. Refer to the API documentation referenced above for a list of available fields.

Returns:

The scan instance resource record.

Return type:

dict

Examples

Getting the details of a scan instance with just the default parameters:

>>> scan = sc.scan_instances.details(1)
>>> pprint(scan)

Specifying what fields you’d like to be returned:

>>> scan = sc.scan_instances.details(1,
...     fields=['name', 'status', 'scannedIPs', 'startTime', 'finishTime'])
>>> pprint(scan)

email(id, *emails)[source]¶

Emails the scan results of the requested scan to the email addresses defined.

scan-result: email

Parameters:

id (int) – The identifier for the specified scan instance.
*emails (str) – Valid email address.

Returns:

Empty string response.

Return type:

str

Examples

>>> sc.scan_instances.email(1, 'email@company.tld')

export_scan(id, fobj=None, export_format=None)[source]¶

Downloads the results of the scan.

scan-result: download

Parameters:

id (int) – The scan instance identifier.
export_format (str, optional) – The format of the resulting data. Allowable values are scap1_2 and v2. v2 is the default value if none are specified.
fobj (FileObject, optional) – The file-like object to write the resulting file into. If no file-like object is provided, a BytesIO objects with the downloaded file will be returned. Be aware that the default option of using a BytesIO object means that the file will be stored in memory, and it’s generally recommended to pass an actual file-object to write to instead.

Returns:

The file-like object with the resulting zipped report.

Return type:

FileObject

Examples

>>> with open('example.zip', 'wb') as fobj:
...     sc.scan_instances.export_scan(1, fobj)

import_scan(fobj, repo, **kw)[source]¶

Imports a nessus file into Tenable Security Center.

scan-result: import

Parameters:

fobj (FileObject) – The file-like object containing the Nessus file to import.
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.
host_tracking (bool, optional) – Should DHCP host tracking be enabled? The default is False.
vhosts (bool, optional) – Should virtual host logic be enabled for the scan? The default is False.

Returns:

An empty string response.

Return type:

str

Examples

>>> with open('example.nessus') as fobj:
...     sc.scan_instances.import_scan(fobj, 1)

list(fields=None, start_time=None, end_time=None, optimize=True)[source]¶

Retrieves the list of scan instances.

scan-result: list

Parameters:

fields (list, optional) – A list of attributes to return.
start_time (int, optional) – Epoch time to start search (searches against createdTime and defaults to now-30d)
end_time (int, optional) – Epoch time to end search (searches against createdTime and defaults to now)
optimize (bool, optional) – Informs Tenable Security Center to optimize completed scan results. If left unspecified, the default is True.

Returns:

A list of scan instance resources.

Return type:

dict

Examples

Retrieving all of the manageable scans instances:

>>> for scan in sc.scan_instances.list()['manageable']:
...     pprint(scan)

pause(id)[source]¶

Pauses a running scan instance. Note that this will not impact agent scan instances.

scan-result: pause

Parameters:: id (int) – The unique identifier for the scan instance.
Returns:: The Scan instance state
Return type:: dict

Examples

>>> sc.scan_instances.pause(1)

reimport_scan(id, **kw)[source]¶

Re-imports an existing scan into the cumulative repository.

scan-result: re-import

Parameters:

id (int) – The scan instance identifier.
auto_mitigation (int, optional) – How many days to hold on to data before mitigating it? The default value is 0.
host_tracking (bool, optional) – Should DHCP host tracking be enabled? The default is False.
vhosts (bool, optional) – Should virtual host logic be enabled for the scan? The default is False.

Returns: