Retrieve Asset Data from Vulnerability Management
The asset export APIs provide the ability to retrieve all assets and related metadata from Vulnerability Management for integration into third-party systems. With these APIs, you can perform a large initial synchronization of Vulnerability Management with a third-party system. You can then retrieve differentials to update on a regular basis. For example, you can use the asset export APIs to retrieve all known assets, then use the data to create and regularly update your configuration management database (CMDB).
Recommended Approach
To retrieve asset data using the Vulnerability Management API, Tenable recommends the following approach:
- Review the guidelines and limitations for asset 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.
- (Optional) Retrieve agent data related to the assets.
Note
Agent data is only relevant if the has_agent parameter is set to
truefor assets in the export chunk.
You can also:
- View recent asset export jobs for your Vulnerability Management instance.
- Cancel an asset export job
Example
Guidelines
Configuration
| Category | Guideline |
|---|---|
| First Export | The first time you generate an export file, you can export all current data by omitting all filter parameters, or you can export a subset of the data using filter parameters to limit by date or other attributes. |
| Ongoing Exports | Every time you export after the first time, 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 created_at filter in the Export Assets endpoint to return all assets created later than the date specified. |
| Chunk Size | Vulnerability Management exports asset data in data chunks. Configure the chunk_size 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 Asset 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 Asset Exports | To synchronize multiple exports of asset data, use the id attribute from the asset export response message, instead of any other single asset identifier such as IPv4 address.To synchronize asset export data with vulnerability export data, match the id attribute from the asset export to the asset.uuid attribute in the vulnerability export. |
| 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 |
|---|---|
| Chunks Expiration | You can download completed export chunks for 24 hours after completion. At that point, the chunks expire, and you must re-submit the export request. |
| Concurrency Limiting | There are maximum limits for concurrent asset export requests per container. For more information, see Concurrency Limits. |
| 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. If you need to submit an identical request while the original request is still processing, contact Support for assistance. |
| Duplicate Export Filters | If you submit an asset export request with filters that are identical to a previously submitted asset export request then the old export is canceled and a new export is submitted. |
Updated 3 days ago