IoT Security API Reference
    : Get Security Alerts
    Focus
    Download PDF
    Focus
    1. Home
    2. IoT
    3. IoT Security API Reference
    4. IoT Security API
    5. Get Security Alerts
    Download PDF

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

    © 2024 Palo Alto Networks, Inc. All rights reserved.