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:
- Review the guidelines and limitations for vulnerability exports.
- Generate the export file based on the guidelines and limitations.
- Query for the export generation status and chunk identification information.
- Download completed export chunks.
You can also:
- View recent vulnerability export jobs for your Vulnerability Management instance.
- Cancel a vulnerability export job.
Guidelines
Configuration
| Category | Guideline |
|---|---|
| First Export | The 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 Exports | Every 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 Size | Vulnerability 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 Refinements | See Refine Vulnerability Export Requests. |
Synchronization
| Category | Guideline |
|---|---|
| Chunk Order | Vulnerability Management processes export chunks in parallel, so chunk IDs may not be arranged sequentially in the completed output. |
| Synchronize Vulnerabilities and Assets | To 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 Assets | As 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
| Category | Guideline |
|---|---|
| Unlicensed Assets | By 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 Limiting | There are maximum limits for concurrent vulnerability export requests per container. For more information, see Concurrency Limiting. |
| Time-based Filters | By 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 Requests | Vulnerability 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 Expiration | You 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 Exports | You cannot export vulnerabilities detected by PCI scans. |
| Plugin Output Size | Output for an individual plugin is limited to 1,024 KB (1 MB). |
Updated 3 days ago