Palo Alto Networks Posture Checks API

openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Posture Checks 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: Posture Checks
  description: Security posture check results and remediation status.
paths:
  /v1/posture-checks:
    get:
      operationId: listPostureChecks
      summary: Palo Alto Networks List Posture Check Results
      description: Returns posture check results across all onboarded SaaS applications. Supports filtering by application, check type, severity, and remediation status. Each check result indicates whether a specific security best practice is implemented in the connected application.
      tags:
      - Posture Checks
      parameters:
      - name: app_id
        in: query
        description: Filter checks by onboarded application ID.
        schema:
          type: string
        example: '131412'
      - name: check_type
        in: query
        description: Filter by check category type.
        schema:
          type: string
          enum:
          - access_control
          - authentication
          - data_protection
          - logging
          - network_security
          - configuration
        example: logging
      - name: severity
        in: query
        description: Filter by check severity level.
        schema:
          type: string
          enum:
          - informational
          - low
          - medium
          - high
          - critical
        example: critical
      - name: status
        in: query
        description: Filter by remediation status.
        schema:
          type: string
          enum:
          - pass
          - fail
          - error
          - suppressed
        example: fail
      - name: offset
        in: query
        description: Number of results to skip for pagination.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of check results to return.
        schema:
          type: integer
          default: 50
          maximum: 200
        example: 50
      responses:
        '200':
          description: Posture check results returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PostureCheck'
              examples:
                ListPostureChecks200Example:
                  summary: Default listPostureChecks 200 response
                  x-microcks-default: true
                  value:
                    total: 887
                    offset: 835
                    limit: 673
                    items:
                    - check_id: '841281'
                      app_id: '849318'
                      check_name: Primary Policy 44
                      check_type: authentication
                      severity: low
                      status: suppressed
                      description: Configured network on activity configured incident alert monitoring.
                      remediation: example-remediation
                      compliance_frameworks: &id001
                      - example-compliance_frameworks_item
                      last_evaluated_at: '2026-09-01T23:02:10Z'
                      suppression_justification: example-suppression_justification
                    - check_id: '841281'
                      app_id: '849318'
                      check_name: Primary Policy 44
                      check_type: authentication
                      severity: low
                      status: suppressed
                      description: Configured network on activity configured incident alert monitoring.
                      remediation: example-remediation
                      compliance_frameworks: *id001
                      last_evaluated_at: '2026-09-01T23:02:10Z'
                      suppression_justification: example-suppression_justification
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListPostureChecks400Example:
                  summary: Default listPostureChecks 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListPostureChecks401Example:
                  summary: Default listPostureChecks 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListPostureChecks403Example:
                  summary: Default listPostureChecks 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListPostureChecks500Example:
                  summary: Default listPostureChecks 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/posture-checks/{check_id}:
    get:
      operationId: getPostureCheck
      summary: Palo Alto Networks Get Posture Check Details
      description: Returns full details for a specific posture check result including the check description, affected configuration, remediation guidance, and compliance framework mappings.
      tags:
      - Posture Checks
      parameters:
      - name: check_id
        in: path
        required: true
        description: Unique identifier of the posture check result.
        schema:
          type: string
        example: '461435'
      responses:
        '200':
          description: Posture check details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
              examples:
                GetPostureCheck200Example:
                  summary: Default getPostureCheck 200 response
                  x-microcks-default: true
                  value:
                    check_id: '841281'
                    app_id: '849318'
                    check_name: Primary Policy 44
                    check_type: authentication
                    severity: low
                    status: suppressed
                    description: Configured network on activity configured incident alert monitoring.
                    remediation: example-remediation
                    compliance_frameworks:
                    - example-compliance_frameworks_item
                    last_evaluated_at: '2026-09-01T23:02:10Z'
                    suppression_justification: example-suppression_justification
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetPostureCheck401Example:
                  summary: Default getPostureCheck 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetPostureCheck403Example:
                  summary: Default getPostureCheck 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '404':
          description: Posture check not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetPostureCheck404Example:
                  summary: Default getPostureCheck 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetPostureCheck500Example:
                  summary: Default getPostureCheck 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/posture-checks/{check_id}/status:
    put:
      operationId: updatePostureCheckStatus
      summary: Palo Alto Networks Update Posture Check Status
      description: Updates the remediation status of a posture check result. Use this endpoint to mark checks as suppressed with a justification, or to mark remediated checks for re-evaluation.
      tags:
      - Posture Checks
      parameters:
      - name: check_id
        in: path
        required: true
        description: Unique identifier of the posture check result.
        schema:
          type: string
        example: '258568'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - status
              properties:
                status:
                  type: string
                  enum:
                  - suppressed
                  - pending_remediation
                  description: New status to set for the check.
                justification:
                  type: string
                  description: Reason for suppressing the check. Required when setting status to suppressed.
                  maxLength: 1024
            examples:
              UpdatePostureCheckStatusRequestExample:
                summary: Default updatePostureCheckStatus request
                x-microcks-default: true
                value:
                  status: pending_remediation
                  justification: example-justification
      responses:
        '200':
          description: Check status updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
              examples:
                UpdatePostureCheckStatus200Example:
                  summary: Default updatePostureCheckStatus 200 response
                  x-microcks-default: true
                  value:
                    check_id: '841281'
                    app_id: '849318'
                    check_name: Primary Policy 44
                    check_type: authentication
                    severity: low
                    status: suppressed
                    description: Configured network on activity configured incident alert monitoring.
                    remediation: example-remediation
                    compliance_frameworks:
                    - example-compliance_frameworks_item
                    last_evaluated_at: '2026-09-01T23:02:10Z'
                    suppression_justification: example-suppression_justification
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdatePostureCheckStatus400Example:
                  summary: Default updatePostureCheckStatus 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdatePostureCheckStatus401Example:
                  summary: Default updatePostureCheckStatus 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdatePostureCheckStatus403Example:
                  summary: Default updatePostureCheckStatus 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '404':
          description: Posture check not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdatePostureCheckStatus404Example:
                  summary: Default updatePostureCheckStatus 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdatePostureCheckStatus500Example:
                  summary: Default updatePostureCheckStatus 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Malware violation rule blocked detected endpoint policy detected.
                    request_id: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    PostureCheck:
      type: object
      properties:
        check_id:
          type: string
          description: Unique identifier of the posture check result.
          example: '841281'
        app_id:
          type: string
          description: ID of the onboarded application this check applies to.
          example: '849318'
        check_name:
          type: string
          description: Name of the security posture check.
          example: Primary Policy 44
        check_type:
          type: string
          enum:
          - access_control
          - authentication
          - data_protection
          - logging
          - network_security
          - configuration
          description: Category of the posture check.
          example: authentication
        severity:
          type: string
          enum:
          - informational
          - low
          - medium
          - high
          - critical
          description: Severity level if the check fails.
          example: low
        status:
          type: string
          enum:
          - pass
          - fail
          - error
          - suppressed
          description: Current result status of the check.
          example: suppressed
        description:
          type: string
          description: Description of what the check evaluates.
          example: Configured network on activity configured incident alert monitoring.
        remediation:
          type: string
          description: Step-by-step remediation guidance for failed checks.
          example: example-remediation
        compliance_frameworks:
          type: array
          items:
            type: string
          description: Compliance frameworks this check maps to (e.g., CIS, SOC2, ISO27001).
          example:
          - example-compliance_frameworks_item
        last_evaluated_at:
          type: string
          format: date-time
          description: Timestamp when the check was last evaluated.
          example: '2026-09-01T23:02:10Z'
        suppression_justification:
          type: string
          description: Justification text if the check is suppressed.
          example: example-suppression_justification
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code identifying the error type.
          example: example-error
        message:
          type: string
          description: Human-readable description of the error.
          example: Malware violation rule blocked detected endpoint policy detected.
        request_id:
          type: string
          description: Request identifier for support correlation.
          example: f7942ddd-4571-4f6e-a8a1-00c0f9d7dfb4
  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.