Palo Alto Networks Scans API

openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Scans 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: Scans
  description: Vulnerability scan lifecycle management.
paths:
  /v1/scans:
    post:
      operationId: startVulnerabilityScan
      summary: Palo Alto Networks Start Vulnerability Scan
      description: Starts a new AI vulnerability scan against a registered target. Specify the attack categories to test and optionally provide custom prompts to supplement the built-in attack library. The scan runs asynchronously; use GET /v1/scans/{scan_id} to monitor progress and GET /v1/scans/{scan_id}/results to retrieve the completed report.
      tags:
      - Scans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
            examples:
              StartVulnerabilityScanRequestExample:
                summary: Default startVulnerabilityScan request
                x-microcks-default: true
                value:
                  target_id: '645262'
                  attack_categories:
                  - example-attack_categories_item
                  - example-attack_categories_item
                  custom_prompts:
                  - example-custom_prompts_item
                  - example-custom_prompts_item
                  max_attacks_per_category: 740
      responses:
        '201':
          description: Vulnerability scan started successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan'
              examples:
                StartVulnerabilityScan201Example:
                  summary: Default startVulnerabilityScan 201 response
                  x-microcks-default: true
                  value:
                    scan_id: '588456'
                    target_id: '410241'
                    target_name: Production Agent 95
                    status: running
                    attack_categories:
                    - example-attack_categories_item
                    progress: 0.36
                    total_attacks: 275
                    completed_attacks: 880
                    vulnerabilities_found: 746
                    error_message: example-error_message
                    started_at: '2025-08-08T22:13:06Z'
                    completed_at: '2024-11-03T18:50:01Z'
        '400':
          description: Invalid request body or target not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                StartVulnerabilityScan400Example:
                  summary: Default startVulnerabilityScan 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                StartVulnerabilityScan401Example:
                  summary: Default startVulnerabilityScan 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                StartVulnerabilityScan403Example:
                  summary: Default startVulnerabilityScan 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '409':
          description: A scan is already in progress for this target.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                StartVulnerabilityScan409Example:
                  summary: Default startVulnerabilityScan 409 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                StartVulnerabilityScan500Example:
                  summary: Default startVulnerabilityScan 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/scans/{scan_id}:
    get:
      operationId: getScanStatus
      summary: Palo Alto Networks Get Scan Status
      description: Returns the current status and progress of a vulnerability scan. When status is completed, use GET /v1/scans/{scan_id}/results to retrieve the full vulnerability report.
      tags:
      - Scans
      parameters:
      - name: scan_id
        in: path
        required: true
        description: Unique identifier of the vulnerability scan.
        schema:
          type: string
        example: '734547'
      responses:
        '200':
          description: Scan status returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan'
              examples:
                GetScanStatus200Example:
                  summary: Default getScanStatus 200 response
                  x-microcks-default: true
                  value:
                    scan_id: '588456'
                    target_id: '410241'
                    target_name: Production Agent 95
                    status: running
                    attack_categories:
                    - example-attack_categories_item
                    progress: 0.36
                    total_attacks: 275
                    completed_attacks: 880
                    vulnerabilities_found: 746
                    error_message: example-error_message
                    started_at: '2025-08-08T22:13:06Z'
                    completed_at: '2024-11-03T18:50:01Z'
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanStatus401Example:
                  summary: Default getScanStatus 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanStatus403Example:
                  summary: Default getScanStatus 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '404':
          description: Scan not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanStatus404Example:
                  summary: Default getScanStatus 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanStatus500Example:
                  summary: Default getScanStatus 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/scans/{scan_id}/results:
    get:
      operationId: getScanResults
      summary: Palo Alto Networks Get Scan Results and Report
      description: Returns the detailed vulnerability report for a completed scan. The report includes an overall risk score, vulnerability findings organized by attack category, specific attack prompts that succeeded, and remediation recommendations. Only available when the scan status is completed.
      tags:
      - Scans
      parameters:
      - name: scan_id
        in: path
        required: true
        description: Unique identifier of the completed scan.
        schema:
          type: string
        example: '783198'
      - name: category
        in: query
        description: Filter results by attack category.
        schema:
          type: string
        example: standard
      - name: severity
        in: query
        description: Filter findings by severity level.
        schema:
          type: string
          enum:
          - informational
          - low
          - medium
          - high
          - critical
        example: high
      responses:
        '200':
          description: Scan results and report returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanReport'
              examples:
                GetScanResults200Example:
                  summary: Default getScanResults 200 response
                  x-microcks-default: true
                  value:
                    scan_id: '428692'
                    target_id: '819001'
                    target_name: Branch Agent 03
                    overall_risk_score: 2.13
                    total_attacks_executed: 817
                    vulnerabilities_found: 907
                    category_summaries:
                    - category_id: '482152'
                      category_name: Staging Firewall 89
                      attacks_executed: 371
                      vulnerabilities_found: 428
                      risk_score: 33.91
                    - category_id: '228990'
                      category_name: Staging Sensor 95
                      attacks_executed: 409
                      vulnerabilities_found: 670
                      risk_score: 53.57
                    findings:
                    - finding_id: '841657'
                      category_id: '121939'
                      category_name: Branch Gateway 62
                      severity: low
                      title: Primary Sensor 11
                      description: Applied Security on activity traffic investigation configured investigation activity on configured.
                      attack_prompt: example-attack_prompt
                      model_response: VM-300
                      remediation: example-remediation
                    generated_at: '2026-12-07T01:42:19Z'
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanResults400Example:
                  summary: Default getScanResults 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanResults401Example:
                  summary: Default getScanResults 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanResults403Example:
                  summary: Default getScanResults 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '404':
          description: Scan not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanResults404Example:
                  summary: Default getScanResults 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '409':
          description: Scan is not yet completed. Results are not available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanResults409Example:
                  summary: Default getScanResults 409 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetScanResults500Example:
                  summary: Default getScanResults 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Policy investigation blocked activity on activity suspicious configured configured suspicious.
                    request_id: f62400eb-5426-47bb-acc1-166eb163d06c
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /scans/integrations:
    get:
      operationId: listScanIntegrations
      summary: Palo Alto Networks List CI/CD Scan Integrations
      description: Returns a list of configured CI/CD pipeline integrations for automated scanning. Integrations include Jenkins, GitHub Actions, CircleCI, GitLab CI, Azure Pipelines, and other supported CI platforms.
      tags:
      - Scans
      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
      responses:
        '200':
          description: CI/CD integrations returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalCount:
                    type: integer
                  integrations:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScanIntegration'
              examples:
                ListScanIntegrations200Example:
                  summary: Default listScanIntegrations 200 response
                  x-microcks-default: true
                  value:
                    totalCount: 800
                    integrations:
                    - id: example-id
                      name: Corporate Agent 16
                      type: circleci
                      repositoryId: '140485'
                      enabled: true
                      createdAt: '2024-02-04T09:08:54Z'
                    - id: example-id
                      name: Corporate Agent 16
                      type: circleci
                      repositoryId: '140485'
                      enabled: true
                      createdAt: '2024-02-04T09:08:54Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /scans:
    post:
      operationId: triggerScan
      summary: Palo Alto Networks Trigger a Scan
      description: Triggers an IaC and SCA scan for a specific repository branch. The scan analyzes all supported file types in the repository. Returns a scan identifier for polling status.
      tags:
      - Scans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - repositoryId
              properties:
                repositoryId:
                  type: string
                  description: Unique identifier of the repository to scan.
                branch:
                  type: string
                  description: Branch to scan. Defaults to the repository default branch.
                scanTypes:
                  type: array
                  description: Types of scans to run. Defaults to all scan types.
                  items:
                    type: string
                    enum:
                    - iac
                    - sca
                    - secrets
                    - cicd
            examples:
              TriggerScanRequestExample:
                summary: Default triggerScan request
                x-microcks-default: true
                value:
                  repositoryId: '181356'
                  branch: example-branch
                  scanTypes:
                  - iac
                  - sca
      responses:
        '200':
          description: Scan triggered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanStatus'
              examples:
                TriggerScan200Example:
                  summary: Default triggerScan 200 response
                  x-microcks-default: true
                  value:
                    scan_id: '905307'
                    repositoryId: '225862'
                    branch: example-branch
                    status: failed
                    startTime: '2025-06-09T14:49:57Z'
                    endTime: '2026-10-02T12:40:08Z'
                    scanTypes:
                    - sca
                    - iac
                    summary:
                      filesScanned: 87
                      resourcesScanned: 381
                      errorsBySeverity:
                        critical: 274
                        high: 812
                        medium: 73
                        low: 85
                        info: 478
        '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
    get:
      operationId: getCIScans
      summary: Palo Alto Networks Get CI Scan Results
      description: Returns vulnerability and compliance scan results from CI/CD pipeline scans run using the twistcli tool or CI/CD integrations. Results include the scan target, policy outcome, and detailed findings for each scan run.
      tags:
      - Scans
      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: 50
        example: 50
      - name: search
        in: query
        description: Search term to filter scan results by image name.
        schema:
          type: string
        example: example-search
      - name: type
        in: query
        description: Filter by scan target type.
        schema:
          type: string
          enum:
          - ciImage
          - ciServerless
          - ciIaC
        example: ciServerless
      responses:
        '200':
          description: CI scan results returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CIScan'
              examples:
                GetCiscans200Example:
                  summary: Default getCIScans 200 response
                  x-microcks-default: true
                  value:
                  - entityInfo:
                      _id: '302929'
                      type: ciIaC
                      hostname: host-6942
                      scanTime: '2026-01-25T05:11:50Z'
                    pass: true
                    vulnerabilitiesCount: 27
                    complianceIssuesCount: 398
                    vulnerabilityDistribution:
                      critical: 112
                      high: 224
                      medium: 858
                      low: 591
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '403':
          $ref: '#/components/responses/Forbidden_2'
        '500':
          $ref: '#/components/responses/InternalServerError_2'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /scans/{scan_id}:
    get:
      operationId: getScanStatus
      summary: Palo Alto Networks Get Scan Status
      description: Returns the current status and summary results of a specific scan. Poll this endpoint to determine when a triggered scan has completed.
      tags:
      - Scans
      parameters:
      - name: scan_id
        in: path
        required: true
        description: Unique scan identifier.
        schema:
          type: string
        example: '170028'
      responses:
        '200':
          description: Scan status returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanStatus'
              examples:
                GetScanStatus200Example:
                  summary: Default getScanStatus 200 response
                  x-microcks-default: true
                  value:
                    scan_id: '905307'
                    repositoryId: '225862'
                    branch: example-branch
                    status: failed
                    startTime: '2025-06-09T14:49:57Z'
                    endTime: '2026-10-02T12:40:08Z'
                    scanTypes:
                    - sca
                    - iac
                    summary:
                      filesScanned: 87
                      resourcesScanned: 381
                      errorsBySeverity:
                        critical: 274
                        high: 812
                        medium: 73
                        low: 85
                        info: 478
        '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:
  schemas:
    ErrorResponse_3:
      type: object
      properties:
        err:
          type: string
          description: Error message.
          example: example-err
    ScanStatus:
      type: object
      properties:
        scan_id:
          type: string
          description: Unique scan identifier.
          example: '905307'
        repositoryId:
          type: string
          description: Repository that was scanned.
          example: '225862'
        branch:
          type: string
          description: Branch that was scanned.
          example: example-branch
        status:
          type: string
          enum:
          - queued
          - running
          - completed
          - failed
          description: Current scan status.
          example: failed
        startTime:
          type: string
          format: date-time
          description: Scan start timestamp.
          example: '2025-06-09T14:49:57Z'
        endTime:
          type: string
          format: date-time
          description: Scan completion timestamp.
          example: '2026-10-02T12:40:08Z'
        scanTypes:
          type: array
          items:
            type: string
            enum:
            - iac
            - sca
            - secrets
            - cicd
          description: Types of scans included in this run.
          example:
          - sca
          - iac
        summary:
          type: object
          description: High-level scan result summary. Available after completion.
          properties:
            filesScanned:
              type: integer
              example: 387
            resourcesScanned:
              type: integer
              example: 861
            errorsBySeverity:
              type: object
              properties:
                critical:
                  type: integer
                  example: 932
                high:
                  type: integer
                  example: 868
                medium:
                  type: integer
                  example: 675
                low:
                  type: integer
                  example: 245
                info:
                  type: integer
                  example: 509
              example:
                critical: 138
                high: 977
                medium: 550
                low: 371
                info: 383
          example:
            filesScanned: 87
            resourcesScanned: 381
            errorsBySeverity:
              critical: 274
              high: 812
              medium: 73
              low: 85
              info: 478
    VulnerabilityFinding:
      type: object
      properties:
        finding_id:
          type: string
          description: Unique identifier of the finding.
          example: '299305'
        category_id:
          type: string
          description: Attack category identifier.
          example: '468963'
        category_name:
          type: string
          description: Human-readable attack category name.
          example: Staging Sensor 12
        severity:
          type: string
          enum:
          - informational
          - low
          - medium
          - high
          - critical
          description: Severity level of the vulnerability.
          example: high
        title:
          type: string
          description: Brief title describing the vulnerability.
          example: Branch Agent 11
        description:
          type: string
          description: Detailed description of the vulnerability and its impact.
          example: Applied applied configured incident rule incident threat.
        attack_prompt:
          type: string
          description: The adversarial prompt that revealed the vulnerability.
          example: example-attack_prompt
        model_response:
          type: string
          description: The AI model's response to the attack prompt, demonstrating the vulnerability. May be truncated.
          example: PA-3260
        remediation:
          type: string
          description: Recommended steps to mitigate the vulnerability.
          example: example-remediation
    ScanRequest:
      type: object
      required:
      - target_id
      - attack_categories
      properties:
        target_id:
          type: string
          description: ID of the scan target to assess.
          example: '645262'
        attack_categories:
          type: array
          items:
            type: string
          minItems: 1
          description: Attack category identifiers to include in the scan. Use GET /v1/attack-categories to retrieve available category IDs.
          example:
          - example-attack_categories_item
          - example-attack_categories_item
        custom_prompts:
          type: array
          items:
            type: string
          description: Optional custom adversarial prompts to include alongside the built-in attack library. Useful for testing application-specific threat scenarios.
          maxItems: 100
          example:
          - example-custom_prompts_item
          - example-custom_prompts_item
        max_attacks_per_category:
          type: integer
          description: Maximum number of attack probes per category. Limits scan duration for large attack libraries. If omitted, all available attacks for each category are executed.
          minimum: 1
          maximum: 1000
          example: 740
    Scan:
      type: object
      properties:
        scan_id:
          type: string
          description: Unique identifier of the scan.
          example: '588456'
        target_id:
          type: string
          description: ID of the scan target being assessed.
          example: '410241'
        target_name:
         

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/palo-alto-networks/refs/heads/main/openapi/palo-alto-networks-scans-api-openapi.yml