openapi: 3.1.0
info:
  title: Palo Alto Networks Threat Vault API
  description: >-
    REST API for querying Palo Alto Networks threat intelligence including
    threat signature metadata, ATP (Advanced Threat Prevention) analysis
    reports, content release notes, and API usage statistics. The Threat
    Vault provides access to the full catalog of antivirus, anti-spyware,
    vulnerability protection, and DNS Security signatures used by PAN-OS
    firewalls. Enables security operations teams to look up specific threats
    by ID, CVE, SHA-256, or name and retrieve historical signature data for
    threat hunting and incident response. Authentication uses an API key
    passed in the X-API-KEY header.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/threat-vault/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api.threatvault.paloaltonetworks.com/service/v1
  description: Threat Vault API production endpoint.
security:
- apiKey: []
tags:
- name: ATP
  description: Advanced Threat Prevention detailed analysis reports and PCAP files.
- name: ReleaseNotes
  description: Content release notes for PAN-OS content updates.
- name: Stats
  description: API usage statistics.
- name: Threats
  description: Threat signature lookup and metadata retrieval.
paths:
  /threats:
    get:
      operationId: getThreats
      summary: Palo Alto Networks Get Threat Signatures
      description: >-
        Retrieves threat signature metadata from the Threat Vault. Supports
        filtering by signature type, ID, SHA-256 hash, name, CVE identifier,
        and date range. Returns antivirus, anti-spyware, vulnerability
        protection, DNS security, and file type signature records.
      tags:
      - Threats
      parameters:
      - name: type
        in: query
        description: Signature type to filter results.
        schema:
          type: string
          enum:
          - antivirus
          - antispyware
          - vulnerability
          - dns
          - fileformat
        example: dns
      - name: id
        in: query
        description: Specific signature ID to retrieve.
        schema:
          type: integer
        example: 942
      - name: sha256
        in: query
        description: SHA-256 hash to look up associated threat signatures.
        schema:
          type: string
        example: fb3a5e00a1b4048bd5ae9bfe7fb263550abc9ecd5ae4876459215b04129e655d
      - name: name
        in: query
        description: Partial or exact signature name to search.
        schema:
          type: string
        example: Branch Gateway 77
      - name: cve
        in: query
        description: CVE identifier to find associated vulnerability signatures.
        schema:
          type: string
          example: CVE-2021-44228
        example: CVE-2021-44228
      - name: from
        in: query
        description: >-
          Start date for filtering signatures by release date
          (YYYY-MM-DD format).
        schema:
          type: string
          format: date
        example: '2026-05-06'
      - name: to
        in: query
        description: >-
          End date for filtering signatures by release date
          (YYYY-MM-DD format).
        schema:
          type: string
          format: date
        example: '2025-05-01'
      - 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 signatures to return.
        schema:
          type: integer
          default: 10
          maximum: 100
        example: 10
      responses:
        '200':
          description: Threat signatures returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreatList'
              examples:
                GetThreats200Example:
                  summary: Default getThreats 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    data: &id003
                      zingbox:
                      - id: 675
                        name: Primary Sensor 96
                        type: fileformat
                        subtype: custom
                        severity: informational
                        description: Suspicious detected Security policy applied network network applied firewall.
                        cve: &id001
                        - example-cve_item
                        - example-cve_item
                        default_action: reset-client
                        min_version: 10.0.1
                        max_version: 5.1.5
                        status: released
                        ori_release_version: 3.0.5
                        latest_release_version: 5.7.0
                        first_release_time: '2025-11-23T03:19:43Z'
                        latest_release_time: '2024-07-12T01:32:30Z'
                        sha256: &id002
                        - example-sha256_item
                        - example-sha256_item
                    count: 508
                    total: 403
                    offset: 515
                    limit: 625
        '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
  /threats/history:
    get:
      operationId: getThreatHistory
      summary: Palo Alto Networks Get Signature History
      description: >-
        Retrieves the version history of a specific threat signature including
        all previous releases, modifications, and associated content versions.
        Useful for tracking signature changes over time.
      tags:
      - Threats
      parameters:
      - name: id
        in: query
        required: true
        description: Signature ID to retrieve version history for.
        schema:
          type: integer
        example: 514
      - name: type
        in: query
        required: true
        description: Signature type.
        schema:
          type: string
          enum:
          - antivirus
          - antispyware
          - vulnerability
          - dns
          - fileformat
        example: dns
      - 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: Signature history returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreatHistoryList'
              examples:
                GetThreatHistory200Example:
                  summary: Default getThreatHistory 200 response
                  x-microcks-default: true
                  value:
                    success: false
                    data: &id004
                    - id: 915
                      name: Branch Agent 35
                      version: 4.1.4
                      release_time: '2026-12-25T01:36:47Z'
                      action: deprecated
                    - id: 915
                      name: Branch Agent 35
                      version: 4.1.4
                      release_time: '2026-12-25T01:36:47Z'
                      action: deprecated
                    total: 799
                    offset: 559
                    limit: 217
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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: &id006
                    - id: example-id
                      sha256: 1a0cc0aab37304dfb1801ee9999fdc70e10dcffd0bff8e3cc12d14e696abe57a
                      status: pending
                      verdict: grayware
                      create_time: '2024-11-24T09:15:12Z'
                      report: &id005
                        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
  /release-notes:
    get:
      operationId: getReleaseNotes
      summary: Palo Alto Networks Get Content Release Notes
      description: >-
        Retrieves content release notes for PAN-OS content updates including
        Applications and Threats, Antivirus, and WildFire content packages.
        Release notes describe new signatures, modified signatures, and
        deprecated signatures included in each content version.
      tags:
      - ReleaseNotes
      parameters:
      - name: type
        in: query
        required: true
        description: Content release type.
        schema:
          type: string
          enum:
          - content
          - antivirus
          - wildfire
        example: antivirus
      - name: version
        in: query
        description: Specific content version to retrieve notes for (e.g., 8000-7000).
        schema:
          type: string
        example: 1.5.2
      - 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: Release notes returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseNotesList'
              examples:
                GetReleaseNotes200Example:
                  summary: Default getReleaseNotes 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    data: &id007
                    - version: 10.5.6
                      type: wildfire
                      release_date: '2024-11-03'
                      new_signatures: 835
                      modified_signatures: 48
                      deprecated_signatures: 698
                      notes: Traffic threat Security applied network alert violation.
                    total: 124
                    offset: 201
                    limit: 455
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /stats:
    get:
      operationId: getStats
      summary: Palo Alto Networks Get API Usage Statistics
      description: >-
        Returns API usage statistics for the authenticated API key, including
        the number of requests made, quota limits, and usage breakdown by
        endpoint. Use this endpoint to monitor consumption against subscription
        limits.
      tags:
      - Stats
      responses:
        '200':
          description: API usage statistics returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiStats'
              examples:
                GetStats200Example:
                  summary: Default getStats 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    data: &id008
                      api_key: c0132cd88805a182d0438741905d074c
                      quota: 721
                      remaining: 197
                      used: 718
                      reset_time: '2025-11-13T16:19:53Z'
                      endpoint_usage: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Threat Vault API key. Generate your API key from the Palo Alto
        Networks customer support portal or the Developer Portal at
        pan.dev. The API key controls access level and daily quota limits.
  responses:
    BadRequest:
      description: Malformed request or invalid query parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient API key permissions or quota exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ThreatSignature:
      type: object
      description: Threat signature metadata record.
      properties:
        id:
          type: integer
          description: Unique signature identifier.
          example: 675
        name:
          type: string
          description: Signature name.
          example: Primary Sensor 96
        type:
          type: string
          enum:
          - antivirus
          - antispyware
          - vulnerability
          - dns
          - fileformat
          description: Signature type category.
          example: fileformat
        subtype:
          type: string
          description: Signature subtype (e.g., virus, trojan, exploit).
          example: custom
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - informational
          example: informational
        description:
          type: string
          description: Human-readable description of the threat.
          example: Suspicious detected Security policy applied network network applied firewall.
        cve:
          type: array
          items:
            type: string
          description: Associated CVE identifiers.
          example: *id001
        default_action:
          type: string
          enum:
          - alert
          - allow
          - drop
          - reset-both
          - reset-client
          - reset-server
          - block-ip
          - sinkhole
          description: Default action applied to traffic matching this signature.
          example: reset-client
        min_version:
          type: string
          description: Minimum PAN-OS version supporting this signature.
          example: 10.0.1
        max_version:
          type: string
          description: Maximum PAN-OS version supporting this signature (empty if still active).
          example: 5.1.5
        status:
          type: string
          enum:
          - released
          - deprecated
          - disabled
          example: released
        ori_release_version:
          type: string
          description: Content version in which this signature was first released.
          example: 3.0.5
        latest_release_version:
          type: string
          description: Most recent content version that updated this signature.
          example: 5.7.0
        first_release_time:
          type: string
          format: date-time
          description: Timestamp when the signature was first released.
          example: '2025-11-23T03:19:43Z'
        latest_release_time:
          type: string
          format: date-time
          description: Timestamp of the most recent signature update.
          example: '2024-07-12T01:32:30Z'
        sha256:
          type: array
          items:
            type: string
          description: SHA-256 hashes associated with this signature (antivirus).
          example: *id002
    ThreatList:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            zingbox:
              type: array
              items:
                $ref: '#/components/schemas/ThreatSignature'
              example:
              - id: 675
                name: Primary Sensor 96
                type: fileformat
                subtype: custom
                severity: informational
                description: Suspicious detected Security policy applied network network applied firewall.
                cve: *id001
                default_action: reset-client
                min_version: 10.0.1
                max_version: 5.1.5
                status: released
                ori_release_version: 3.0.5
                latest_release_version: 5.7.0
                first_release_time: '2025-11-23T03:19:43Z'
                latest_release_time: '2024-07-12T01:32:30Z'
                sha256: *id002
              - id: 675
                name: Primary Sensor 96
                type: fileformat
                subtype: custom
                severity: informational
                description: Suspicious detected Security policy applied network network applied firewall.
                cve: *id001
                default_action: reset-client
                min_version: 10.0.1
                max_version: 5.1.5
                status: released
                ori_release_version: 3.0.5
                latest_release_version: 5.7.0
                first_release_time: '2025-11-23T03:19:43Z'
                latest_release_time: '2024-07-12T01:32:30Z'
                sha256: *id002
          example: *id003
        count:
          type: integer
          description: Total number of matching signatures.
          example: 508
        total:
          type: integer
          example: 403
        offset:
          type: integer
          example: 515
        limit:
          type: integer
          example: 625
    ThreatHistoryEntry:
      type: object
      description: A historical record of a signature version.
      properties:
        id:
          type: integer
          example: 915
        name:
          type: string
          example: Branch Agent 35
        version:
          type: string
          description: Content version number for this history entry.
          example: 4.1.4
        release_time:
          type: string
          format: date-time
          example: '2026-12-25T01:36:47Z'
        action:
          type: string
          enum:
          - added
          - modified
          - deprecated
          example: deprecated
    ThreatHistoryList:
      type: object
      properties:
        success:
          type: boolean
          example: false
        data:
          type: array
          items:
            $ref: '#/components/schemas/ThreatHistoryEntry'
          example: *id004
        total:
          type: integer
          example: 799
        offset:
          type: integer
          example: 559
        limit:
          type: integer
          example: 217
    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: *id005
    AtpReportList:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/AtpReport'
          example: *id006
        total:
          type: integer
          example: 264
        offset:
          type: integer
          example: 161
        limit:
          type: integer
          example: 795
    ReleaseNote:
      type: object
      description: Content release notes for a specific PAN-OS content version.
      properties:
        version:
          type: string
          description: Content version identifier (e.g., 8000-7000).
          example: 10.5.6
        type:
          type: string
          enum:
          - content
          - antivirus
          - wildfire
          example: wildfire
        release_date:
          type: string
          format: date
          example: '2024-11-03'
        new_signatures:
          type: integer
          description: Number of new signatures in this release.
          example: 835
        modified_signatures:
          type: integer
          description: Number of modified signatures in this release.
          example: 48
        deprecated_signatures:
          type: integer
          description: Number of deprecated signatures in this release.
          example: 698
        notes:
          type: string
          description: Release notes text.
          example: Traffic threat Security applied network alert violation.
    ReleaseNotesList:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ReleaseNote'
          example: *id007
        total:
          type: integer
          example: 124
        offset:
          type: integer
          example: 201
        limit:
          type: integer
          example: 455
    ApiStats:
      type: object
      description: API usage statistics for the authenticated API key.
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            api_key:
              type: string
              description: Redacted API key identifier.
              example: 7f0aeb83312442613acf974dba5e853c
            quota:
              type: integer
              description: Daily request quota.
              example: 719
            remaining:
              type: integer
              description: Remaining requests in the current day.
              example: 93
            used:
              type: integer
              description: Number of requests used today.
              example: 810
            reset_time:
              type: string
              format: date-time
              description: Timestamp when the quota resets.
              example: '2026-08-06T23:19:12Z'
            endpoint_usage:
              type: object
              description: Request counts broken down by endpoint.
              additionalProperties:
                type: integer
              example: {}
          example: *id008
    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