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.)
- 200
- 4XX
- 5XX
Successful Response (We only show some important fields here.)
- application/json
- Schema
- Example (from schema)
- vulnerabilityListResponseExample
Schema
- total integer
The number of vulnerablities matching the request
items object[]
An array containing vulnerablities
Array [name stringThe hostname of the device associated with a vulnerability instance
ip stringThe IP address of a device associated with a vulnerability instance
deviceid stringThe MAC address or IP address of the device
profile stringThe profile to which the device belongs
profile_vertical stringThe vertical to which the device profile belongs
display_profile_category stringThe category to which the device profile belongs
vendor stringThe device vendor
model stringThe device model
os stringThe device OS
osCombined stringThe OS and OS version combined
siteid stringThe ID of the site where the device is deployed
asset_tag stringThe asset tag of the device; if none, then “null” is returned
sn stringThe device serial number
date stringThe date of the latest activity of the device
risk_score integerThe risk score of the vulnerability instance
risk_level stringThe risk level of the vulnerability instance: Low, Medium, High, or Critical
ticketState stringThe 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 stringThe unique ticket ID for a vulnerability instance
ticketAssignees stringThe email address of one or more people assigned to remediate a vulnerability instance; if there aren’t any, null is returned
reason_history stringAn 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 stringThe 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 stringIndex values indicating the type of information sent to asset management; 0 = vulnerability summary, 1 = vulnerability impact, 2 = device information
remediate_instruction stringAdditional instructions included with the work order
detected_date stringThe date when a vulnerability instance was originally detected
vulnerability_name stringThe 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 stringThe key for a user-defined tag
tagValue stringThe value of the tag key for a user-defined tag
tagId stringThe ID of a user-defined tag
]]
{
"total": 0,
"items": [
{
"name": "string",
"ip": "string",
"deviceid": "string",
"profile": "string",
"profile_vertical": "string",
"display_profile_category": "string",
"vendor": "string",
"model": "string",
"os": "string",
"osCombined": "string",
"siteid": "string",
"asset_tag": "string",
"sn": "string",
"date": "string",
"risk_score": 0,
"risk_level": "string",
"ticketState": "string",
"zb_ticketid": "string",
"ticketAssignees": "string",
"reason_history": "string",
"remediate_workorder": "string",
"remediate_checkbox": "string",
"remediate_instruction": "string",
"detected_date": "string",
"vulnerability_name": "string",
"allTags": [
{
"tagType": "string",
"tagValue": "string",
"tagId": "string"
}
]
}
]
}
{
"ver": "v4.0",
"api": "/vulnerability/list",
"items": [
{
"name": "Polycom_64167f372d45",
"ip": "10.1.1.84",
"deviceid": "64:16:7f:37:2d:45",
"profile": "Polycom IP Phone",
"profile_vertical": "Office",
"display_profile_category": "IP Phone",
"vendor": "Polycom",
"model": "VVX601",
"os": "Embedded",
"osCombined": "Embedded",
"siteid": "0",
"asset_tag": null,
"sn": null,
"date": "2020-05-12T01:28:26.986Z",
"risk_score": 20,
"risk_level": "Low",
"ticketState": "new",
"zb_ticketid": "vuln-52f40a58",
"ticketAssignees": [
"analyst1@acmecorp.com"
],
"reason_history": [
{
"action": "sent to asset management: aims",
"reason": "Check system",
"reason_type": null,
"user_email": "admin@acmecorp.com",
"timestamp": "2019-10-18T22:00:20.255Z",
"aims_workorder_number": 152027
}
],
"remediate_workorder": "152027",
"remediate_checkbox": "0,1,2",
"remediate_instruction": null,
"detected_date": "2019-10-15T20:18:42.135Z",
"vulnerability_name": "CVE-2019-12948",
"allTags": [
{
"tagType": "TestFilter",
"tagValue": "withTagInLocalFilter5",
"tagId": "6030135777a1d6fb488e26ad"
},
{
"tagType": "TestFilter",
"tagValue": "withTagInLocalFilter4",
"tagId": "60301332ff1679e9481b62a6"
}
]
}
]
}
Client Error Response
- application/json
- Schema
- Example (from schema)
- Bad Request
- Forbidden access
- Too many requests
Schema
- code string
STATUS_CODE
- msg string
GENERAL_MESSAGE
{
"code": "string",
"msg": "string"
}
{
"code": 400,
"msg": "Bad Request. This occurs when an HTTP request contains an invalid query string."
}
{
"code": 403,
"msg": "Forbidden access. Either the provided API key is invalid or it does not have the required RBAC permissions to run this API."
}
{
"code": 429,
"msg": "Too many requests. The number of requests for device details for a single device exceeded the rate limit of 180 queries per minute per tenant."
}
Server Error Response
- application/json
- Schema
- Example (from schema)
- vulnerabilityListResponseExample
Schema
- code string
STATUS_CODE
- msg string
GENERAL_MESSAGE
{
"code": "string",
"msg": "string"
}
{
"code": 500,
"msg": "Internal server error. A unified status for API communication type errors."
}