openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Device API
  description: AIOps for NGFW Best Practice Assessment (BPA) API. Provides programmatic access to submit BPA requests for Palo Alto Networks next-generation firewalls, check request processing status, and retrieve completed assessment reports. BPA reports analyze firewall configurations against Palo Alto Networks best practices and security benchmarks, identifying gaps and providing remediation guidance to improve security posture. Part of the Strata Cloud Manager platform.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
  description: AIOps for NGFW BPA API production server.
security:
- oauth2Bearer: []
tags:
- name: Device
paths:
  /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:
      - Device
      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
  /Device/VirtualSystems:
    get:
      operationId: listVirtualSystems
      summary: Palo Alto Networks List Virtual Systems
      description: Returns all virtual systems (vsys) configured on the firewall. Virtual systems provide multi-tenancy on a single physical or virtual firewall appliance, each with its own security policy, interfaces, and zones.
      tags:
      - Device
      responses:
        '200':
          description: Virtual systems returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@status':
                    type: string
                  '@code':
                    type: string
                  result:
                    type: object
                    properties:
                      '@total-count':
                        type: string
                      '@count':
                        type: string
                      entry:
                        type: array
                        items:
                          $ref: '#/components/schemas/VirtualSystem'
              examples:
                ListVirtualSystems200Example:
                  summary: Default listVirtualSystems 200 response
                  x-microcks-default: true
                  value:
                    '@status': running
                    '@code': example-@code
                    result:
                      '@total-count': example-@total-count
                      '@count': example-@count
                      entry:
                      - '@name': Corporate Firewall 67
                        display-name: Corporate Policy 13
                        import:
                          network:
                            interface:
                              member:
                              - example-member_item
                              - example-member_item
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    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'
    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.
    VirtualSystem:
      type: object
      description: A virtual system (vsys) on the PAN-OS firewall.
      properties:
        '@name':
          type: string
          description: Virtual system name (e.g., vsys1, vsys2).
          example: Corporate Firewall 67
        display-name:
          type: string
          description: Human-readable display name for the vsys.
          example: Corporate Policy 13
        import:
          type: object
          description: Imported network resources for this vsys.
          properties:
            network:
              type: object
              properties:
                interface:
                  type: object
                  properties:
                    member:
                      type: array
                      items:
                        type: string
                      description: Network interfaces assigned to this vsys.
                      example:
                      - example-member_item
                      - example-member_item
                  example:
                    member:
                    - example-member_item
              example:
                interface:
                  member:
                  - example-member_item
          example:
            network:
              interface:
                member:
                - example-member_item
                - example-member_item
    ErrorResponse_2:
      type: object
      properties:
        '@status':
          type: string
          example: running
        '@code':
          type: string
          example: example-@code
        msg:
          type: object
          properties:
            line:
              type: string
              description: Error message detail.
              example: example-line
          example:
            line: example-line
  responses:
    BadRequest_2:
      description: Malformed request or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
    Unauthorized_2:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
    Unauthorized:
      description: Invalid or missing API keys.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth2Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for SASE platform authentication. Obtain using the client_credentials grant with your SASE service account client ID and client secret.