Workbenches

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

Note

Workbenches API endpoints have an upper bound on the amount of data that they will return, so for larger result sets, it may make more sense to use the exports API.

Methods available on tio.workbenches:

class WorkbenchesAPI(api: APISession)[source]
asset_activity(uuid)[source]

Query for the asset activity (when was the asset was seen, were there changes, etc.).

workbenches: asset-activity

Parameters:

uuid (str) – The asset unique identifier.

Returns:

The activity list of the asset specified.

Return type:

list

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> for entry in tio.workbenches.asset_activity(asset_id):
...     pprint(entry)
asset_delete(asset_uuid)[source]

Deletes the asset.

workbenches: asset-delete

Parameters:

asset_uuid (str) – The unique identifier for the asset.

Return type:

None

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> tio.workbenches.asset_delete(asset_id)
asset_info(uuid, all_fields=True)[source]

Query for the information for a specific asset within the asset workbench.

workbenches: asset-info

Parameters:

  • id (str) – The unique identifier (UUID) of the asset.

  • all_fields (bool, optional) – If all_fields is set to true (the default state), then an expanded dataset is returned as defined by the API documentation (linked above).

Returns:

The resource record for the asset.

Return type:

dict

Examples

>>> asset = tio.workbenches.asset_info('00000000-0000-0000-0000-000000000000')
asset_vuln_info(uuid, plugin_id, *filters, **kw)[source]

Retrieves the vulnerability information for a specific plugin on a specific asset within Tenable Vulnerability Management.

workbenches: asset-vulnerability-info

Parameters:

  • uuid (str) – The unique identifier of the asset to query.

  • plugin_id (int) – The unique identifier of the plugin.

  • age (int, optional) – The maximum age of the data to be returned.

  • *filters (list, 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: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above.

  • 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.

Returns:

List of vulnerability resource records.

Return type:

list

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> vuln = tio.workbenches.asset_vuln_info(asset_id, 19506)
>>> pprint(vuln)
asset_vuln_output(uuid, plugin_id, *filters, **kw)[source]

Retrieves the vulnerability output for a specific vulnerability on a specific asset within Tenable Vulnerability Management.

workbenches: asset-vulnerability-output

Parameters:

  • uuid (str) – The unique identifier of the asset to query.

  • plugin_id (int) – The unique identifier of the plugin.

  • age (int, optional) – The maximum age of the data to be returned.

  • *filters (list, 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: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above.

  • 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.

Returns:

List of vulnerability resource records.

Return type:

list

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> output = tio.workbenches.asset_vuln_output(asset_id, 19506)
>>> pprint(output)
asset_vulns(uuid, *filters, **kw)[source]

Return the vulnerabilities for a specific asset.

workbenches: asset-vulnerabilities

Parameters:

  • uuid (str) – The unique identifier of the asset to query.

  • age (int, optional) – The maximum age of the data to be returned.

  • *filters (list, 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: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above.

  • 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.

Returns:

List of vulnerability resource records.

Return type:

list

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> for vuln in tio.workbenches.asset_vulns(asset_id):
...     pprint(vuln)
assets(*filters, **kw)[source]

The assets workbench allows for filtering and interactively querying the asset data stored within Tenable Vulnerability Management. There are a wide variety of filtering options available to find specific pieces of data.

workbenches: assets

Parameters:

  • age (int, optional) – The maximum age of the data to be returned.

  • *filters (list, 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: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above.

  • 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.

  • all_fields (bool, optional) – Should all of the available fields be returned for each returned asset, or just the default fields represented in the UI. The default is set to True which will return the same level of detail as the workbenches: asset-info endpoint.

Returns:

List of asset resource records.

Return type:

list

Examples

Query for all of the asset information:

>>> for asset in tio.workbenches.assets():
...     pprint(asset)

Query for just the windows assets:

>>> for asset in tio.workbenches.assets(
...     ('operating_system', 'match', 'Windows')):
...     pprint(asset)
export(*filters, **kw)[source]

Export data from the vulnerability workbench. These exports can be in a number of different formats, however the defaults are set to export a Nessusv2 report.

workbenches: export

Parameters:

  • *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.

  • asset_uuid (uuid, optional) – Restrict the output to the asset identifier specified.

  • plugin_id (int, optional) – Restrict the output to the plugin identifier specified.

  • 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. Default is ‘nessus’

  • chapters (list, optional) – A list of the chapters to write for the report. The chapters list is only required for PDF, CSV, and HTML exports. Available chapters are vuln_hosts_summary, vuln_by_host, vuln_by_plugin, and vuln_by_asset. List order will denote output order. In the case of CSV reports, only vuln_by_asset and vuln_by_plugin are available and only a singular chapter can be specified.

  • 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.

  • 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

>>> with open('example.nessus', 'wb') as exportobj:
...     tio.workbenches.export(fobj=exportobj)
vuln_assets(*filters, **kw)[source]

Retrieve assets based on the vulnerability data.

workbenches: assets-vulnerabilities

Parameters:

  • age (int, optional) – The maximum age of the data to be returned.

  • *filters (list, 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: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above.

  • 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.

Returns:

List of asset resource records.

Return type:

list

Examples

>>> for asset in tio.workbenches.vuln_assets():
...     pprint(asset)
vuln_info(plugin_id, *filters, **kw)[source]

Retrieve the vulnerability information for a specific vulnerability.

workbenches: vulnerability-info

Parameters:

  • age (int, optional) – The maximum age of the data to be returned.

  • *filters (list, 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: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above.

  • 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.

Returns:

Vulnerability info resource

Return type:

dict

Examples

>>> info = tio.workbenches.vuln_info(19506)
>>> pprint(info)
vuln_outputs(plugin_id, *filters, **kw)[source]

Retrieve the vulnerability output for a given vulnerability.

workbenches: vulnerability-output

Parameters:

  • age (int, optional) – The maximum age of the data to be returned.

  • *filters (list, 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: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above.

  • 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.

Returns:

Vulnerability outputs resource

Return type:

dict

Examples

>>> outputs = tio.workbenches.vuln_outputs(19506)
>>> pprint(outputs)
vulns(*filters, **kw)[source]

The vulnerability workbench allows for filtering and interactively querying the vulnerability data stored within Tenable Vulnerability Management. There are a wide variety of filtering options available to find specific pieces of data.

workbenches: vulnerability-info

Parameters:

  • age (int, optional) – The maximum age of the data to be returned.

  • authenticated (bool, optional) – If set to true will only return authenticated vulnerabilities.

  • exploitable (bool, optional) – If set to true will only return exploitable vulnerabilities.

  • *filters (list, 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: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above.

  • 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.

  • resolvable (bool, optional) – If set to true will only return vulnerabilities with a remediation path.

  • severity (str, optional) – Only return results of a specific severity (critical, high, medium, or low).

Returns:

Vulnerability info resource

Return type:

dict