openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend ATP 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: ATP
  description: Advanced Threat Prevention detailed analysis reports and PCAP files.
paths:
  /atp/reports:
    get:
      operationId: getAtpReports
      summary: Palo Alto Networks Get ATP Detailed Reports
      description: Retrieves Advanced Threat Prevention (ATP) detailed analysis reports for threats detected by inline cloud analysis. Reports include behavioral analysis data, indicators of compromise, and threat context.
      tags:
      - ATP
      parameters:
      - name: sha256
        in: query
        description: SHA-256 hash to retrieve the ATP report for.
        schema:
          type: string
        example: 27b1ace2ba8ec988728e1f6429d2bb4c3316c556210d409aedd8f059615c6121
      - name: id
        in: query
        description: ATP report ID.
        schema:
          type: string
        example: example-id
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
          maximum: 100
        example: 10
      responses:
        '200':
          description: ATP reports returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtpReportList'
              examples:
                GetAtpReports200Example:
                  summary: Default getAtpReports 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    data:
                    - id: example-id
                      sha256: 1a0cc0aab37304dfb1801ee9999fdc70e10dcffd0bff8e3cc12d14e696abe57a
                      status: pending
                      verdict: grayware
                      create_time: '2024-11-24T09:15:12Z'
                      report:
                        file_type: advanced
                        size: 452
                        behaviors:
                        - name: Staging Sensor 59
                          description: Rule rule policy rule policy endpoint endpoint on.
                          severity: low
                        - name: Production Sensor 84
                          description: Policy suspicious configured network firewall violation endpoint threat traffic blocked.
                          severity: low
                        network:
                          dns_queries:
                          - example-dns_queries_item
                          http_requests:
                          - example-http_requests_item
                          connections:
                          - dst_ip: 51.157.178.113
                            dst_port: 664
                            protocol: HTTPS
                          - dst_ip: 122.11.127.230
                            dst_port: 171
                            protocol: HTTPS
                    total: 264
                    offset: 161
                    limit: 795
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /atp/reports/pcaps:
    get:
      operationId: getAtpReportPcaps
      summary: Palo Alto Networks Get ATP PCAP Files
      description: Downloads network packet capture (PCAP) files associated with Advanced Threat Prevention reports. PCAPs contain the network traffic recorded during threat analysis and are useful for incident investigation.
      tags:
      - ATP
      parameters:
      - name: sha256
        in: query
        required: true
        description: SHA-256 hash of the threat sample.
        schema:
          type: string
        example: 79965ebec5847a5aca98f3bbe037fb10e0e808b83dd8637c5bda3f2514623f33
      - name: id
        in: query
        description: ATP report ID.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: PCAP file returned successfully.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AtpReport:
      type: object
      description: Advanced Threat Prevention inline analysis report.
      properties:
        id:
          type: string
          description: Unique report identifier.
          example: example-id
        sha256:
          type: string
          description: SHA-256 hash of the analyzed sample.
          example: 1a0cc0aab37304dfb1801ee9999fdc70e10dcffd0bff8e3cc12d14e696abe57a
        status:
          type: string
          enum:
          - pending
          - complete
          - error
          example: pending
        verdict:
          type: string
          enum:
          - benign
          - malware
          - grayware
          - phishing
          - unknown
          example: grayware
        create_time:
          type: string
          format: date-time
          example: '2024-11-24T09:15:12Z'
        report:
          type: object
          description: Detailed behavioral analysis data.
          properties:
            file_type:
              type: string
              example: custom
            size:
              type: integer
              example: 219
            behaviors:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: Production Sensor 79
                  description:
                    type: string
                    example: Network threat traffic configured policy policy on activity.
                  severity:
                    type: string
                    example: high
              example:
              - name: Staging Sensor 16
                description: Rule firewall network alert rule suspicious network investigation detected network violation.
                severity: low
              - name: Production Agent 81
                description: Applied violation violation traffic detected detected on threat.
                severity: critical
            network:
              type: object
              properties:
                dns_queries:
                  type: array
                  items:
                    type: string
                  example:
                  - example-dns_queries_item
                  - example-dns_queries_item
                http_requests:
                  type: array
                  items:
                    type: string
                  example:
                  - example-http_requests_item
                  - example-http_requests_item
                connections:
                  type: array
                  items:
                    type: object
                    properties:
                      dst_ip:
                        type: string
                        example: 122.232.51.18
                      dst_port:
                        type: integer
                        example: 580
                      protocol:
                        type: string
                        example: TCP
                  example:
                  - dst_ip: 71.44.154.98
                    dst_port: 777
                    protocol: UDP
                  - dst_ip: 207.65.92.163
                    dst_port: 708
                    protocol: HTTPS
              example:
                dns_queries:
                - example-dns_queries_item
                - example-dns_queries_item
                http_requests:
                - example-http_requests_item
                - example-http_requests_item
                connections:
                - dst_ip: 172.115.44.22
                  dst_port: 78
                  protocol: UDP
          example:
            file_type: advanced
            size: 452
            behaviors:
            - name: Staging Sensor 59
              description: Rule rule policy rule policy endpoint endpoint on.
              severity: low
            - name: Production Sensor 84
              description: Policy suspicious configured network firewall violation endpoint threat traffic blocked.
              severity: low
            network:
              dns_queries:
              - example-dns_queries_item
              http_requests:
              - example-http_requests_item
              connections:
              - dst_ip: 51.157.178.113
                dst_port: 664
                protocol: HTTPS
              - dst_ip: 122.11.127.230
                dst_port: 171
                protocol: HTTPS
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          description: Human-readable error message.
          example: Threat applied violation endpoint activity violation activity incident applied.
        error_code:
          type: string
          description: Machine-readable error code.
          example: example-error_code
    AtpReportList:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/AtpReport'
          example:
          - id: example-id
            sha256: 1a0cc0aab37304dfb1801ee9999fdc70e10dcffd0bff8e3cc12d14e696abe57a
            status: pending
            verdict: grayware
            create_time: '2024-11-24T09:15:12Z'
            report:
              file_type: advanced
              size: 452
              behaviors:
              - name: Staging Sensor 59
                description: Rule rule policy rule policy endpoint endpoint on.
                severity: low
              - name: Production Sensor 84
                description: Policy suspicious configured network firewall violation endpoint threat traffic blocked.
                severity: low
              network:
                dns_queries:
                - example-dns_queries_item
                http_requests:
                - example-http_requests_item
                connections:
                - dst_ip: 51.157.178.113
                  dst_port: 664
                  protocol: HTTPS
                - dst_ip: 122.11.127.230
                  dst_port: 171
                  protocol: HTTPS
        total:
          type: integer
          example: 264
        offset:
          type: integer
          example: 161
        limit:
          type: integer
          example: 795
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Malformed request or invalid query 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.