TOC & Recently Viewed

Recently Viewed Topics

Generate the Vulnerability Export File

User Permissions: Administrator (64)

To generate the export file, use the API endpoint described below.

Note:

  • The first time you generate a vulnerabilities export file, you can omit filters parameters to export all current data, or if appropriate use filters parameters to limit by date and other attributes.

  • Every time you export after that, Tenable recommends that you specify parameters for a differential export, with the filters parameters set to the time you last exported vulnerability data from Tenable.io.

HTTP Request

Note: To authenticate your request, be sure to include API keys in the HTTP header of the request. For more information, see Authorization.

Request Path Syntax

POST https://cloud.tenable.com/vulns/export

Request Path Parameters

None.

Request Path Example

See "Request Path Syntax."

Request Body Syntax

{ "num_assets": {integer}, "filters": { "cidr_range": {string}, "first_found": {long}, "last_found": {long}, "last_fixed": {long}, "plugin_family": [ {string}, {string} ], "severity": [ {string}, {string} ], "since": {long}, "state": [ {string}, {string} ], "tag.category": [ {string}, {string} ] } }

Request Body Attributes

Parameter Object Parameter Type Value Required?
num_assets integer

Specifies the maximum number of vulnerabilities per exported chunk.

This number does not represent the number of assets per chunk. Instead, it is equal to the number of assets times the number of vulnerabilities on each asset.

The range of supported chunk sizes is a minimum of 50 (the default size) to a maximum of 5,000. If you specify a value outside this range, the system uses the upper- or lower -bound value.

required

filters

cidr_range string Restricts the export to vulnerabilities on assets assigned an IP address within the specified CIDR range. For example, 0.0.0.0/0 restricts the search to 0.0.0.1 and 255.255.255.254. optional
first_found long

The start date (in Unix time) for the range of vulnerability data you want to export, based on when a scan first found a vulnerability on an asset.

When using this filter, make sure the request message also contains the state filter set to open. If the state filter specifies a value other than open, the request effectively fails, because Tenable.io cannot find any records that match the conflicting criteria.

optional
last_found long

The start date (in Unix time) for the range of vulnerability data you want to export, based on when a scan last found a vulnerability on an asset.

When using this filter, make sure the request message also contains the state filter set to reopened. If the state filter specifies a value other than reopened, the request effectively fails, because Tenable.io cannot find any records that match the conflicting criteria.

optional
last_fixed long

The start date (in Unix time) for the range of vulnerability data you want to export, based on when the vulnerability state was changed to fixed. Tenable.io updates the vulnerability state to fixed when a scan no longer detects a previously detected vulnerability on the asset.

When using this filter, make sure your request message also contains the state filter set to fixed. If the state filter specifies a value other than fixed, the request effectively fails, because Tenable.io cannot find any records that match the conflicting criteria.

optional
plugin_family array

Limits the vulnerabilities you want to include in the export by plugin family. This parameter value is case-sensitive. Use the family names (including capitalization) specified here: Plugins.

If your request omits this parameter, the export includes all vulnerabilities, regardless of plugin family.

optional
severity array

Specifies the severity of the vulnerabilities to include in the export. Defaults to all severity levels.

The severity of a vulnerability is defined using the Common Vulnerability Scoring System (CVSS) base score.

Supported array values are:

  • info—The vulnerability has a CVSS score of 0.
  • low—The vulnerability has a CVSS score between 0.1 and 3.9.
  • medium—The vulnerability has a CVSS score between 4.0 and 6.9.
  • high—The vulnerability has a CVSS score between 7.0 and 9.9.
  • critical—The vulnerability has a CVSS score of 10.0.
optional
since long

Specifies the start date (in Unix time) for the range of data you want to export.

