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 site where the device was discovered.
          example: Branch-London
        subnet:
          type: string
          description: Subnet the device belongs to.
          example: 10.32.40.0/24
        first_seen:
          type: string
          format: date-time
          description: Timestamp when the device was first discovered.
          example: '2024-12-19T02:52:11Z'
        last_seen:
          type: string
          format: date-time
          description: Timestamp when the device was last active.
          example: '2025-01-24T06:19:11Z'
        monitored:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Whether the device is currently monitored.
          example: 'no'
        confidence_score:
          type: integer
          description: Confidence level of the device profile classification.
          example: 533
        tags:
          type: array
          items:
            type: string
          description: User-defined or system-assigned tags.
          example: *id001
    Alert:
      type: object
      properties:
        id:
          type: string
          description: Unique alert identifier.
          example: example-id
        type:
          type: string
          description: Alert type classification.
          example: advanced
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - info
          description: Alert severity level.
          example: info
        description:
          type: string
          description: Human-readable alert description.
          example: Firewall incident network violation detected incident alert monitoring traffic monitoring rule.
        deviceid:
          type: string
          description: Identifier of the affected device.
          example: '257277'
        device_ip:
          type: string
          format: ipv4
          description: IP address of the affected device.
          example: 10.156.198.91
        device_profile:
          type: string
          description: Profile of the affected device.
          example: Network Printer
        resolved:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Whether the alert has been resolved.
          example: 'no'
        resolved_reason:
          type: string
          description: Resolution reason if resolved.
          example: example-resolved_reason
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the alert was generated.
          example: '2024-05-28T18:45:09Z'
        details:
          type: object
          description: Additional alert-specific details.
          example: *id002
    Vulnerability:
      type: object
      properties:
        id:
          type: string
          description: Unique vulnerability record identifier.
          example: example-id
        cve:
          type: string
          description: CVE identifier (e.g., CVE-2023-12345).
          example: example-cve
        vulnerability_name:
          type: string
          description: Vulnerability name.
          example: Production Gateway 97
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - info
          description: Vulnerability severity rating.
          example: critical
        cvss_score:
          type: number
          format: float
          description: CVSS v3 base score.
          example: 41.94
        deviceid:
          type: string
          description: Device identifier affected by the vulnerability.
          example: '527185'
        affected_device_count:
          type: integer
          description: Number of devices affected by this vulnerability.
          example: 436
        description:
          type: string
          description: Vulnerability description.
          example: Security rule blocked Security monitoring rule applied.
        remediation:
          type: string
          description: Recommended remediation steps.
          example: example-remediation
        first_detected:
          type: string
          format: date-time
          description: Timestamp when the vulnerability was first detected.
          example: '2026-01-17T19:27:21Z'
    PolicyRecommendation:
      type: object
      properties:
        id:
          type: string
          description: Unique recommendation identifier.
          example: example-id
        deviceid:
          type: string
          description: Device identifier the recommendation applies to.
          example: '738250'
        profile:
          type: string
          description: Device profile the recommendation applies to.
          example: Network Printer
        source_zone:
          type: string
          description: Recommended source security zone.
          example: dmz
        destination_zone:
          type: string
          description: Recommended destination security zone.
          example: dmz
        applications:
          type: array
          items:
            type: string
          description: Recommended allowed applications.
          example: *id003
        services:
          type: array
          items:
            type: string
          description: Recommended allowed services and ports.
          example: *id004
        action:
          type: string
          enum:
          - allow
          - deny
          - alert
          description: Recommended policy action.
          example: allow
        confidence:
          type: number
          format: float
          description: Confidence score for the recommendation.
          example: 27.0
        description:
          type: string
          description: Human-readable recommendation description.
          example: Blocked configured policy endpoint alert endpoint policy incident violation malware suspicious incident.
    DeviceTag:
      type: object
      properties:
        id:
          type: string
          description: Unique tag identifier.
          example: example-id
        name:
          type: string
          description: Tag name.
          example: Primary Gateway 96
        description:
          type: string
          description: Tag description.
          example: Suspicious traffic violation on network malware.
        device_count:
          type: integer
          description: Number of devices assigned this tag.
          example: 933
        created_at:
          type: string
          format: date-time
          description: Timestamp when the tag was created.
          example: '2024-05-09T23:09:39Z'
    AssetReport:
      type: object
      properties:
        total_devices:
          type: integer
          description: Total number of discovered devices.
          example: 646
        monitored_devices:
          type: integer
          description: Number of actively monitored devices.
          example: 724
        by_category:
          type: object
          description: Device count breakdown by category.
          additionalProperties:
            type: integer
          example: *id005
        by_risk_level:
          type: object
          description: Device count breakdown by risk level.
          properties:
            critical:
              type: integer
              example: 399
            high:
              type: integer
              example: 441
            medium:
              type: integer
              example: 911
            low:
              type: integer
              example: 769
          example: *id006
        by_site:
          type: array
          items:
            type: object
            properties:
              site:
                type: string
                example: HQ-SanFrancisco
              device_count:
                type: integer
                example: 930
          description: Device count breakdown by network site.
          example: *id007
        top_profiles:
          type: array
          items:
            type: object
            properties:
              profile:
                type: string
                example: Network Printer
              device_count:
                type: integer
                example: 267
          description: Most common device profiles.
          example: *id008
        report_time:
          type: string
          format: date-time
          description: Timestamp when the report was generated.
          example: '2025-03-06T06:54:38Z'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code or type.
          example: example-error
        message:
          type: string
          description: Human-readable error message.
          example: Monitoring traffic activity network investigation investigation network policy traffic violation rule rule.