Focus

IoT Security API Reference

Get Vulnerability Instances

Table of Contents

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

You can also use queries from the IoT Security portal to customize which vulnerability instances are retrieved.

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}

Resolve a Security Alert

Resolve Vulnerability Instances