Skip to main content

Get Vulnerabilities

GET 
/pub/v4.0/vulnerability/list

Get a list of vulnerability instances.
Rate limiting: 60 times per minute

Request​

Query Parameters

    customerid stringrequired

    The customer ID to which the API call is directed

    stime string

    Optional field setting the start of a time range for retrieving vulnerability instances. For example, to get all instances since November 3, 2020, starting at 00:00 AM in the Pacific Time Zone(UTC-8), the start time would be stime=2020-11-3T08:00Z.
    If you prefer to specify the time in your local time rather than adjusting it to UTC time, you can also format the start time as 2020-11-03T:00:00-08:00. Especially when starting at a later hour in the day, this format involves less calculating. For example, if you want to get vulnerability instances starting from 6:00 PM on November 3, 2020, entering 2020-11-03T18:00-08:00 is much simpler than entering 2020-11-04T02:00Z.

    updatedCreatedAfter date-time

    Optional field that sets the start of a time range for retrieving vulnerabilities created in the database or that have been updated. When this field is used, the stime field is ignored.

    pagelength integer

    The number of items in one response; that is, in one page. The default page length for vulnerabilities is 1000 and the maximum is 1000. Setting a shorter length improves response times. Note: The pagelength parameter is only valid when grouping vulnerability instances by device, not when grouping them by vulnerability.

    offset integer

    In addition to the pagelength parameter, offset gets items on subsequent pages. For example, if the page length of your first request is 100, you get the first 100 vulnerabilities. To get the next 100, add offset=100 to your second request. This skips the first 100 vulnerabilities and gets the next 100 starting from 101. Note: The offset parameter is only valid when grouping vulnerability instances by device, not when grouping them by vulnerability.

    name string

    The name of a specific vulnerability. If omitted, all vulnerabilities are returned.

    status string

    The status of vulnerabilities to be retrieved: confirmed or potential vulnerabilities. The following field is either the string “Confirmed” or “Potential”. If no value is passed, both types of vulnerabilities are returned.

    groupby string

    The grouping of device vulnerability instances in query results. Each groupby option results in a different JSON object structure in the response. groupby=vulnerability (the default) organizes results into groups by vulnerability. Each vulnerability and the device IDs impacted are an item in the items list. groupby=device organizes results into groups by device ID. Each device ID and a single vulnerability are an item in the items list.
    To request all vulnerability instances for a specific device, the value is the string vulnerability followed by &deviceid='<'device_id'>', where the device ID is either a MAC address or, for static IP devices, an IP address. (Entering an IP address for a device whose device identifier is a MAC address doesn’t work. Similarly, entering a MAC address for a device whose device identifier is an IP address also doesn’t work.)

Responses​

Successful Response (We only show some important fields here.)

Schema
    oneOf
    total integer

    The number of vulnerablity instances matching the request

    items object[]

    An array containing vulnerablity instances

  • Array [
    • name string

    The hostname of the device associated with a vulnerability instance

    ip string

    The IP address of a device associated with a vulnerability instance

    deviceid string

    The MAC address or IP address of the device

    profile string

    The profile to which the device belongs

    profile_vertical string

    The vertical to which the device profile belongs

    display_profile_category string

    The category to which the device profile belongs

    vendor string

    The device vendor

    model string

    The device model

    os string

    The device OS

    osCombined string

    The OS and OS version combined

    siteid string

    The ID of the site where the device is deployed

    asset_tag string

    The asset tag of the device; if none, then “null” is returned

    sn string

    The device serial number

    date string

    The date of the latest activity of the device

    risk_score integer

    The risk score of the vulnerability instance

    risk_level string

    The risk level of the vulnerability instance: Low, Medium, High, or Critical

    ticketState string

    The state of the zb_ticket for a vulnerability instance —investigation, remediation, resolved, or new if the vulnerability was detected but nobody has yet taken action to address it

    zb_ticketid string

    The unique ticket ID for a vulnerability instance

    ticketAssignees string

    The email address of one or more people assigned to remediate a vulnerability instance; if there aren’t any, null is returned

    reason_history string

    An array that holds the history of all actions taken on a vulnerability instance, including status changes, user notes, if it was sent to asset management, and if it was resolved; if no actions were taken, null is returned

    remediate_workorder string

    The work order number returned from an integrated third-party asset management system such as AIMS, Connectiv, Nuvolo, or ServiceNow to which a vulnerability instance was sent

    remediate_checkbox string

    Index values indicating the type of information sent to asset management; 0 = vulnerability summary, 1 = vulnerability impact, 2 = device information

    remediate_instruction string

    Additional instructions included with the work order

    detected_date string

    The date when a vulnerability instance was originally detected

    vulnerability_name string

    The name of the vulnerability

    allTags object[]

    An array of user-defined tags assigned to the device. Each item in the array consists of three attributes: tagType, tagValue, and tagId.

  • Array [
    • tagType string

    The key for a user-defined tag

    tagValue string

    The value of the tag key for a user-defined tag

    tagId string

    The ID of a user-defined tag

  • ]
  • ]
Loading...