Skip to main content

Vulnerabilities​

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

Query Parameters
  • customerid string required

    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
  • total integer

    The number of vulnerablities matching the request

  • items object[]

    An array containing vulnerablities

  • 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...