Focus

IoT Security API Reference

Get Security Alerts

Table of Contents

Get Security Alerts

Use the IoT Security API to get a list of security alerts.

Synopsis

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

Description

Get a list of security alerts.

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.
type	Optional field specifying the alert type as policy_alert. The following value is a string.
resolved	Optional field to get only active alerts (resolved=no) or resolved alerts (resolved=yes). The default is to get both types of alerts. The following value is a string.
pagelength	Optional but recommended field specifying the number of items for each page. The default page length for alerts is 1000 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 device alerts. To get the next 100, add offset = 100 to your second request. This skips the first 100 alerts and gets the next 100 starting from 101.
stime	Optional string that sets the start of a time range for alerts to retrieve. For example, stime=2021-10-6T07:00Z. (It’s unnecessary to set etime=now or etime=<time> because it is always treated as now.)
sortdirection	Optional field defining whether the alerts are organized in ascending order asc (oldest to newest) or descending order desc (newest to oldest). The default is desc. The following value is a string.
sortfield	Optional field that defines how alerts are ordered. date and severityNumber are supported as the following value and the value types are string and integer respectively. The default way to sort alerts is by date in descending order.

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

Request Example

curl --location -X GET  'https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/alert/list?customerid=acmecorp&type=policy_alert&resolved=no&pagelength=1&sortdirection=desc&sortfield=date' \
-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
resolved	Whether the alert has been resolved yesor not no (string)
date	The alert detection date
deviceid	The MAC address or IP address of a device (string)
name	The alert name (string)
severity	The severity level of an alert: high, medium, low, info (string)
severityNumber	The severity number matching the severity level: high = 4, medium = 3, low = 2, info = 1 (integer)
type	The type of alert (string)
description	The alert description (string)
tenantid	The internal customer ID (string)
zb_ticketid	The unique ticket ID (integer)
id	The alert ID. This is the ID to use when resolving an alert through the API (integer)
profile	The device profile to which the alert belongs (string)
profile_vertical	The industry vertical for the profile such as Medical, IT Devices, and Office.
category	The device category to which the alert belongs (string)
hostname	The hostname of the device to which the alert belongs (string)
siteid	The ID number that IoT Security assigns to the site for internal use (string)
serviceLevel	(For MSSP only) The level of service for an MSSP customer as defined by the MSSP owner; for example: Tier 1, Tier 2, Tier 3; or Platinum, Gold, Silver (string)
trafficDirection	The direction of the traffic on the device that triggered the alert; inbound if the device is a server and outbound if it is a client (string)
siteName	The name of the site where the alert occurred (string)
reason_history	The history of actions taken to investigate and resolve the alert (string)
total	The overall number of security alerts for all the IoT devices in your inventory

Success Response Example

{"ver": "v4.0",
    "api": "/alert/list",
    "items": [
         {
            "resolved": "no",
            "date": "2020-05-12T01:23:10.630Z",
            "deviceid": "18:65:90:cd:88:0d",
            "name": "zingcloud alert bg job integration test at 1589246590630",
            "severity": "high",
            "severityNumber": 4,
            "type": "policy_alert",
            "description": "The baseline policy defines a criteria to match normal connections between devices in two different networks or device groups. It is a positive detection if connections outside of this definition are observed.",
            "tenantid": "acmecorp"
            "zb_ticketid": "alert-hNMleG1nW",
            "id": "5eb9fa8127b736d82bf7840a",
            "profile": "Macintosh-MacPro",
            "profile_vertical": "IT Devices",
            "category": "Personal Computer",
            "hostname": "cntl-201-2",
            "siteid": "0",
            "serviceLevel": "",
            "trafficDirection": "inbound",
            "siteName": "acmecorp-hq",
            "reason_history": []
            "msg": {
                "severity": "high",
                "description": "The baseline policy defines criteria to match normal connections between devices in two different networks or device groups. It is a positive detection if connections outside of this definition are observed.",
                "name": "zingcloud alert bg job integration test at 1589246590630",
                "id": "hNMleG1nW",
                "ruleid": "5a26f169c8272f0b00c5ef1a",
                "zb_ticketid": "alert-hNMleG1nW",
                "hostname": "unknown",
                ...            }        },
                    . . .
    ],
    "total": 39
}

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 security alerts 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}

Get Profile Mapping

Resolve a Security Alert