AUTOMATE. BUILD. DELIVER.

Integrate with the world's first Cyber Exposure platform using Tenable APIs

Get Started    API Explorer

Retrieve Vulnerability Data from Tenable.io

The vulnerability export APIs allow you to retrieve all vulnerabilities on each asset, including the vulnerability state, for integration into third-party tools. With these APIs, you can perform a large initial synchronization of Tenable.io with a third-party tool. You can then retrieve differentials to update on a regular basis. For example, you can use the vulnerability export APIs to retrieve all vulnerabilities that are currently active in your environment and integrate them with a ticketing system. You can then leverage the differential functionality to:

  • Retrieve newly discovered vulnerabilities and create new tickets.
  • Retrieve fixed vulnerabilities to automatically close open tickets.

🛈

Note

In most implementations, Tenable.io stores vulnerability data obtained from scans it manages. However, you can also import vulnerability data from scans managed by other Tenable products, as well as a limited number of third-party applications. For more information, see the vulnerabilities import endpoints.

Recommended Approach

To retrieve vulnerability data using the Tenable.io API, Tenable recommends the following approach:

  1. Review the guidelines and limitations for vulnerability exports.
  2. Generate the export file based on the guidelines and limitations.
  3. Query for the export generation status and chunk identification information.
  4. Download completed export chunks.

You can also:

  • View recent vulnerability export jobs for your Tenable.io instance.
  • Cancel a vulnerability export job.

🗹

Example

exports (pyTenable)

Guidelines

Configuration

CategoryGuideline
First ExportThe first time you generate an export file, you can omit filter parameters to export all current data, or use filter parameters to limit by date and other attributes.
Ongoing ExportsEvery time you export after that, Tenable recommends that you specify parameters for a differential export, with the filter parameters set to the time you last exported data from Tenable.io.

For example, you can use the last_found and state filters in the Export Vulnerabilities endpoint to export vulnerability data created later than the date specified along with the state of the vulnerabilities you want the export to include.
Chunk SizeTenable.io exports vulnerability data in data chunks. Configure the num_assets parameter to maximize network performance and satisfy data ingestion requirements for third-party applications. Tenable does not recommend using a chunk size larger than 5000 as the potential for an error increases above this amount.
Additional RefinementsSee Refine Vulnerability Export Requests.

Synchronization

CategoryGuideline
Chunk OrderTenable.io processes export chunks in parallel, so chunk IDs may not be arranged sequentially in the completed output.
Synchronize Vulnerabilities and AssetsTo synchronize vulnerability export data with asset export data, match the asset.uuid attribute in the vulnerability export response to the id attribute in the asset export response.

Tenable recommends synchronizing vulnerability export data with asset export data, because the asset data included in the vulnerability export response (for example, IPv4 address) is limited to asset attributes that plugins identified in an individual scan. Asset export data, on the other hand, provides aggregated asset data based on multiple scans.
Vulnerabilities on Deleted or Terminated AssetsAs assets are deleted or terminated in Tenable.io, you can identify those assets and related vulnerabilities using the terminated_at and deleted_at filters on the Export Assets endpoint.

Tenable recommends that you periodically run two asset export queries—(1) a query where terminated_at is set to the date of your last asset export and (2) a query where deleted_at is set to the date of your last asset export. You can then match the asset IDs in the returned results to the asset IDs associated with the vulnerabilities in a third-party system and update the system records accordingly (for example, you might remove the vulnerabilities from the system).

Limitations

CategoryGuideline
Unlicensed AssetsBy default, exported vulnerability data includes licensed assets only. However, to include both licensed and unlicensed assets in vulnerability exports, you can set the include_unlicensed body parameter to true for the Export Vulnerabilities endpoint.
Concurrency LimitingThere are maximum limits for concurrent vulnerability export requests per container. For more information, see Concurrency Limiting.
Time-based FiltersBy default, vulnerability exports will only include vulnerabilities found or fixed within the last 30 days if no time-based filters (indexed_at, last_fixed, last_found, or first_found) are submitted with the request.
Duplicate RequestsTenable.io prevents duplicate requests. If the export request status is PROCESSING and fewer than three days have passed since you submitted the original request, Tenable.io rejects any concurrent request with identical filters from the same user account. If you need to submit an identical request while the original request is still processing, contact Support for assistance.
Chunks ExpirationYou can download completed export chunks for three days after completion. At that point, the chunks expire, and you must re-submit the export request.
PCI Scan ExportsYou cannot export vulnerabilities detected by PCI scans.
Plugin Output SizeOutput for an individual plugin is limited to 1,024 KB (1 MB).
Filter Parsing LimitIf 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. For more information on the host.target filter, see Commonly-used Filters in Workbench Filters.

Updated 3 months ago


Retrieve Vulnerability Data from Tenable.io


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.