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.
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
yes
or 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}

Recommended For You