Scanners

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

Methods available on tio.scanners:

class ScannersAPI(api: APISession)

allowed_scanners()

A simple convenience function that returns the list of scanners that the current user is allowed to use.

Returns:

List of scanner documents.

Return type:

list

Examples

>>> for scanner in tio.scanners.allowed_scanners():
...     pprint(scanner)

control_scan(scanner_id, scan_uuid, action)

Perform actions against scans on a given scanner.

scanners: control-scans

Parameters:

• scanner_id (int) – The unique identifier for the scanner.

• scan_uuid (uuid) – The unique identifier for the scan.

• action (str) – The action to take upon the scan. Valid actions are stop, pause, and resume.

Returns:

The action was sent to the scan successfully.

Return type:

None

Examples

Stop a scan running on the scanner:

>>> tio.scanners.control_scan(1, '00000000-0000-0000-0000-000000000000', 'stop')

delete(id)

Delete a scanner from Tenable Vulnerability Management.

scanners: delete

Parameters:

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

Returns:

The scanner was successfully deleted.

Return type:

None

Examples

>>> tio.scanners.delete(1)

details(id)

Retrieve the details for a specified scanner.

scanners: details

Parameters:

id (int) – The unique identifier for the scanner

Returns:

The scanner resource record.

Return type:

dict

Examples

>>> scanner = tio.scanners.details(1)
>>> pprint(scanner)

edit(id, **kwargs)

Modify the scanner.

scanners: edit

Parameters:

• id (int) – The unique identifier for the scanner.

• force_plugin_update (bool, optional) – Force the scanner to perform a plugin update .

• force_ui_update (bool, optional) – Force the scanner to perform a UI update.

• finish_update (bool, optional) – Force the scanner to reboot to complete the update process. This action is only valid when automatic updates are disabled.

• registration_code (str, optional) – Sets the registration code for the scanner.

• aws_update_interval (int, optional) – For AWS scanners this will inform the scanner how often to check into Tenable Vulnerability Management.

Returns:

The operation was requested successfully.

Return type:

None

Examples

Force a plugin update on a scanner:

>>> tio.scanners.edit(1, force_plugin_update=True)

edit_permissions(id, *acls)

Modifies the permissions list for the given scanner.

Parameters:

• id (int) – The unique identifier for the scanner.

• *acls (dict) – The permissions record(s) for the scanner.

Returns:

The permissions have been updated successfully.

Return type:

None

Examples

>>> tio.scanners.edit_permissions(1,
...     {'type': 'default, 'permissions': 16},
...     {'type': 'user', 'id': 2, 'permissions': 16})

get_aws_targets(id)

Returns the list of AWS targets the scanner can reach.

scanners: get-aws-targets

Parameters:

id (int) – The unique identifier for the scanner.

Returns:

List of aws target resource records.

Return type:

list

Examples

>>> for target in tio.scanners.get_aws_targets(1):
...      pprint(target)

get_permissions(id)

Returns the permission list for a given scanner.

Parameters:

id (int) – The unique identifier for the scanner.

Returns:

The permissions resource for the scanner

Return type:

dict

Examples

>>> tio.scanners.get_permissions(1)

get_scanner_key(id)

Return the key associated with the scanner.

scanners: get-scanner-key

Parameters:

id (int) – The unique identifier for the scanner.

Returns:

The scanner key

Return type:

str

Examples

>>> print(tio.scanners.get_scanner_key(1))

get_scans(id)

Retrieves the scans associated to the scanner.

scanners: get-scans

Parameters:

id (int) – The unique identifier for the scanner.

Returns:

List of scan resource records associated to the scanner.

Return type:

list

Examples

>>> for scan in tio.scanners.get_scans(1):
...     pprint(scan)

linking_key()

The linking key for the Tenable Vulnerability Management instance.

Returns:

The linking key

Return type:

str

Examples

>>> print(tio.scanners.linking_key())

list()

Retrieves the list of scanners.

scanners: list

Returns:

List of scanner resource records.

Return type:

list

Examples

>>> for scanner in tio.scanners.list():
...     pprint(scanner)

toggle_link_state(id, linked)

Toggles the scanner’s activated state.

scanners: toggle-link-state

Parameters:

• id (int) – The unique identifier for the scanner

• linked (bool) – The link status of the scanner. Setting to False will disable the link, whereas setting to True will enable the link.

Returns:

The status change was successful.

Return type:

None

Examples

to deactivate a linked scanner:

>>> tio.scanners.toggle_link_state(1, False)