Retrieve Vulnerability Data from Vulnerability Management

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 Vulnerability Management 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, Vulnerability Management 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 POST /api/v2/vulnerabilities import endpoint.

Recommended Approach

To retrieve vulnerability data using the Vulnerability Management 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 Vulnerability Management instance.
  • Cancel a vulnerability export job.

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 Vulnerability Management.

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 SizeVulnerability Management 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 OrderVulnerability Management 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 Vulnerability Management, 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 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 RequestsVulnerability Management prevents duplicate requests. If the export request status is PROCESSING and fewer than three days have passed since you submitted the original request, Vulnerability Management rejects any concurrent request with identical filters from the same user account.
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).