IoT Security API

openapi: 3.1.0
info:
  title: Palo Alto Networks IoT Security API
  description: >-
    REST API for managing IoT and OT device security through Palo Alto
    Networks IoT Security cloud service. Provides device discovery and
    profiling, risk assessment, alert management, vulnerability tracking,
    and policy recommendation capabilities. Enables integration with
    third-party SIEM, SOAR, CMDB, and NAC platforms for automated
    security workflows. Requires an active IoT Security subscription.
  version: '4.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://{customer}.iot.paloaltonetworks.com/pub/v4.0
  description: IoT Security API production server.
  variables:
    customer:
      description: Customer-specific tenant identifier.
      default: customer-tenant
security:
- keyId: []
  accessKey: []
tags:
- name: Alerts
  description: Security alert management operations.
- name: Devices
  description: IoT and OT device discovery and profiling operations.
- name: Policies
  description: Security policy recommendation operations.
- name: Reports
  description: Asset and inventory reporting operations.
- name: Vulnerabilities
  description: Device vulnerability tracking operations.
paths:
  /device/list:
    get:
      operationId: listDevices
      summary: Palo Alto Networks List Discovered Devices
      description: >-
        Returns a paginated list of IoT and OT devices discovered on the
        network. Supports filtering by monitoring status and time range.
        Each device record includes identification details, network
        information, risk assessment, and classification metadata.
      tags:
      - Devices
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '858936'
      - name: offset
        in: query
        description: Pagination offset for results.
        schema:
          type: integer
          default: 0
        example: 0
      - name: pagelength
        in: query
        description: Number of devices to return per page.
        schema:
          type: integer
          default: 100
          maximum: 1000
        example: 100
      - name: detail
        in: query
        description: Level of detail to include in the response.
        schema:
          type: string
          enum:
          - full
          - summary
          default: summary
        example: summary
      - name: filter_monitored
        in: query
        description: Filter for monitored or unmonitored devices.
        schema:
          type: string
          enum:
          - 'yes'
          - 'no'
        example: 'no'
      - name: stime
        in: query
        description: >-
          Start time filter as a Unix epoch timestamp in seconds.
          Returns devices active since this time.
        schema:
          type: string
        example: example-stime
      - name: etime
        in: query
        description: >-
          End time filter as a Unix epoch timestamp in seconds.
          Returns devices active before this time.
        schema:
          type: string
        example: example-etime
      responses:
        '200':
          description: Device list returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of devices matching the query.
                  devices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
              examples:
                ListDevices200Example:
                  summary: Default listDevices 200 response
                  x-microcks-default: true
                  value:
                    total: 0
                    devices:
                    - deviceid: '805631'
                      ip: 10.178.141.130
                      mac: 42:f0:fc:53:1d:d1
                      hostname: host-03a3
                      profile: Network Printer
                      category: advanced
                      risk_score: 53
                      os: Ubuntu 22.04
                      os_version: 10.5.0
                      vendor: Fortinet
                      model: VM-300
                      site: Branch-London
                      subnet: 10.32.40.0/24
                      first_seen: '2024-12-19T02:52:11Z'
                      last_seen: '2025-01-24T06:19:11Z'
                      monitored: 'no'
                      confidence_score: 533
                      tags: &id001
                      - pci-scope
                    - deviceid: '805631'
                      ip: 10.178.141.130
                      mac: 42:f0:fc:53:1d:d1
                      hostname: host-03a3
                      profile: Network Printer
                      category: advanced
                      risk_score: 53
                      os: Ubuntu 22.04
                      os_version: 10.5.0
                      vendor: Fortinet
                      model: VM-300
                      site: Branch-London
                      subnet: 10.32.40.0/24
                      first_seen: '2024-12-19T02:52:11Z'
                      last_seen: '2025-01-24T06:19:11Z'
                      monitored: 'no'
                      confidence_score: 533
                      tags: *id001
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /device/detail:
    get:
      operationId: getDeviceDetail
      summary: Palo Alto Networks Get Device Details
      description: >-
        Returns detailed information for the device associated with the
        specified device identifier. Includes full device profile, risk
        score breakdown, network activity summary, and classification
        details.
      tags:
      - Devices
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '904445'
      - name: deviceid
        in: query
        required: true
        description: Unique device identifier.
        schema:
          type: string
        example: '348066'
      responses:
        '200':
          description: Device details returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  device:
                    $ref: '#/components/schemas/Device'
              examples:
                GetDeviceDetail200Example:
                  summary: Default getDeviceDetail 200 response
                  x-microcks-default: true
                  value:
                    device:
                      deviceid: '805631'
                      ip: 10.178.141.130
                      mac: 42:f0:fc:53:1d:d1
                      hostname: host-03a3
                      profile: Network Printer
                      category: advanced
                      risk_score: 53
                      os: Ubuntu 22.04
                      os_version: 10.5.0
                      vendor: Fortinet
                      model: VM-300
                      site: Branch-London
                      subnet: 10.32.40.0/24
                      first_seen: '2024-12-19T02:52:11Z'
                      last_seen: '2025-01-24T06:19:11Z'
                      monitored: 'no'
                      confidence_score: 533
                      tags: *id001
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert/list:
    get:
      operationId: listAlerts
      summary: Palo Alto Networks List Security Alerts
      description: >-
        Returns a paginated list of security alerts generated by the
        IoT Security service. Alerts are triggered by anomalous device
        behavior, policy violations, known vulnerability exploitation,
        and communication with suspicious destinations. Supports filtering
        by resolution status and time range.
      tags:
      - Alerts
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '758970'
      - name: offset
        in: query
        description: Pagination offset for results.
        schema:
          type: integer
          default: 0
        example: 0
      - name: pagelength
        in: query
        description: Number of alerts to return per page.
        schema:
          type: integer
          default: 100
          maximum: 1000
        example: 100
      - name: stime
        in: query
        description: Start time filter as a Unix epoch timestamp in seconds.
        schema:
          type: string
        example: example-stime
      - name: etime
        in: query
        description: End time filter as a Unix epoch timestamp in seconds.
        schema:
          type: string
        example: example-etime
      - name: resolved
        in: query
        description: Filter by alert resolution status.
        schema:
          type: string
          enum:
          - 'yes'
          - 'no'
        example: 'no'
      responses:
        '200':
          description: Alert list returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of alerts matching the query.
                  alerts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Alert'
              examples:
                ListAlerts200Example:
                  summary: Default listAlerts 200 response
                  x-microcks-default: true
                  value:
                    total: 701
                    alerts:
                    - id: example-id
                      type: advanced
                      severity: info
                      description: Firewall incident network violation detected incident alert monitoring traffic monitoring rule.
                      deviceid: '257277'
                      device_ip: 10.156.198.91
                      device_profile: Network Printer
                      resolved: 'no'
                      resolved_reason: example-resolved_reason
                      timestamp: '2024-05-28T18:45:09Z'
                      details: &id002 {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert/detail:
    get:
      operationId: getAlertDetail
      summary: Palo Alto Networks Get Alert Details
      description: >-
        Returns detailed information for a specific security alert by its
        identifier. Includes full alert context, affected device
        information, timeline, and recommended response actions.
      tags:
      - Alerts
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '272345'
      - name: id
        in: query
        required: true
        description: Unique alert identifier.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Alert details returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  alert:
                    $ref: '#/components/schemas/Alert'
              examples:
                GetAlertDetail200Example:
                  summary: Default getAlertDetail 200 response
                  x-microcks-default: true
                  value:
                    alert:
                      id: example-id
                      type: advanced
                      severity: info
                      description: Firewall incident network violation detected incident alert monitoring traffic monitoring rule.
                      deviceid: '257277'
                      device_ip: 10.156.198.91
                      device_profile: Network Printer
                      resolved: 'no'
                      resolved_reason: example-resolved_reason
                      timestamp: '2024-05-28T18:45:09Z'
                      details: *id002
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert/update:
    put:
      operationId: updateAlert
      summary: Palo Alto Networks Update Alert Status
      description: >-
        Updates the resolution status of a specific security alert.
        Allows marking an alert as resolved or unresolved, and provides
        a reason for the status change. Resolved alerts are retained
        for historical analysis.
      tags:
      - Alerts
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '582063'
      - name: id
        in: query
        required: true
        description: Unique alert identifier to update.
        schema:
          type: string
        example: example-id
      - name: resolved
        in: query
        required: true
        description: New resolution status for the alert.
        schema:
          type: string
          enum:
          - 'yes'
          - 'no'
        example: 'no'
      - name: reason
        in: query
        description: Reason for the status change.
        schema:
          type: string
        example: Firewall Security Security alert Security applied suspicious violation rule applied alert.
      responses:
        '200':
          description: Alert status updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the update was successful.
                  alert:
                    $ref: '#/components/schemas/Alert'
              examples:
                UpdateAlert200Example:
                  summary: Default updateAlert 200 response
                  x-microcks-default: true
                  value:
                    success: false
                    alert:
                      id: example-id
                      type: advanced
                      severity: info
                      description: Firewall incident network violation detected incident alert monitoring traffic monitoring rule.
                      deviceid: '257277'
                      device_ip: 10.156.198.91
                      device_profile: Network Printer
                      resolved: 'no'
                      resolved_reason: example-resolved_reason
                      timestamp: '2024-05-28T18:45:09Z'
                      details: *id002
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vulnerability/list:
    get:
      operationId: listVulnerabilities
      summary: Palo Alto Networks List Vulnerabilities
      description: >-
        Returns a paginated list of known vulnerabilities affecting
        discovered devices. Vulnerability data is correlated from device
        profiles, firmware versions, and known CVEs. Includes severity
        ratings, affected device counts, and remediation guidance.
      tags:
      - Vulnerabilities
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '458156'
      - name: offset
        in: query
        description: Pagination offset for results.
        schema:
          type: integer
          default: 0
        example: 0
      - name: pagelength
        in: query
        description: Number of vulnerability records to return per page.
        schema:
          type: integer
          default: 100
          maximum: 1000
        example: 100
      - name: stime
        in: query
        description: Start time filter as a Unix epoch timestamp in seconds.
        schema:
          type: string
        example: example-stime
      - name: etime
        in: query
        description: End time filter as a Unix epoch timestamp in seconds.
        schema:
          type: string
        example: example-etime
      responses:
        '200':
          description: Vulnerability list returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of vulnerabilities matching the query.
                  vulnerabilities:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vulnerability'
              examples:
                ListVulnerabilities200Example:
                  summary: Default listVulnerabilities 200 response
                  x-microcks-default: true
                  value:
                    total: 171
                    vulnerabilities:
                    - id: example-id
                      cve: example-cve
                      vulnerability_name: Production Gateway 97
                      severity: critical
                      cvss_score: 41.94
                      deviceid: '527185'
                      affected_device_count: 436
                      description: Security rule blocked Security monitoring rule applied.
                      remediation: example-remediation
                      first_detected: '2026-01-17T19:27:21Z'
                    - id: example-id
                      cve: example-cve
                      vulnerability_name: Production Gateway 97
                      severity: critical
                      cvss_score: 41.94
                      deviceid: '527185'
                      affected_device_count: 436
                      description: Security rule blocked Security monitoring rule applied.
                      remediation: example-remediation
                      first_detected: '2026-01-17T19:27:21Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vulnerability/detail:
    get:
      operationId: getVulnerabilityDetail
      summary: Palo Alto Networks Get Vulnerability Details
      description: >-
        Returns detailed information about a specific vulnerability
        affecting a device. Includes full CVE information, affected
        device context, severity scoring, and remediation guidance.
      tags:
      - Vulnerabilities
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '958434'
      - name: deviceid
        in: query
        required: true
        description: Unique device identifier.
        schema:
          type: string
        example: '543948'
      - name: vulnerability_name
        in: query
        required: true
        description: Name of the vulnerability to retrieve details for.
        schema:
          type: string
        example: Branch Sensor 56
      responses:
        '200':
          description: Vulnerability details returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  vulnerability:
                    $ref: '#/components/schemas/Vulnerability'
              examples:
                GetVulnerabilityDetail200Example:
                  summary: Default getVulnerabilityDetail 200 response
                  x-microcks-default: true
                  value:
                    vulnerability:
                      id: example-id
                      cve: example-cve
                      vulnerability_name: Production Gateway 97
                      severity: critical
                      cvss_score: 41.94
                      deviceid: '527185'
                      affected_device_count: 436
                      description: Security rule blocked Security monitoring rule applied.
                      remediation: example-remediation
                      first_detected: '2026-01-17T19:27:21Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /policy/recommendation:
    get:
      operationId: getPolicyRecommendation
      summary: Palo Alto Networks Get Policy Recommendations
      description: >-
        Returns policy recommendations generated by the IoT Security
        service based on observed device behavior and communication
        patterns. Recommendations include suggested security rules,
        microsegmentation policies, and access control configurations
        that can be applied to Palo Alto Networks firewalls.
      tags:
      - Policies
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '134137'
      - name: deviceid
        in: query
        description: Filter recommendations for a specific device.
        schema:
          type: string
        example: '876712'
      responses:
        '200':
          description: Policy recommendations returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of recommendations.
                  recommendations:
                    type: array
                    items:
                      $ref: '#/components/schemas/PolicyRecommendation'
              examples:
                GetPolicyRecommendation200Example:
                  summary: Default getPolicyRecommendation 200 response
                  x-microcks-default: true
                  value:
                    total: 906
                    recommendations:
                    - id: example-id
                      deviceid: '738250'
                      profile: Network Printer
                      source_zone: dmz
                      destination_zone: dmz
                      applications: &id003
                      - web-browsing
                      services: &id004
                      - example-services_item
                      action: allow
                      confidence: 27.0
                      description: Blocked configured policy endpoint alert endpoint policy incident violation malware suspicious incident.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /device/tag/list:
    get:
      operationId: listDeviceTags
      summary: Palo Alto Networks List Device Tags
      description: >-
        Returns a list of tags defined in the IoT Security tenant.
        Tags are used to label and categorize devices for filtering,
        reporting, and policy assignment purposes.
      tags: []
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '776473'
      - name: offset
        in: query
        description: Pagination offset for results.
        schema:
          type: integer
          default: 0
        example: 0
      - name: pagelength
        in: query
        description: Number of tags to return per page.
        schema:
          type: integer
          default: 100
        example: 100
      responses:
        '200':
          description: Device tags returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of tags.
                  tags:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeviceTag'
              examples:
                ListDeviceTags200Example:
                  summary: Default listDeviceTags 200 response
                  x-microcks-default: true
                  value:
                    total: 832
                    tags:
                    - id: example-id
                      name: Primary Gateway 96
                      description: Suspicious traffic violation on network malware.
                      device_count: 933
                      created_at: '2024-05-09T23:09:39Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /report/asset:
    get:
      operationId: getAssetReport
      summary: Palo Alto Networks Get Asset Report
      description: >-
        Returns an asset inventory report summarizing all discovered
        IoT and OT devices. The report includes breakdowns by device
        category, profile, risk level, and site. Useful for asset
        inventory management and compliance reporting.
      tags:
      - Reports
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '725385'
      - name: offset
        in: query
        description: Pagination offset for results.
        schema:
          type: integer
          default: 0
        example: 0
      - name: pagelength
        in: query
        description: Number of report records to return per page.
        schema:
          type: integer
          default: 100
        example: 100
      responses:
        '200':
          description: Asset report returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of assets in the report.
                  report:
                    $ref: '#/components/schemas/AssetReport'
              examples:
                GetAssetReport200Example:
                  summary: Default getAssetReport 200 response
                  x-microcks-default: true
                  value:
                    total: 9
                    report:
                      total_devices: 646
                      monitored_devices: 724
                      by_category: &id005 {}
                      by_risk_level: &id006
                        critical: 372
                        high: 696
                        medium: 301
                        low: 206
                      by_site: &id007
                      - site: HQ-SanFrancisco
                        device_count: 327
                      top_profiles: &id008
                      - profile: Network Printer
                        device_count: 597
                      report_time: '2025-03-06T06:54:38Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    keyId:
      type: apiKey
      in: header
      name: X-Key-Id
      description: >-
        IoT Security API key identifier. Generated from the IoT Security
        portal under Settings > API Keys.
    accessKey:
      type: apiKey
      in: header
      name: X-Access-Key
      description: >-
        IoT Security API access key. Generated alongside the key
        identifier from the IoT Security portal.
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Invalid or missing API keys.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Device:
      type: object
      properties:
        deviceid:
          type: string
          description: Unique device identifier.
          example: '805631'
        ip:
          type: string
          format: ipv4
          description: IPv4 address of the device.
          example: 10.178.141.130
        mac:
          type: string
          description: MAC address of the device.
          example: 42:f0:fc:53:1d:d1
        hostname:
          type: string
          description: Hostname or NetBIOS name of the device.
          example: host-03a3
        profile:
          type: string
          description: Device profile classification (e.g., IP Camera, Infusion Pump).
          example: Network Printer
        category:
          type: string
          description: Device category (e.g., IoT, OT, IT).
          example: advanced
        risk_score:
          type: integer
          minimum: 0
          maximum: 100
          description: Aggregate risk score from 0 (lowest) to 100 (highest).
          example: 53
        os:
          type: string
          description: Detected operating system.
          example: Ubuntu 22.04
        os_version:
          type: string
          description: Detected operating system version.
          example: 10.5.0
        vendor:
          type: string
          description: Device manufacturer or vendor.
          example: Fortinet
        model:
          type: string
          description: Device model identifier.
          example: VM-300
        site:
          type: string
          description: Network sit

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/palo-alto-networks/refs/heads/main/openapi/palo-alto-iot-security-api-openapi-original.yml