Use this filter in conjunction with the state filter as follows:

  • If the state filter is set to open, the export includes data for vulnerabilities that were first seen on or after the since date you specify.
  • If the state filter is set to reopened, the export includes data for vulnerabilities that were last seen on or after the since date you specify.
  • If the state filter is set to fixed, the export includes data for vulnerabilities that were fixed on or after the since date you specify.
  • If you do not include the state filter in your request, the export includes data for open vulnerabilities that were first seen on or after the since date you specify, AND reopened vulnerabilities that were last seen on or after the since date you specify.

Note: This filter cannot be used in conjunction with the first_found, last_found, or last_fixed filters.

optional
state array

Specifies the state of the vulnerabilities you want the export to include.

Supported, case-insensitive values are:

  • open—The vulnerability is currently present on a host.
  • reopened—The vulnerability was previously marked as fixed on a host, but has returned.
  • fixed—The vulnerability was present on a host, but is no longer detected.

If your request omits this parameter, the export includes default states open and reopened only.

required if filters include first_found, last_found, or last_fixed
tag.category array

Returns vulnerabilities on assets with the specified asset tags. The filter is defined as "tag", a period ("."), and the tag category name. For example, tag.Location. The value of the filter is an array of tag values, for example, Headquarters.

For more information about tags, see Tags in the Tenable.io Vulnerability Management User Guide

optional

Request Body Example 1: Since Only

{ "num_assets": 100, "filters": { "severity": [ "low", "medium", "high", "critical" ], "since": 1546300800 } }

In this example, the request message contains a since filter specifying Jan 1, 2019, and does not contain a state filter.

The export includes vulnerabilities that meet the following criteria:

  • The state attribute in the vulnerability record is open AND the first_found attribute in the vulnerability record is 1/1/19 or later.
  • The state attribute in the vulnerability is reopened AND the last_found attribute in the vulnerability record is 1/1/19 or later.

The export omits any vulnerabilities where the state attribute in the vulnerability record is fixed.

Request Body Example 2: Since and State

{ "num_assets": 100, "filters": { "severity": [ "low", "medium", "high", "critical" ], "since": 1546300800, "state": [ "open", "reopened", "fixed" ] } }

In this example, the request message includes both the since and state filters.

The export includes only vulnerabilities where the state attribute in the vulnerability record is either open, reopened, or fixed. AND the since attribute in the vulnerability record is 1/1/19 or later.

Request Body Example 3: Last_fixed and Correct State

{ "num_assets": 100, "filters": { "severity": [ "low", "medium", "high", "critical" ], "last_fixed": 1546300800, "state": [ "fixed" ] } }

In this example, the request message contains both the last_fixed and state parameters.

The export includes only vulnerabilities where the state attribute in the vulnerability record is fixed AND the since attribute in the vulnerability record is 1/1/19 or later.

Request Body Example 4: Tags

{ "num_assets": 100, "filters": { "severity": [ "low", "medium", "high", "critical" ], "tag.Location": "Headquarters" } }

In this example, the export includes only vulnerabilities on assets that you assigned the Location:Headquarters tag.

HTTP Response

Response Codes

Status Description
200 Returned if Tenable.io successfully queues the export request. For more information, see "Response Body Syntax."
400 Returned if any of the filters in the request is invalid.
403 Returned if you do not have permission to export vulnerabilities.
429

Returned if you attempt to send too many requests in a specific period of time. For more information, see Rate Limiting.

Response Body Syntax

{ "export_uuid": {string} }

Response Body Attributes

Attribute Type Description
export_uuid string The unique identifier of the export request.

Response Body Example

{ "export_uuid": "a483adf8-24e3-4c7f-818a-6867b02310dd" }

Reference Guide

https://cloud.tenable.com/api#/resources/exports/vulns-request-export

Examples

Copyright © 2019 Tenable, Inc. All rights reserved. Tenable, Tenable.io, Tenable Network Security, Nessus, SecurityCenter, SecurityCenter Continuous View and Log Correlation Engine are registered trademarks of Tenable, Inc.. Tenable.sc, Lumin, Assure, and the Cyber Exposure Company are trademarks of Tenable, Inc. All other products or services are trademarks of their respective owners.