Scans¶
The following methods allow for interaction into the Tenable Vulnerability Management scans API endpoints.
Methods available on tio.scans:
- class ScansAPI(api: APISession)[source]¶
This will contain all methods related to scans
- attachment(scan_id: int | UUID, attachment_id: int, key: str, fobj: BytesIO | None = None) → BytesIO[source]¶
Retrieve an attachment associated to a scan.
- 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: int, matched_resource_limit: int, network_uuid: UUID | None = '00000000-0000-0000-0000-000000000000', tags: List[UUID] | None = None, targets: List[str] | None = None) → Dict[source]¶
Evaluates a list of targets and/or tags against the scan route configuration of scanner groups.
- 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:
Examples
>>> scan_routes_info = tio.scans.check_auto_targets(10, 5, targets=['127.0.0.1'])
- configure(scan_id: int | UUID, **kw) → Dict[source]¶
Overwrite the parameters specified on top of the existing scan record.
- 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:
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 isONETIME.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 scans-timezones
- Returns:
Dictionary of the keys required for scan schedule.
- Return type:
- copy(scan_id, folder_id=None, name=None)[source]¶
Duplicates a scan and returns the details of the copy.
- Parameters:
- Returns:
The scan resource record for the copied scan.
- Return type:
Examples
>>> new_scan = tio.scans.copy(1, 'New Scan Name')
- create(**kw)[source]¶
Create a new scan.
- 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:
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 isONETIME.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 scans-timezones
- Returns:
Dictionary of the keys required for scan schedule.
- Return type:
- delete(scan_id: int | UUID)[source]¶
Remove a scan.
- Parameters:
scan_id (int or uuid) – The unique identifier for the scan.
- Returns:
The scan was successfully deleted.
- Return type:
Examples
>>> tio.scans.delete(1)
- delete_history(scan_id: int | UUID, history_id: int | UUID)[source]¶
Remove an instance of a scan from a scan history.
- Parameters:
- Returns:
Scan history successfully deleted.
- Return type:
Examples
>>> tio.scans.delete_history(1, 1)
- details(scan_id: int | UUID) → Dict[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:
Examples
>>> scan = tio.scans.details(1) >>> pprint(scan)
- export(scan_id: int | UUID, *filters: Tuple[str, str, str], stream_hook: Callable | None = None, **kw)[source]¶
Export the scan report.
- 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: int | UUID, limit: int = 50, offset: int = 0, pages: int | None = None, sort: Tuple[str, str] = None) → ScanHistoryIterator[source]¶
Get the scan history of a given scan from Tenable Vulnerability Management.
- 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: int | UUID, host_id: int, history_id: int | None = None, history_uuid: UUID | None = None) → Dict[source]¶
Retrieve the host details from a specific scan.
- Parameters:
- Returns:
The information related to the host requested.
- Return type:
Examples
>>> host = tio.scans.host_details(1, 1)
- import_scan(fobj: BytesIO, folder_id: int | None = None, password: str | None = None, aggregate: bool = True)[source]¶
Import a scan report into Tenable Vulnerability Management.
- 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:
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: int | UUID, history_uuid: UUID) → Dict[source]¶
Retrieves information about the status of the specified instance of the scan.
- Parameters:
- Returns:
The metadata about the scan instance specified.
- Return type:
Examples
>>> info = tio.scans.info(1, 'BA0ED610-C27B-4096-A8F4-3189279AFFE7')
- launch(scan_id: int | UUID, targets: List[str] | None = None)[source]¶
Launches a scan.
- Parameters:
- 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: int | None = None, last_modified: datetime | None = None) → List[Dict][source]¶
Retrieve the list of configured scans.
- 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:
Examples
>>> for scan in tio.scans.list(): ... pprint(scan)
- pause(scan_id: int | UUID, block: bool = False)[source]¶
Pauses a running scan.
- Parameters:
- Returns:
The scan was successfully requested to be paused.
- Return type:
Examples
>>> tio.scans.pause(1)
- plugin_output(scan_id: int | UUID, host_id: int, plugin_id: int, history_id: int | None = None, history_uuid: UUID | None = None) → Dict[source]¶
Retrieve the plugin output for a specific instance of a vulnerability on a host.
- Parameters:
- Returns:
The plugin resource record for that plugin on that host.
- Return type:
Examples
>>> output = tio.scans.plugin_output(1, 1, 1) >>> pprint(output)
- progress(scan_id: int | UUID, history_id: int | None = None, history_uuid: UUID | None = None) → int[source]¶
Get the progress of the specified scan.
- Parameters:
scan_id (int | UUID) – The
- results(scan_id: int | UUID, history_id: int | UUID | None = None, history_uuid: UUID | None = None)[source]¶
Return the scan results from either the latest scan or a specific scan instance in the history.
- Parameters:
- Returns:
The scan result dictionary.
- Return type:
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: str | UUID)[source]¶
Resume a paused scan.
- Parameters:
scan_id (int or uuid) – The unique identifier for the scan.
- Returns:
The scan was successfully requested to resume.
- Return type:
Examples
>>> tio.scans.resume(1)
- schedule(scan_id: str | UUID, enabled: bool) → dict[source]¶
Enables or disables the scan schedule.
- Parameters:
- Returns:
The schedule resource record for the scan.
- Return type:
Examples
Enable a scan schedule:
>>> tio.scans.schedule(1, True)
- schedule_const¶
alias of
ScanScheduleConst
- set_read_status(scan_id: str | UUID, read_status: bool)[source]¶
Sets the read status of the scan. This is generally used to toggle the unread status of the scan within the UI.
- Parameters:
- Returns:
The status of the scan was updated.
- Return type:
Examples
Set a scan to unread:
>>> tio.scans.set_read_status(1, False)
- status(scan_id: str | UUID) → str[source]¶
Get the status of the latest instance of the scan.
- Parameters:
scan_id (int or uuid) – The unique identifier for the scan.
- Returns:
The current status of the last instance.
- Return type:
Examples
>>> tio.scans.status(1) u'completed'
- stop(scan_id: str | UUID, block: bool = False)[source]¶
Stop a running scan.
- Parameters:
- Returns:
The scan was successfully requested to stop.
- Return type:
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() → List[str][source]¶
Retrieves the list of timezones.
- Returns:
List of allowed timezone strings accepted by Tenable.IO
- Return type:
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: