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: restfly.session.APISession)[source]¶
- copy(id, *users)[source]¶
Clones the scan instance.
- Parameters
- Returns
The cloned scan instance record.
- Return type
Examples
>>> sc.scan_instances.copy(1)
- delete(id)[source]¶
Removes the scan instance from TenableSC.
- Parameters
id (int) – The identifier of the scan instance to delete.
- Returns
An empty string.
- Return type
Examples
>>> sc.scan_instances.delete(1)
- details(id, fields=None)[source]¶
Retrieves the details for the specified scan instance.
- Parameters
- Returns
The scan instance resource record.
- Return type
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.
- Parameters
- Returns
Empty string response.
- Return type
Examples
>>> sc.scan_instances.email(1, 'email@company.tld')
- export_scan(id, fobj=None, export_format=None)[source]¶
Downloads the results of the scan.
- Parameters
id (int) – The scan instance identifier.
export_format (str, optional) – The format of the resulting data. Allowable values are
scap1_2
andv2
.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.
- 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
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.
- 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
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.
- Parameters
id (int) – The unique identifier for the scan instance.
- Returns
The Scan instance state
- Return type
Examples
>>> sc.scan_instances.pause(1)
- reimport_scan(id, **kw)[source]¶
Re-imports an existing scan into the cumulative repository.
- 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
An empty string response.
- Return type
Examples
>>> sc.scan_instances.reimport_scan(1)
- resume(id)[source]¶
Resumes a paused scan instance. Note that this will not impact agent scan instances.
- Parameters
id (int) – The unique identifier for the scan instance.
- Returns
The Scan instance state
- Return type
Examples
>>> sc.scan_instances.resume(1)