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 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
.
pagelength
Optional but recommended field specifying the number of items for each page. The default page length for vulnerabilities is 1000 and the maximum is 1000. Setting a shorter length improves response times. The following value is an integer.
The
pagelength
parameter is only valid when grouping vulnerability instances by device, not when grouping them by vulnerability.
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.
The
offset
parameter is only valid when grouping vulnerability instances by device, not when grouping them by vulnerability.
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
) This specifies how to group 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.)
Request All Vulnerability Instances Grouped by Device Example
curl --location -X GET '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 --location -X GET 'https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/vulnerability/list?customerid=acmecorp&groupby=device&deviceid=64:16:7f:0a:f6:38' \ -H 'X-Key-Id: KEY_ID' \ -H 'X-Access-Key: ACCESS_KEY'
Request All Vulnerability Instances Grouped by Vulnerability Example
curl --location -X GET 'https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/vulnerability/list?customerid=acmecorp&groupby=vulnerability' \ -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.
The fields returned differ depending on whether you group results by device or by vulnerability. Both sets of fields are shown below.
When the request includes
groupby=device
, the response includes the following fields:
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)
tagIdList
A list of IDs for user- and system-defined tags assigned to a device
allTags
An array of user-defined tags assigned to the device. Each item in the array consists of three attributes:
tagType
,
tagValue
, and
tagId
.
tagType
The key for a user-defined tag
tagValue
The value of the key for a user-defined tag
tagId
The ID of a user-defined tag
total
The total overall number of vulnerability instances on the devices in your network
When the request includes
groupby=vulnerability
, the response includes the following fields:
Field
Description
items
Introduces items in the list of vulnerability instances
data
The device profiles, IoT devices, and number of addressed instances for confirmed and potential instances in a vulnerability group
Potential
The following data is for potential vulnerability instances
Confirmed
The following data is for confirmed vulnerability instances
profile
The device profiles that the vulnerability affects or potentially affects
device
List of device IDs of all IoT devices that are vulnerable or potentially vulnerable
addressedInstance
The number of instances that have been addressed
name
Name of the vulnerability; for example, CVE-2015-3959 or Windows SMBv1 Usage
cvssVersion
v2
or
v3
Score ranges are different for the two Common Vulnerability Scoring System versions. Version 2 has three score ranges: Low 0.0 - 3.9, Medium 4.0 - 6.9, High 7.0 - 10.0. Version 3 has five ranges: None - 0.0, Low 0.1 - 3.9, Medium 4.0 - 6.9, High, 7.0 - 8.9, Critical 9.0 - 10.0.)
severity
Low
,
Medium
,
High
,
Critical
Only vulnerabilities with a CVSSv3 rating can have a Critical severity level.
date
The most recent date that an instance of this vulnerability was detected on an IoT device
CVSS
The CVSS score for the vulnerability; for example, 10.0
description
A description of what the vulnerability is and how it can be exploited
deviceid
The MAC address or IP address of a device that either has or potentially has a vulnerability
source
The source of the vulnerability detection:
IoT Security
when IoT Security learns it through its own detection and analysis; or, if learned through integration with a third-party vulnerability scanner, the name of the scanner–
Qualys
,
Rapid7
,
Tenable
vulnerability_types
The type of attack to which a vulnerability makes a device susceptible; for example,
Code Execution
,
Overflow
,
Info Leak
,
Denial of Service
deviceTags
A list of device IDs of all vulnerable and potentially vulnerable IoT devices and any tags they might have
allTags
An array of user-defined tags assigned to the device. Each item in the array consists of three attributes:
tagType
,
tagValue
, and
tagId
.
tagType
The key for a user-defined tag
tagValue
The value of the key for a user-defined tag
tagId
The ID of a user-defined tag
source
The source of the vulnerability detection:
IoT Security
when IoT Security learns it through its own detection and analysis; or, if learned through integration with a third-party vulnerability scanner, the name of the scanner–
Qualys
,
Rapid7
,
Tenable
total
The total number of vulnerabilities affecting devices in your network
Success Response for All Vulnerability Instances (
groupby=device
) Example
{ "ver": "v4.0", "api": "/vulnerability/list", "items": [ { "deviceid": "64:16:7f:37:2d:45", "detected_date": [ "2021-04-19T23:59:59" ], "name": "Polycom_64167f372d45", "ip": "10.1.1.84", "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": "2021-03-12T01:28:26.986Z", "risk_score": 20, "risk_level": "Low", "tagIdList": [ "6030135777a1d6fb488e26ad", "60301332ff1679e9481b62a6" ], "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": "Owner", "tagValue": "Joe", "tagId": "6030135777a1d6fb488e26ad" }, { "tagType": "com-devices", "tagValue": "phones", "tagId": "60301332ff1679e9481b62a6" }, ] } ... ] "total": 34, }
Success Response for All Vulnerability Instances (
groupby=vulnerability
) Example
{ "ver": "v4.0", "api": "/vulnerability/list", "items": { "items": [ { "data": { "Potential": { "profile": [ "Arista Networks Device", "Cisco Systems Device" ], "device": [ "00:1c:73:20:c4:b5", "00:1c:73:16:a6:33", "00:57:d2:27:d2:d1" ], "addressedInstance": 0 } "Confirmed": { "profile": [ "Roles-Network-Router", "Cisco Networking Switch" ], "device": [ "e4:d3:f1:40:e8:c0", "08:17:35:77:d0:c1" ], "addressedInstance": 0 } }, "name": "CVE-2019-1737", "tenantid": "", "cvssVersion": "v3", "serviceLevel": null, "severity": "High", "date": "2022-07-18T23:59:59.000Z", "CVSS": 8.6, "description": "A vulnerability in the processing of IP Service Level Agreement (SLA) packets by Cisco IOS Software and Cisco IOS XE software could allow an unauthenticated, remote attacker to cause an interface wedge and an eventual denial of service (DoS) condition on the affected device. The vulnerability is due to improper socket resources handling in the IP SLA responder application code. An attacker could exploit this vulnerability by sending crafted IP SLA packets to an affected device. An exploit could allow the attacker to cause an interface to become wedged, resulting in an eventual denial of service (DoS) condition on the affected device.", "source": "IoT Security", "vulnerability_types": [ "Denial Of Service" ] }, ... ] "deviceTags": { "08:17:35:77:d0:c1": { "deviceid": "08:17:35:77:d0:c1", "allTags": [ { "tagType": "lab", "tagValue": "l3", "tagId": "62acbf20a5fb040006174076" }, { "tagType": "location", "tagValue": "office14", "tagId": "62acbf74a5fb040006174078" }, { "tagType": "Forescout", "tagValue": "In Scope", "tagId": "6144c5700a5895bbb5384b88" }, ] }, "00:0f:11:00:e9:f2": { "deviceid": "00:0f:11:00:e9:f2" }, "00:a0:aa:00:01:96": { "deviceid": "00:a0:aa:00:01:96" }, ... } } "total": 61 }

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. This occurs when an HTTP request contains an invalid query string.
403
Forbidden access. Either the provided API Key is invalid or it does not have the required RBAC permissions to run this API.
429
Too many requests. The number of requests for a list of vulnerability instances exceeded the rate limit of 180 queries per minute per tenant.
500
Internal server error. A unified status for API communication type errors.
Error Response Format
{code: STATUS_CODE, msg: GENERAL_MESSAGE}

Recommended For You