openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Risks 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: Risks
  description: Data security risk identification and management.
paths:
  /dspm/api/v1/risks:
    get:
      operationId: listRisks
      summary: Palo Alto Networks List Data Risks
      description: Returns data security risks identified across all monitored data stores and assets. Risks are generated when sensitive data is found in data stores with insecure configurations such as public access, missing encryption, or excessive permissions.
      tags:
      - Risks
      parameters:
      - name: offset
        in: query
        description: Number of records to skip for pagination.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of records to return.
        schema:
          type: integer
          default: 25
        example: 25
      - name: riskLevel
        in: query
        description: Filter by risk severity level.
        schema:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
        example: medium
      - name: status
        in: query
        description: Filter by risk status.
        schema:
          type: string
          enum:
          - open
          - remediated
          - suppressed
          - acknowledged
        example: acknowledged
      - name: cloudProvider
        in: query
        description: Filter by cloud provider.
        schema:
          type: string
          enum:
          - aws
          - azure
          - gcp
        example: azure
      - name: search
        in: query
        description: Search term to filter by risk title or data store name.
        schema:
          type: string
        example: example-search
      - name: sortBy
        in: query
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - riskLevel
          - detectedAt
        example: detectedAt
      - name: sortOrder
        in: query
        description: Sort order direction.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: desc
      responses:
        '200':
          description: Data risks returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalCount:
                    type: integer
                    description: Total number of data risks matching filters.
                  risks:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataRisk'
              examples:
                ListRisks200Example:
                  summary: Default listRisks 200 response
                  x-microcks-default: true
                  value:
                    totalCount: 464
                    risks:
                    - id: example-id
                      title: Branch Sensor 28
                      description: Endpoint applied threat investigation violation Security traffic detected.
                      riskLevel: medium
                      riskCategory: backupMissing
                      status: open
                      dataStoreId: '132179'
                      dataStoreName: Staging Agent 64
                      cloudProvider: gcp
                      cloudAccountId: '452369'
                      region: us-east-1
                      affectedClassifications:
                      - example-affectedClassifications_item
                      affectedDataAssetCount: 700
                      remediation:
                        description: Firewall rule violation applied endpoint detected endpoint alert rule suspicious.
                        steps:
                        - example-steps_item
                        automatedRemediationAvailable: true
                      detectedAt: '2026-10-09T08:11:21Z'
                      lastEvaluatedAt: '2024-12-04T00:05:27Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /dspm/api/v1/risks/{id}:
    get:
      operationId: getRisk
      summary: Palo Alto Networks Get Risk Details
      description: Returns detailed information for a specific data security risk including full risk description, affected data store details, impacted data assets, and step-by-step remediation guidance.
      tags:
      - Risks
      parameters:
      - name: id
        in: path
        required: true
        description: Unique risk identifier.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Risk details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataRisk'
              examples:
                GetRisk200Example:
                  summary: Default getRisk 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    title: Branch Sensor 28
                    description: Endpoint applied threat investigation violation Security traffic detected.
                    riskLevel: medium
                    riskCategory: backupMissing
                    status: open
                    dataStoreId: '132179'
                    dataStoreName: Staging Agent 64
                    cloudProvider: gcp
                    cloudAccountId: '452369'
                    region: us-east-1
                    affectedClassifications:
                    - example-affectedClassifications_item
                    affectedDataAssetCount: 700
                    remediation:
                      description: Firewall rule violation applied endpoint detected endpoint alert rule suspicious.
                      steps:
                      - example-steps_item
                      automatedRemediationAvailable: true
                    detectedAt: '2026-10-09T08:11:21Z'
                    lastEvaluatedAt: '2024-12-04T00:05:27Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /dspm/api/v1/risks/{id}/status:
    put:
      operationId: updateRiskStatus
      summary: Palo Alto Networks Update Risk Status
      description: Updates the status of a specific data security risk. Use this endpoint to acknowledge, suppress, or mark a risk as remediated after applying corrective actions to the affected data store.
      tags:
      - Risks
      parameters:
      - name: id
        in: path
        required: true
        description: Unique risk identifier.
        schema:
          type: string
        example: example-id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - status
              properties:
                status:
                  type: string
                  enum:
                  - open
                  - remediated
                  - suppressed
                  - acknowledged
                  description: New status for the risk.
                comment:
                  type: string
                  description: Comment explaining the status change.
            examples:
              UpdateRiskStatusRequestExample:
                summary: Default updateRiskStatus request
                x-microcks-default: true
                value:
                  status: open
                  comment: Detected detected policy investigation threat incident policy Security violation firewall network.
      responses:
        '200':
          description: Risk status updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataRisk'
              examples:
                UpdateRiskStatus200Example:
                  summary: Default updateRiskStatus 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    title: Branch Sensor 28
                    description: Endpoint applied threat investigation violation Security traffic detected.
                    riskLevel: medium
                    riskCategory: backupMissing
                    status: open
                    dataStoreId: '132179'
                    dataStoreName: Staging Agent 64
                    cloudProvider: gcp
                    cloudAccountId: '452369'
                    region: us-east-1
                    affectedClassifications:
                    - example-affectedClassifications_item
                    affectedDataAssetCount: 700
                    remediation:
                      description: Firewall rule violation applied endpoint detected endpoint alert rule suspicious.
                      steps:
                      - example-steps_item
                      automatedRemediationAvailable: true
                    detectedAt: '2026-10-09T08:11:21Z'
                    lastEvaluatedAt: '2024-12-04T00:05:27Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    Forbidden:
      description: Insufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Invalid or expired JWT token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code.
          example: 177
        message:
          type: string
          description: Human-readable error message.
          example: Suspicious traffic configured monitoring malware endpoint applied.
        error:
          type: string
          description: Error code.
          example: example-error
    DataRisk:
      type: object
      properties:
        id:
          type: string
          description: Unique risk identifier.
          example: example-id
        title:
          type: string
          description: Short description of the risk.
          example: Branch Sensor 28
        description:
          type: string
          description: Detailed explanation of the risk and its potential impact.
          example: Endpoint applied threat investigation violation Security traffic detected.
        riskLevel:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          description: Severity of the risk.
          example: medium
        riskCategory:
          type: string
          enum:
          - publicExposure
          - encryptionMissing
          - excessivePermissions
          - dataResidency
          - auditLogging
          - backupMissing
          - crossAccountAccess
          - sensitiveDataExposure
          description: Category of the data security risk.
          example: backupMissing
        status:
          type: string
          enum:
          - open
          - remediated
          - suppressed
          - acknowledged
          description: Current status of the risk.
          example: open
        dataStoreId:
          type: string
          description: Data store where the risk was identified.
          example: '132179'
        dataStoreName:
          type: string
          description: Name of the affected data store.
          example: Staging Agent 64
        cloudProvider:
          type: string
          enum:
          - aws
          - azure
          - gcp
          description: Cloud provider of the affected data store.
          example: gcp
        cloudAccountId:
          type: string
          description: Cloud account ID of the affected data store.
          example: '452369'
        region:
          type: string
          description: Cloud region of the affected data store.
          example: us-east-1
        affectedClassifications:
          type: array
          items:
            type: string
          description: Classification labels of sensitive data at risk.
          example:
          - example-affectedClassifications_item
        affectedDataAssetCount:
          type: integer
          description: Number of data assets affected by this risk.
          example: 700
        remediation:
          type: object
          properties:
            description:
              type: string
              description: Human-readable description of the recommended remediation.
              example: Malware traffic detected threat blocked policy suspicious firewall rule alert blocked malware.
            steps:
              type: array
              items:
                type: string
              description: Step-by-step remediation instructions.
              example:
              - example-steps_item
              - example-steps_item
            automatedRemediationAvailable:
              type: boolean
              description: Whether automated remediation is available.
              example: false
          description: Recommended remediation steps.
          example:
            description: Firewall rule violation applied endpoint detected endpoint alert rule suspicious.
            steps:
            - example-steps_item
            automatedRemediationAvailable: true
        detectedAt:
          type: string
          format: date-time
          description: Timestamp when the risk was first detected.
          example: '2026-10-09T08:11:21Z'
        lastEvaluatedAt:
          type: string
          format: date-time
          description: Timestamp of the most recent risk evaluation.
          example: '2024-12-04T00:05:27Z'
  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.