Workbench Filters

In the Tenable.io 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

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

ParameterDescription
filter..filterThe name of the filter to apply to the returned data.
filter..qualityThe operator of the filter to apply to the returned data.
filter..valueThe value of the filter to apply to the returned data.

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
  1. (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, Tenable.io 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.

User Interface Labelfilter..filterfilter..qualityfilter..value
Asset Assessedasset_assessedeqtrue, false
Hostname/IP Addresshost.targeteq, neq, match, nmatchString
IPv4 Addressassets[].ipv4eq, neq, match, nmatchNUMBER
Is Licensed (VM)is_licensedeqtrue, false
Severityseverityeq, neqNone, Low, Medium, High, Critical
Tag UUIDinfo.tags[].tag_uuidset-has, set-hasnotString
Tag Keyinfo.tags[].tag_keyset-has, set-hasnotDynamic, DynamicTest, Location
Tag Valueinfo.tags[].tag_valueset-has, set-hasnotfilter-test, HQ, test
Tag Added Byinfo.tags[].added_byset-has, set-hasnotString
Tag Added Atinfo.tags[].added_atset-has, set-hasnotString
Tag Sourceinfo.tags[].sourceset-has, set-hasnotstatic, dynamic

๐Ÿ“˜

Note

If a POST /vulns/exports request contains a host.target filter, Tenable.io parses the filter into asset identifiers, which it then matches to vulnerabilities. Tenable.io can support parsing the filter up to a maximum of 1,024 asset identifiers. If the filter parsing exceeds this limit, Tenable.io 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

Tenable.io 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