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: restfly.session.APISession)[source]¶
- asset_activity(uuid)[source]¶
Query for the asset activity (when was the asset was seen, were there changes, etc.).
- Parameters
uuid (str) – The asset unique identifier.
- Returns
The activity list of the asset specified.
- Return type
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.
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.
- Parameters
- Returns
The resource record for the asset.
- Return type
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
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
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.
devportalworkbenches: asset-vulnerabilities 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
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.
- 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
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.
- 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
, andvuln_by_asset
. List order will denote output order. In the case of CSV reports, onlyvuln_by_asset
andvuln_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
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
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
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