Scanners¶

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

Methods available on tio.scanners:

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

allowed_scanners()[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

The linking key for the Tenable Vulnerability Management instance.

Returns: The linking key
Return type: str

Examples

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

list()[source]¶

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)[source]¶

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)