IoT Security API Reference
    : Get Started with the IoT Security API
    Focus
    Download PDF
    Focus
    1. Home
    2. IoT
    3. IoT Security API Reference
    4. IoT Security API Overview
    5. Get Started with the IoT Security API
    Download PDF

    IoT Security API Reference

    Get Started with the IoT Security API

    Table of Contents

    Get Started with the IoT Security API

    Learn what’s necessary to use the IoT Security API.
    The following parameters are used in queries sent to the IoT Security API.
    ParameterExample
    Protocol
    https
    Tenant-specific URIs
    acmecorp.iot.paloaltonetworks.com where acmecorp is the tenant ID (customer ID)
    A tenant is the organization that owns an IoT Security account.
    Path/pub/v4.0/
    Function call
    device retrieves details about an individual device by device ID. This is typically its MAC address but when a device is configured as a static IP device, the device ID is its IP address.
    device/ip retrieves details about one or more devices by IP address.
    device/list retrieves the entire device inventory for a tenant.
    profile/mapping retrieves a complete list of profile-category-vertical mappings.
    alert/list retrieves the entire list of security and system alerts.
    vulnerability/list retrieves the entire list of vulnerability instances.
    alert/update resolves a security alert.
    vulnerability/update resolves one or more vulnerability instances.
    device/update adds a user tag to one or more devices.
    tag/list retrieves a list of user-defined tags for devices.
    policy/recommendation retrieves all active policy rule recommendations or those for one or more device profiles.
    When retrieving a list of items or details for a single item, the properties can be in any order within the returned JSON object.
    General parameters
    customerid=acmecorp indicates the customer ID.
    offset=1 is an optional integer that sets the number of items to skip.
    pagelength=20 is an optional integer that sets the number of items in one response; that is, in one page. The maximum page length you can set is 1000. The default page length for alerts, devices, and vulnerability instances is 1000. Because of these high default values, we recommend setting the page length to a smaller number, especially for alerts and vulnerabilities.
    Device-specific parameters
    deviceid=34:02:86:44:65:36 specifies the MAC address of a device. For a static IP device, the device ID is its static IP address.
    ip=192.168.10.121 specifies the IP address of a device.
    detail=false is an optional Boolean value requesting the level of device details to be returned. The default is false.
    detail=true enters detail mode, which returns more device properties; for example: ‘https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/device?detail=true&customerid=acmecorp’
    stime=2020-11-3T08:00Z is an optional string that sets the start of a time range for devices to retrieve. This is the time when a device was last active. (It’s unnecessary to set etime=now or etime=<time> because it is always treated as now.)
    sortdirection=asc is an optional string that sets the alphanumeric order in which devices are displayed by MAC address. asc indicates an ascending order from smallest to largest. desc, which is the default, indicates a descending order from largest to smallest.
    sortfield=MAC is an optional string that sets the field by which returned devices are sorted. Currently only MAC is supported.
    You can use queries from the IoT Security portal to customize which devices are retrieved.
    Alert-specific parameters
    type=policy_alert is an optional string that returns security alerts. This is the only type of alert supported.
    resolved=yes is an optional string that returns only resolved alerts. no is the default and returns only active alerts.
    stime=2020-11-3T08:00Z is an optional string that sets the start of a time range for alerts to retrieve. (It’s unnecessary to set etime=now or etime=<time> because it is always treated as now.)
    sortdirection=asc is an optional string that sets the chronological order in which alerts are displayed. asc is from oldest to newest. desc is from newest to oldest and is the default.
    sortfield=date is an optional string that sets the field by which returned alerts are sorted. Currently only date is supported.
    You can use queries from the IoT Security portal to customize which security alerts are retrieved.
    Vulnerability-specific parameters
    name=CVE-2018-18568 is an optional string that retrieves all instances of a specific vulnerability among your devices.
    status=Confirmed is an optional string that retrieves only confirmed vulnerabilities. Potential retrieves potential but unconfirmed vulnerabilities. If no value is passed, both types of vulnerabilities are retrieved.
    groupby is a required string. It specifies how to group device vulnerability instances in query results:
    groupby=device groups results by device ID. Each device ID and a single vulnerability are an item in the items list.
    groupby=vulnerability (the default) groups results by vulnerability. Each vulnerability and the device IDs impacted are an item in the items list.
    You can use queries from the IoT Security portal to customize which vulnerability instances are retrieved.
    Authentication and authorization
    IoT Security issues the API Access Key and its ID. To authenticate and authorize your requests, pass the access key and its ID by adding two extra request headers:
    X-Key-ID: KEY_ID
    X-Access-Key: ACCESS_KEY
    For your requests to be authorized, the access key must be active and the user who created the key must be an owner or administrator.
    To prevent DoS (denial-of-service) attacks on our system, IoT Security imposes rate limits. When queries are for device/list, the rate limit is a maximum of 60 queries per minute per tenant because of the intensive amount of data that can potentially be returned. For everything else, the rate limit is 180 queries per minute.
    Before you can begin using the IoT Security API, you must generate the following from the IoT Security app:
    • API Access Key
    • API Key ID
    ValueDescription
    API Access Key
    The API Access Key is your unique token that’s used as the "X-Access-Key: ACCESS_KEY" request header required for authenticating API calls.
    API Key ID
    The API Key ID is your unique identifier used to authenticate the API Access Key. The request header that’s used when running an API call is "X-Key-Id: KEY_ID".
    The following steps describe how to generate the necessary key values.
    1. Log in to the IoT Security portal and click
      Preferences      .
    2. In the User Role & Access section, click Create next to API Access Key and follow the online steps to create an access key.
    3. View and download the access key and key ID, saving them in a secure location. Your code must include both when making calls to the API.
      You can later return to the Preferences page to view the key ID. However, for security reasons, it is not possible to view the actual key in the IoT Security portal.

    Use Queries from the IoT Security Portal

    You can copy a query from the IoT Security portal, convert it to an ASCII string, and paste it in API requests to get customized lists of devices, vulnerability instances, and security alerts.
    1. Log in to the IoT Security portal and open one of the following pages:
      AssetsDevices
      VulnerabilitiesVulnerability Overview
      AlertsSecurity Alerts
    2. At the top of the page, click Query and use the query builder to define a query to fetch the list of items you want to see.
      For example, the following query on the AssetsDevices page gets a list of various network devices at high or critical risk levels.
    3. Click the Copy to clipboard icon (
      ) at the far right of the Query builder field.
    4. Open a JavaScript console and use the btoa command to convert the binary string to a Base64-encoded ASCII string.
      For example, in a Chrome browser, click the three vertical dots icon (
      )       More toolsDeveloper tools      , click the Console tab, and then enter:
      btoa('SELECT * FROM "device" WHERE ( ml_risk_level IN ("High", "Critical") AND
        category IN ("Network Equipment", "Network Management", "Network Security Equipment")
        )')
      This produces the following ASCII string:
      'U0VMRUNUICogRlJPTSAiZGV2aWNlIiBXSEVSRSAoIG1sX3Jpc2tfbGV2ZWwgSU4gKCJIaWdoIiwgIkNyaXRpY2FsIikgQU5EIGNhdGVnb3J5IElOICgiTmV0d29yayBFcXVpcG1lbnQiLCAiTmV0d29yayBNYW5hZ2VtZW50IiwgIk5ldHdvcmsgU2VjdXJpdHkgRXF1aXBtZW50IikgKQ=='
    5. Copy the ASCII string, excluding the single quotation marks and paste it into the get request as a SQL string (sql_str parameter) after the tenant name.
      When you copy a query from the IoT Security portal, the time filters that you see on the page aren’t included. By default, an API request using the query will get all results to date. If you want to include a time filter, use the stime parameter as shown in the example below.
      Example:
      curl --location -X GET 'http://acmecorp.iot.paloaltonetworks.com/pub/v4.0/device/list?customerid=staging-banff-test&stime=2023-07-01T08:00Z&sql_str=U0VMRUNUICogRlJPTSAiZGV2aWNlIiBXSEVSRSAoIG1sX3Jpc2tfbGV2ZWwgSU4gKCJIaWdoIiwgIkNyaXRpY2FsIikgQU5EIGNhdGVnb3J5IElOICgiTmV0d29yayBFcXVpcG1lbnQiLCAiTmV0d29yayBNYW5hZ2VtZW50IiwgIk5ldHdvcmsgU2VjdXJpdHkgRXF1aXBtZW50IikgKQ=='\
-H 'X-Key-Id: KEY_ID' \
-H 'X-Access-Key: ACCESS_KEY'
      When requesting a device list, use only [device] options in the query builder; do not include any [vulnerability] or [alert] options. Although the IoT Security portal UI supports queries that combine devices and security alerts or devices and vulnerabilities, the API doesn’t support these combinations.

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