Retrieve Vulnerability Data for a Specific Time Range

To retrieve vulnerability data using the Tenable Security Center API, Tenable recommends the following approach:

Authenticate, if you have not already done so. Be sure to include the authentication token in your request headers. For more information on authentication, see the description of the /token endpoint in the Tenable Security Center API reference guide.

Use the POST version of the /analysis endpoint.

HTTP Request Syntax:

POST /rest/analysis{parameters}

Recommended parameters are:

Parameter	Value
`query`	Specifies the parameters of the data you want to retrieve for analysis. This parameter encapsulates the functionality of the /query endpoint. For the /query parameters Tenable recommends in this specific case, see recommended query parameters below. For a full description of the available /query parameters, see the Tenable Security Center API reference guide.
`sortDir`	Specifies the sort order for the data, using the field you specify in `sortField`. Requires companion parameter, `sortField`. Valid values are: `asc`—Sorts data in ascending order (A-Z, 0-9). `desc`—Sorts data in descending order (Z-A, 9-0).
`sortField`	Specifies the field the system uses to sort the data. Requires companion parameter, `sortDir`. For vulnerabilities data, Tenable recommends you sort by severity: `“sortField”: “severity”`
`sourceType`	Specifies the status of the vulnerabilities you want to analyze. This field corresponds to the Options > Switch to options on the Vulnerability Analysis page in the Tenable Security Center user interface. Valid values are: `cumulative`—Analyzes cumulative vulnerabilities. This parameter corresponds to Options > Switch to Cumulative on the Vulnerability Analysis page. `patched`—Analyzes mitigated vulnerabilities. This parameter corresponds to Options > Switch to Mitigated on the Vulnerability Analysis page.
`type`	Specifies the type of data you want to analyze. For vulnerability data, use `vuln`. This field corresponds to the options available when you click Analysis in the top navigation bar of the Tenable Security Center user interface. Specifying `vuln` is equivalent to clicking Analysis > Vulnerabilities.

For all parameters supported for the /analysis endpoint, see the Tenable Security Center API reference guide.

Recommended Query Parameters:

Tenable recommends that you use the following parameters for the query element of the /analysis endpoint when retrieving vulnerability data:

Parameter	Value
`endOffset`	Specifies the last record in the range you want to retrieve. For example, if this value is `50`, the retrieved data range stops at the 50th result that meets the query criteria. This parameter requires the presence of the `startOffset` parameter.
`filters`	Specifies the filter criteria for the data you want the system to retrieve. Filter parameters include: `filterName`—The name of the field on which the query filters. To limit your query results to a specific date range, use the following: `firstSeen`—Equivalent to filtering on Vulnerability Discovered on the Vulnerability Analysis page of the Tenable Security Center user interface. `lastSeen`—Equivalent to filtering on Vulnerability Observed on the Vulnerability Analysis page of Tenable Security Center user interface. Requires that the `sourceType` parameter is `cumulative`. `lastMitigated`—Equivalent to filtering on Vulnerability Mitigated on the Vulnerability Analysis page of Tenable Security Center user interface. Requires that the `sourceType` parameter is `patched`. `operator`—An operator that specifies the relationship between the `filterName` and the `value` elements. `value`—A code in the format `#:#` specifying a date range relative to the current day. The first number represents the starting day, and the second number represents the last day of the range. For example: `"filters": { "filterName": "firstSeen", "operator": "=", "value": "#:#" }` In this example, if the `sourceType` for the query is `cumulative`, and this filter value is set to `0:11`, the query retrieves all vulnerabilities first discovered between today and 11 days ago. To set this filter to a single date, use the same number for both elements. For example, a value of `0:0` retrieves all vulnerabilities first discovered today.
`sourceType`	Specifies the status of the vulnerabilities you want to retrieve. Valid values are: `cumulative`—Retrieves vulnerabilities from the cumulative database. Equivalent to Options > Switch to cumulative in the Vulnerability Analysis page. `patched`—Retrieves vulnerabilities from the mitigated database. Equivalent to Options > Switch to Mitigated in the Vulnerability Analysis page.
`startOffset`	Specifies the first record in the range you want to retrieve. For example, if this parameter is `0`, the retrieved data starts at the first result that meets the query criteria. This parameter requires the presence of the `endOffset` parameter.
`tools`	Specifies the level of vulnerability detail you want to retrieve. This field corresponds to the drop-down options on the Vulnerability Analysis page in the Tenable Security Center user interface. Valid values include: `listvuln`—Equivalent to the Vulnerability List option on the Vulnerability Analysis page. `vulndetails`—Equivalent to the Vulnerability Details List option on the Vulnerability Analysis page.
`type`	Specifies type of data you want to retrieve. For vulnerability data, use `vuln`.

HTTP Request Example—Cumulative Vulnerabilities:

{
  "query": {
    "name": "",
    "description": "",
    "context": "",
    "createdTime": 0,
    "modifiedTime": 0,
    "groups": [],
    "type": "vuln",
    "tool": "vulndetails",
    "sourceType": "cumulative",
    "startOffset": 0,
    "endOffset": 50,
    "filters": [
      {
        "filterName": "firstSeen",
        "operator": "=",
        "value": "0:11"
      },
      {
        "filterName": "lastSeen",
        "operator": "=",
        "value": "0:12"
      }
    ]
  },
  "sourceType": "cumulative",
  "sortField": "severity",
  "sortDir": "desc",
  "columns": [],
  "type": "vuln"
}

HTTP Request Example—Mitigated Vulnerabilities:

{
  "query": {
    "name": "",
    "description": "",
    "context": "",
    "createdTime": 0,
    "modifiedTime": 0,
    "groups": [],
    "type": "vuln",
    "tool": "listvuln",
    "sourceType": "patched",
    "startOffset": 0,
    "endOffset": 50,
    "filters": [
      {
        "filterName": "lastMitigated",
        "operator": "=",
        "value": "0:25"
       },
    ]
  }
  "sourceType": "patched",
   "sortField": "severity",
  "sortDir": "desc",
  "columns": [],
  "type": "vuln"
}