TOC & Recently Viewed

Recently Viewed Topics

Retrieve Vulnerability Data for a Specific Time Range

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

  1. 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 SecurityCenter API reference guide.
  2. 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 SecurityCenter 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 SecurityCenter 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 SecurityCenter user interface. Specifying vuln is equivalent to clicking Analysis > Vulnerabilities.

    For all parameters supported for the /analysis endpoint, see the SecurityCenter 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 SecurityCenter user interface.
      • lastSeen—Equivalent to filtering on Vulnerability Observed on the Vulnerability Analysis page of SecurityCenter user interface. Requires that the sourceType parameter is cumulative.
      • lastMitigated—Equivalent to filtering on Vulnerability Mitigated on the Vulnerability Analysis page of SecurityCenter 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 SecurityCenter 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" }

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