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.
    Parameter
    Example
    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
    Value
    Description
    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:
      Assets
      Devices
      Vulnerabilities
      Vulnerability Overview
      Alerts
      Security 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
      Assets
      Devices
       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 tools
      Developer 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.

    Recommended For You

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