WildFire API

openapi: 3.1.0
info:
  title: Palo Alto Networks WildFire API
  description: >-
    Cloud-based REST API for submitting files, URLs, and links to the Palo Alto
    Networks WildFire sandbox for advanced malware analysis. WildFire executes
    submitted samples in a safe, isolated environment and returns threat verdicts
    (benign, malware, grayware, phishing) along with detailed behavioral
    analysis reports. The API supports file submission via multipart form
    upload, verdict queries by file hash (MD5 or SHA-256), bulk verdict
    lookups, and retrieval of PCAP network captures and full analysis reports
    in XML or PDF format. Authentication uses an API key passed as a form
    field in every POST request body.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/wildfire/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://wildfire.paloaltonetworks.com/publicapi
  description: WildFire global cloud (US).
- url: https://wildfire.{region}.paloaltonetworks.com/publicapi
  description: WildFire regional cloud endpoint.
  variables:
    region:
      description: Regional deployment (e.g., eu, jp).
      default: eu
tags:
- name: Report
  description: Retrieve detailed analysis reports and supporting files.
- name: Submit
  description: File, URL, and link submission for malware analysis.
- name: Verdict
  description: Retrieve analysis verdicts by file hash.
paths:
  /submit/file:
    post:
      operationId: submitFile
      summary: Palo Alto Networks Submit File for Analysis
      description: >-
        Submits a file to WildFire for malware analysis. The file is executed
        in an isolated sandbox environment and analyzed for malicious behavior.
        Supported file types include PE executables, DLLs, Office documents,
        PDFs, APKs, and scripts. Returns a SHA-256 hash and upload status.
        Poll /get/verdict for the analysis result.
      tags:
      - Submit
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - apikey
              - file
              properties:
                apikey:
                  type: string
                  description: WildFire API key for authentication.
                file:
                  type: string
                  format: binary
                  description: The file to submit for analysis (max 100 MB).
            examples:
              SubmitFileRequestExample:
                summary: Default submitFile request
                x-microcks-default: true
                value:
                  apikey: example-apikey
                  file: example-file
      responses:
        '200':
          description: File submitted successfully.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              examples:
                SubmitFile200Example:
                  summary: Default submitFile 200 response
                  x-microcks-default: true
                  value:
                    upload-file-info: &id001
                      filename: Primary Firewall 60
                      filetype: standard
                      fileurl: example-fileurl
                      md5: e80837f90fb511c2a14570a6acc47263
                      sha256: b4ed4912613bb347504a26b57f498c5ea2364a7174f06253e7336aeac148a038
                      size: 806
                      url: https://mail.acme-systems.org/3910a3
        '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
  /submit/url:
    post:
      operationId: submitUrl
      summary: Palo Alto Networks Submit URL for Analysis
      description: >-
        Submits a URL to WildFire for phishing and malware analysis. WildFire
        visits the URL in an isolated browser environment and analyzes the
        page content and any downloaded files for malicious behavior.
      tags:
      - Submit
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - apikey
              - url
              properties:
                apikey:
                  type: string
                  description: WildFire API key for authentication.
                url:
                  type: string
                  description: URL to submit for analysis (must be a valid HTTP or HTTPS URL).
            examples:
              SubmitUrlRequestExample:
                summary: Default submitUrl request
                x-microcks-default: true
                value:
                  apikey: example-apikey
                  url: https://mail.example.com/063e82
      responses:
        '200':
          description: URL submitted successfully.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              examples:
                SubmitUrl200Example:
                  summary: Default submitUrl 200 response
                  x-microcks-default: true
                  value:
                    upload-file-info: *id001
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /submit/link:
    post:
      operationId: submitLink
      summary: Palo Alto Networks Submit Link for Analysis
      description: >-
        Submits a hyperlink for WildFire analysis. Similar to URL submission
        but intended for links extracted from email bodies or documents.
      tags:
      - Submit
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - apikey
              - link
              properties:
                apikey:
                  type: string
                  description: WildFire API key for authentication.
                link:
                  type: string
                  description: Link to submit for analysis.
            examples:
              SubmitLinkRequestExample:
                summary: Default submitLink request
                x-microcks-default: true
                value:
                  apikey: example-apikey
                  link: https://portal.acme-systems.org/87b216
      responses:
        '200':
          description: Link submitted successfully.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              examples:
                SubmitLink200Example:
                  summary: Default submitLink 200 response
                  x-microcks-default: true
                  value:
                    upload-file-info: *id001
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /get/verdict:
    post:
      operationId: getVerdict
      summary: Palo Alto Networks Get Verdict by Hash
      description: >-
        Retrieves the WildFire analysis verdict for a file identified by its
        MD5 or SHA-256 hash. Verdicts are: 0 (benign), 1 (malware), 2 (grayware),
        4 (phishing), -100 (pending analysis), -101 (error), -102 (unknown),
        -103 (invalid hash).
      tags:
      - Verdict
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - apikey
              - hash
              properties:
                apikey:
                  type: string
                  description: WildFire API key for authentication.
                hash:
                  type: string
                  description: MD5 or SHA-256 hash of the file to query.
            examples:
              GetVerdictRequestExample:
                summary: Default getVerdict request
                x-microcks-default: true
                value:
                  apikey: example-apikey
                  hash: example-hash
      responses:
        '200':
          description: Verdict returned successfully.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/VerdictResponse'
              examples:
                GetVerdict200Example:
                  summary: Default getVerdict 200 response
                  x-microcks-default: true
                  value:
                    get-verdict-info: &id002
                      md5: 38498da0e6edd44b63ec5776e3ac4349
                      sha256: 48a8bc75aef249c015423b2e6abe7c31f9432715b65e0b0310e65f34d6b5d3ca
                      verdict: -101
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /get/verdicts:
    post:
      operationId: getBulkVerdicts
      summary: Palo Alto Networks Get Bulk Verdicts
      description: >-
        Retrieves WildFire analysis verdicts for multiple files in a single
        request. Submit an array of MD5 or SHA-256 hashes to query up to 500
        verdicts simultaneously.
      tags:
      - Verdict
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - apikey
              - hash
              properties:
                apikey:
                  type: string
                  description: WildFire API key for authentication.
                hash:
                  type: array
                  items:
                    type: string
                  description: Array of MD5 or SHA-256 hashes to query (max 500).
            examples:
              GetBulkVerdictsRequestExample:
                summary: Default getBulkVerdicts request
                x-microcks-default: true
                value:
                  apikey: example-apikey
                  hash:
                  - example-hash_item
                  - example-hash_item
      responses:
        '200':
          description: Bulk verdicts returned successfully.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/BulkVerdictResponse'
              examples:
                GetBulkVerdicts200Example:
                  summary: Default getBulkVerdicts 200 response
                  x-microcks-default: true
                  value:
                    get-verdicts-info: &id003
                      entry:
                      - md5: 97ccdf884551f2ecf8abc10da662652d
                        sha256: 47d2198514583bc897bb7b8ae089187d336a6de865b6d6ad0e943777abbe85af
                        verdict: 596
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /get/report:
    post:
      operationId: getReport
      summary: Palo Alto Networks Get Analysis Report
      description: >-
        Retrieves the full WildFire analysis report for a sample identified
        by its MD5 or SHA-256 hash. Reports include behavioral analysis,
        network activity, file system changes, registry modifications, and
        process information. Reports are available in XML or PDF format.
      tags:
      - Report
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - apikey
              - hash
              - format
              properties:
                apikey:
                  type: string
                  description: WildFire API key for authentication.
                hash:
                  type: string
                  description: MD5 or SHA-256 hash of the analyzed sample.
                format:
                  type: string
                  enum:
                  - xml
                  - pdf
                  description: Report output format.
                type:
                  type: string
                  description: >-
                    Hash type. If omitted, WildFire auto-detects based on
                    hash length.
                  enum:
                  - md5
                  - sha256
            examples:
              GetReportRequestExample:
                summary: Default getReport request
                x-microcks-default: true
                value:
                  apikey: example-apikey
                  hash: example-hash
                  format: pdf
                  type: sha256
      responses:
        '200':
          description: Analysis report returned successfully.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AnalysisReport'
              examples:
                GetReport200Example:
                  summary: Default getReport 200 response
                  x-microcks-default: true
                  value:
                    wildfire: &id004
                      version: 2.3.1
                      file_info:
                        file_stype: standard
                        size: 531
                        md5: fe002567a9904394d4ceafd8a4fb3f00
                        sha256: 59258b8b3904457b736c4ebf1128de54a88068379c519afe5c7cae56cb75cd1e
                        create_time: '2025-07-04T20:04:29Z'
                      task_info:
                        report: example-report
            application/pdf:
              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
  /get/sample:
    post:
      operationId: getSample
      summary: Palo Alto Networks Download Sample
      description: >-
        Downloads the original sample file identified by its hash. Only
        available for samples where the verdict is malware or grayware.
        Requires an API key with sample download permissions.
      tags:
      - Report
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - apikey
              - hash
              properties:
                apikey:
                  type: string
                  description: WildFire API key with sample download permissions.
                hash:
                  type: string
                  description: MD5 or SHA-256 hash of the sample to download.
                type:
                  type: string
                  enum:
                  - md5
                  - sha256
            examples:
              GetSampleRequestExample:
                summary: Default getSample request
                x-microcks-default: true
                value:
                  apikey: example-apikey
                  hash: example-hash
                  type: md5
      responses:
        '200':
          description: Sample file returned successfully.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /get/pcap:
    post:
      operationId: getPcap
      summary: Palo Alto Networks Get PCAP File
      description: >-
        Downloads the network packet capture (PCAP) file recorded during
        sandbox analysis of the specified sample. PCAP files contain the
        network traffic generated by the malware during detonation.
      tags:
      - Report
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - apikey
              - hash
              - platform
              properties:
                apikey:
                  type: string
                  description: WildFire API key for authentication.
                hash:
                  type: string
                  description: MD5 or SHA-256 hash of the analyzed sample.
                type:
                  type: string
                  enum:
                  - md5
                  - sha256
                platform:
                  type: string
                  description: >-
                    Analysis platform identifier (e.g., 100 for Windows XP,
                    200 for Windows 7, 400 for Android).
            examples:
              GetPcapRequestExample:
                summary: Default getPcap request
                x-microcks-default: true
                value:
                  apikey: example-apikey
                  hash: example-hash
                  type: md5
                  platform: example-platform
      responses:
        '200':
          description: PCAP file returned successfully.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    BadRequest:
      description: Malformed request, missing required parameters, or invalid API key format.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing API key or API key is invalid.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        Valid API key but insufficient permissions for the requested operation
        (e.g., sample download requires elevated permissions).
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: No analysis result found for the specified hash.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: An internal server error occurred.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    SubmitResponse:
      type: object
      description: Response returned after successfully submitting a file, URL, or link.
      properties:
        upload-file-info:
          type: object
          properties:
            filename:
              type: string
              description: Original filename of the submitted file.
              example: Staging Agent 09
            filetype:
              type: string
              description: Detected file type.
              example: advanced
            fileurl:
              type: string
              description: URL of the submitted link or URL sample.
              example: example-fileurl
            md5:
              type: string
              description: MD5 hash of the submitted file.
              example: c3b5353b5e324afe11011c986fdff25e
            sha256:
              type: string
              description: SHA-256 hash of the submitted file.
              example: 6e459dbe581619c17119c4b6902f58ba424ef03b271bedcfdbc0431b7912882c
            size:
              type: integer
              description: File size in bytes.
              example: 334
            url:
              type: string
              description: Submitted URL value.
              example: https://login.example.com/8d2a5c
          example: *id001
    VerdictResponse:
      type: object
      description: WildFire verdict result for a single file hash query.
      properties:
        get-verdict-info:
          type: object
          properties:
            md5:
              type: string
              description: MD5 hash of the queried file.
              example: 629a220afeea672abcc2e391ea07b26d
            sha256:
              type: string
              description: SHA-256 hash of the queried file.
              example: 365d23a6a81b4ff0b6ea99f59667be72b252544284c549fc165bc04b9be441be
            verdict:
              type: integer
              description: >-
                Verdict code: 0 (benign), 1 (malware), 2 (grayware),
                4 (phishing), -100 (pending), -101 (error), -102 (unknown),
                -103 (invalid hash).
              enum:
              - 0
              - 1
              - 2
              - 4
              - -100
              - -101
              - -102
              - -103
              example: 2
          example: *id002
    BulkVerdictResponse:
      type: object
      description: WildFire bulk verdict results for multiple hash queries.
      properties:
        get-verdicts-info:
          type: object
          properties:
            entry:
              type: array
              items:
                type: object
                properties:
                  md5:
                    type: string
                    example: e508ea95575f45e7ba5e47b556d7a241
                  sha256:
                    type: string
                    example: 328888a8b561894deaaba0fb4e0abda175b02cafd71320b2b72d18c59139fd86
                  verdict:
                    type: integer
                    example: 792
              example:
              - md5: 36e5049a68495c51691a114c9087a07e
                sha256: c8899b756e0d13dd355342c97737825750fdb64903f4770725334e4991c4dc23
                verdict: 168
          example: *id003
    AnalysisReport:
      type: object
      description: >-
        Detailed WildFire analysis report including behavioral analysis,
        network activity, and system changes observed during sandbox execution.
      properties:
        wildfire:
          type: object
          properties:
            version:
              type: string
              example: 7.4.8
            file_info:
              type: object
              properties:
                file_stype:
                  type: string
                  example: standard
                size:
                  type: integer
                  example: 922
                md5:
                  type: string
                  example: db68a8bb1f10612a7b71092b35e4a545
                sha256:
                  type: string
                  example: 51031294c848b48ea0dc621ed7f3a86a61174866d4df7f6f379875b2415e918c
                create_time:
                  type: string
                  format: date-time
                  example: '2025-09-02T12:12:51Z'
              example:
                file_stype: standard
                size: 897
                md5: cb973a5cae8352a4a0e24ef1084a3b40
                sha256: 33e4e05c75f8845fc07508f405087c2628fafecb25faffccdd91728a00239652
                create_time: '2024-11-03T13:49:56Z'
            task_info:
              type: object
              properties:
                report:
                  oneOf:
                  - $ref: '#/components/schemas/SandboxReport'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SandboxReport'
                  example: example-report
              example:
                report: example-report
          example: *id004
    SandboxReport:
      type: object
      description: Analysis results from a single sandbox execution environment.
      properties:
        platform:
          type: string
          description: Platform identifier (e.g., 100 for Windows XP SP3).
          example: example-platform
        software:
          type: string
          description: Sandbox software environment.
          example: example-software
        version:
          type: string
          example: 10.9.8
        summary:
          type: object
          properties:
            '@verdict':
              type: string
              enum:
              - benign
              - malware
              - grayware
              - phishing
              example: grayware
          example:
            '@verdict': grayware
        network:
          type: object
          properties:
            dns:
              type: array
              items:
                type: object
                properties:
                  '@query':
                    type: string
                    example: example-@query
                  '@response':
                    type: string
                    example: example-@response
              example:
              - '@query': example-@query
                '@response': example-@response
            tcp:
              type: array
              items:
                type: object
                properties:
                  '@ip':
                    type: string
                    example: example-@ip
                  '@port':
                    type: integer
                    example: 344
                  '@country':
                    type: string
                    example: JP
              example:
              - '@ip': example-@ip
                '@port': 823
                '@country': DE
              - '@ip': example-@ip
                '@port': 728
                '@country': JP
            http:
              type: array
              items:
                type: object
                properties:
                  '@request':
                    type: string
                    example: example-@request
                  '@response':
                    type: string
                    example: example-@response
              example:
              - '@request': example-@request
                '@response': example-@response
              - '@request': example-@request
                '@response': example-@response
          example:
            dns:
            - '@query': example-@query
              '@response': example-@response
            tcp:
            - '@ip': example-@ip
              '@port': 719
              '@country': JP
            http:
            - '@request': example-@request
              '@response': example-@response
        process_list:
          type: object
          properties:
            process:
              type: array
              items:
                type: object
                properties:
                  '@name':
                    type: string
                    example: Corporate Sensor 01
                  '@pid':
                    type: string
                    example: '394815'
                  '@text':
                    type: string
                    example: example-@text
              example:
              - '@name': Branch Agent 68
                '@pid': '593743'
                '@text': example-@text
              - '@name': Primary Agent 67
                '@pid': '145182'
                '@text': example-@text
          example:
            process:
            - '@name': Branch Policy 87
              '@pid': '603246'
              '@text': example-@text
    ErrorResponse:
      type: object
      description: Error response returned when a request fails.
      properties:
        error:
          type: object
          properties:
            error-message:
              type: string
              description: Human-readable error message.
              example: example-error-message
          example:
            error-message: example-error-message