Get Vulnerability Instances

Use the IoT Security API to get a list of vulnerability instances.

Synopsis

URI
/pub/v4.0/vulnerability/list
HTTP Method
GET
FQDN
<customer-name>.iot.paloaltonetworks.com

Description

Get a list of device vulnerability instances.

Request Fields

The URL of this request contains the following parameters:
Field
Description
customerid
(
Required
) The customer ID specifies the API call for a specific tenant.
The following value is a string.
stime
Optional field setting the start of a time range for retrieving vulnerability instances. For example, to get all instances since November 3, 2020 (Pacific Standard Time), the start time would be
stime=2020-11-3T08:00Z
.
pagelength
Optional but recommended field specifying the number of items for each page. The default page length for vulnerabilities is unlimited and the maximum is 1000. Setting a shorter length improves response times. The following value is an integer.
offset
In addition to the
pagelength
parameter, use
offset
to get items on subsequent pages. For example, if your first request is
pagelength = 100
, you will get the first 100 vulnerabilities (indexed from 0 to 99). 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 index number 100.
name
Optional field defining a specific vulnerability. If omitted, instances for all vulnerabilities are returned. The following value is a string.
status
Optional field that retrieves only confirmed or potential vulnerability instances. The following field is either the string
Confirmed
or
Potential
. If no value is passed, both types of vulnerabilities are returned.
groupby
(
Required
) When requesting all vulnerability instances, the value is the string
device
. When requesting 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.
Request All Vulnerability Instances Example
curl 'https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/vulnerability/list?customerid=acmecorp&groupby=device' -H 'X-Key-Id: <key_id>' -H 'X-Access-Key: <access_key>'
Request All Vulnerability Instances for a Specific Device Example
curl 'https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/vulnerability/list?customerid=acmecorp&pagelength=10&groupby=vulnerability&deviceid=64 :16:7f:0a:f6:38' -H 'X-Key-Id: <key_id>' -H 'X-Access-Key: <access_key>'

Success Response

Upon success, the HTTP response code is 200. In addition, this API returns a JSON object containing an array of JSON objects, representing devices and their attributes.
Field
Description
items
Introduces items in the list of vulnerability instances
name
The hostname of the device associated with a vulnerability instance (string)
ip
The IP address of the device associated with a vulnerability instance (string)
deviceid
The MAC address or IP address of the device (string)
profile
The profile to which the device belongs (string)
profile_vertical
The vertical to which the device profile belongs (string)
display_profile_category
The category to which the device profile belongs (string)
vendor
The device vendor (string)
model
The device model (string)
os
The device OS (sting)
osCombined
The OS and OS version combined (string)
siteid
The ID of the site where the device is deployed (string)
asset_tag
The asset tag of the device; if none, then “null” is returned (string)
sn
The device serial number (string)
date
The date of the latest activity of the device (string)
risk_score
The risk score of the vulnerability instance (integer)
risk_level
The risk level of the vulnerability instance: Low, Medium, High, or Critical (string)
ticketState
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 (string)
zb_ticketid
The unique ticket ID for a vulnerability instance (integer)
ticketAssignees
The email address of one or more people assigned to remediate a vulnerability instance; if there aren’t any,
null
is returned (string)
reason_history
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 (string)
remediate_workorder
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 (string)
remediate_checkbox
Index values indicating the type of information sent to asset management; 0 = vulnerability summary, 1 = vulnerability impact, 2 = device information
remediate_instruction
Additional instructions included with the work order (string)
detected_date
The date when a vulnerability instance was originally detected (string)
vulnerability_name
The name of the vulnerability (string)
Success Response for All Vulnerability Instances Example
{ "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" } . . . ] }
Success Response for All Vulnerability Instances for a Specific Device Example
{ "ver": "v4.0", "api": "/vulnerability/list", "items": [ { "data": { "Potential": { "device": [ "64:16:7f:0a:f6:38" ], "profile": [ "Polycom Device" ] } }, "tenantid": "acmecorp", "name": "CVE-2018-18568", "serviceLevel": "", "severity": "Medium", "date": "2019-11-19T23:59:59", "CVSS": 5.9, "description": "Polycom VVX 500 and 601 devices 5.8.0.12848 and earlier allows man-in-the-middle attackers to obtain sensitive credential information by leveraging failure to validate X.509 certificates when used with an on-premise installation with Skype for Business.", "source": "NIST", "vulnerability_types": [ "Obtain Information" ] } ] }

Error Response

Upon error, the reply includes an HTTP response code, an error message, and additional information describing the error. The HTTP response code is one of the following:
Field
Description
400
Bad Request. Got an invalid JSON.
401
Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.
402
Unauthorized access. User does not have the required license type to run this API.
403
Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.
500
Internal server error. A unified status for API communication type errors.
Error Response Format
{code: STATUS_CODE, msg: GENERAL_MESSAGE}

Recommended For You