Workbench Filters

In the Tenable Vulnerability Management user interface, "workbenches" are default dashboards that, unlike user-defined dashboards, cannot be customized. Workbenches provide you with an overview of actionable insights into assets and vulnerability management, which you can then use to prioritize vulnerabilities and manage assets and scan coverage in your organization's network. The workbenches API provides extended capabilities for retrieving asset and vulnerability data from the workbenches.

Use filter query parameters to refine the asset and vulnerability data that the workbenches API endpoints return.

For more information, see:

• Filter Parameters
• Supported Filters
• Commonly-used Filters
• Example: Filter by Installed Software
• Example: Filter by Asset Assessed

Filter Parameters

For each filter you want to apply to workbench data, you must specify the following query parameters:

To specify a single filter, use '0' as the value in each filter parameter name.

To specify multiple filters:

1. Increment the portion of each filter parameter name. For example:

filter.0.filter=host.id
filter.0.quality=eq
filter.0.value=8720e5e5-2ea7-4f86-a7cb-2630c7714a35
filter.1.filter=plugin.attributes.bid
filter.1.quality=eq
filter.1.value=19970919

2. (Optional) Include the filter.search_type query parameter. This parameter specifies whether to use the AND or the OR logical operator when matching data to the specified filters. If you omit the filter.search_type parameter, Vulnerability Management uses AND by default.

📘

Note

You cannot specify more than 10 filters or 50 filter values per filter. A 400 Bad Request error is returned if you exceed this limit.

Supported Filters

Commonly-used Filters

The table below lists parameters for commmonly-used filters for assets and vulnerabilities.

📘

Note

If a POST /vulns/exports request contains a host.target filter, Vulnerability Management parses the filter into asset identifiers, which it then matches to vulnerabilities. Vulnerability Management can support parsing the filter up to a maximum of 1,024 asset identifiers. If the filter parsing exceeds this limit, Vulnerability Management returns a 400 error response. To resolve this error state, refine the values specified for the host.target filter to minimize returned results.

Example: Filter by Installed Software

Your organization might distribute remediation responsibility based on network segments or, commonly, based on the type of software installed on the network assets. For example, you might be responsible for patching only Apple vulnerabilities for your organization. You can use the API to retrieve a list of only those assets where a specific version of Apple Quicktime is installed.

In this case, your query parameters might include the following:

GET https://cloud.tenable.com/workbenches/assets?filter.0.filter=installed_software&filter.0.quality=eq&filter.0.value=cpe:/a:apple:quicktime:7.7.1

Example: Filter by Asset Assessed

Vulnerability Management can discover assets without scanning them for vulnerabilities. After discovery, you may want to identify these unassessed assets to target them for vulnerability scanning. For more information, see Manage Unassessed Assets.

In this case, your query parameters include the following:

GET https://cloud.tenable.com/workbenches/assets?filter.0.filter=asset_assessed&filter.0.quality=eq&filter.0.value=false