openapi: 3.2.0
info:
  version: '1.0'
  contact: {}
  description: ' The Advanced Threat Prevention API endpoints require an active subscription to the Advanced Threat Prevention security service. These endpoints can only be accessed using the API key associated with the account that holds the subscription. Attempting to view an unauthorized report ID will not return any results. List of Advanced Threat Prevention API endpoints: 1. Link to [Request Advanced Threat Prevention cloud analysis report](/threat-vault/api/postatpreportsbatchmode) 2. Link to [Request Advanced Threat Prevention cloud analysis report PCAP](/threat-vault/api/getatppcaps) '
  title: Advanced Threat Prevention API
servers:
- url: https://api.threatvault.paloaltonetworks.com/service/v1
tags:
- name: Advanced Threat Prevention
paths:
  /atp/reports:
    post:
      description: 'A POST request to retrieve the ATP report by report id in batch mode. Batch limit is 100 entries. Get one or more ATP reports. User must provide **one or more** report IDs in request body. '
      operationId: postatpreportsbatchmode
      requestBody:
        content:
          application/json:
            schema:
              example:
                id:
                - c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50
                - a23b5d46d6ac77e70376080517991187a07ac008bfc799f08795d59c57e23a50
              properties:
                id:
                  description: "Provides the ATP report by matching the report id of the customer.\n\n---\n```\ncurl -v -X POST -H 'X-API-KEY: API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"id\": [\"c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50\", \"a23b5d46d6ac77e70376080517991187a07ac008bfc799f08795d59c57e23a50\"]}' \\\n  'https://api.threatvault.paloaltonetworks.com/service/v1/atp/reports'\n```\n"
                  items:
                    type: string
                  type: array
              type: object
        required: true
      responses:
        '200':
          description: Request succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: The response status.
                    example: true
                  data:
                    type: array
                    description: 'The data of the response.

                      '
                    items:
                      $ref: '#/components/schemas/ATPReportList'
                  message:
                    type: string
                    description: Generic response message.
                    example: Successful
          headers:
            X-Day-RateLimit-Limit:
              description: The maximum number of requests that the user is permitted to make per day.
              example: 2000
              schema:
                type: integer
            X-Day-RateLimit-Remaining:
              description: The number of requests remaining in the current rate limit window (one day).
              schema:
                type: integer
            X-Day-RateLimit-Reset:
              description: The epoch timestamp at which the current rate limit window (one day) resets.
              schema:
                type: integer
            X-Minute-RateLimit-Limit:
              description: The maximum number of requests that the user is permitted to make per minute.
              example: 200
              schema:
                type: integer
            X-Minute-RateLimit-Remaining:
              description: The number of requests remaining in the current rate limit window (one minute).
              schema:
                type: integer
            X-Minute-RateLimit-Reset:
              description: The epoch timestamp at which the current rate limit window (one minute) resets.
              schema:
                type: integer
        4XX:
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Generic response message.
                    example: Error message.
                    type: string
                  success:
                    description: The response status.
                    example: false
                    type: boolean
                type: object
          description: Client related error response
        5XX:
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Generic response message.
                    example: Error message.
                    type: string
                  success:
                    description: The response status.
                    example: false
                    type: boolean
                type: object
          description: Server related error response
      security:
      - X-API-KEY: []
      summary: Request Advanced Threat Prevention Report in Batch Mode
      tags:
      - Advanced Threat Prevention
  /atp/reports/pcaps:
    get:
      description: 'A GET request to retrieve the ATP report sample (packet capture) by report id. '
      operationId: getatppcaps
      parameters:
      - description: "Retrieve the ATP report sample (packet capture) by report id.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n  'https://api.threatvault.paloaltonetworks.com/service/v1/atp/reports/pcaps?id=c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50'\n```"
        in: query
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: Request succeeded
          headers:
            X-Day-RateLimit-Limit:
              description: The maximum number of requests that the user is permitted to make per day.
              example: 2000
              schema:
                type: integer
            X-Day-RateLimit-Remaining:
              description: The number of requests remaining in the current rate limit window (one day).
              schema:
                type: integer
            X-Day-RateLimit-Reset:
              description: The epoch timestamp at which the current rate limit window (one day) resets.
              schema:
                type: integer
            X-Minute-RateLimit-Limit:
              description: The maximum number of requests that the user is permitted to make per minute.
              example: 200
              schema:
                type: integer
            X-Minute-RateLimit-Remaining:
              description: The number of requests remaining in the current rate limit window (one minute).
              schema:
                type: integer
            X-Minute-RateLimit-Reset:
              description: The epoch timestamp at which the current rate limit window (one minute) resets.
              schema:
                type: integer
        4XX:
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Generic response message.
                    example: Error message.
                    type: string
                  success:
                    description: The response status.
                    example: false
                    type: boolean
                type: object
          description: Certificate related error response
        5XX:
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Generic response message.
                    example: Error message.
                    type: string
                  success:
                    description: The response status.
                    example: false
                    type: boolean
                type: object
          description: Server related error response
      security:
      - X-API-KEY: []
      summary: Request Advanced Threat Prevention Report PCAP
      tags:
      - Advanced Threat Prevention
components:
  schemas:
    ATPReportList:
      type: object
      properties:
        report_id:
          type: string
          description: The id of the ATP report.
          example: c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50
        err_msg:
          type: string
          description: Any error message related to the report.
          example: Error
        panos_info:
          type: object
          description: All related PAN-OS information.
          properties:
            fw_hostname:
              type: string
              description: Firewall Hostname.
              example: fw-1
            fw_addr_v4:
              type: string
              description: Firewall MP interface IPv4.
              example: 10.0.0.0
            fw_addr_v6:
              type: string
              description: Firewall MP interface IPv6. (Can be empty)
              example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
            fw_app_version:
              type: string
              description: Firewall Content package version.
              example: 8527-12345
            fw_sw_version:
              type: string
              description: Firewall PANOS version.
              example: 10.2.1
            fw_serial:
              type: string
              description: Firewall Serial Number.
              example: '000000000000001'
            fw_model:
              type: string
              description: Firewall model.
              example: PA-VM
        session_info:
          type: object
          description: All related session information.
          properties:
            session_id:
              type: string
              description: Session ID.
              example: '123456'
            session_timestamp:
              type: string
              description: Session timestamp.
              example: 2022-04-11 10:00:00.740261-07:00
            flow_info:
              type: object
              properties:
                saddr:
                  type: string
                  description: Session source IP address.
                  example: 1.1.1.1
                daddr:
                  type: string
                  description: Session destination IP address.
                  example: 1.1.1.2
                sport:
                  type: string
                  description: Session source IP port.
                  example: '49234'
                dport:
                  type: string
                  description: Session destination IP port.
                  example: '80'
                data_type:
                  type: string
                  enum:
                  - http
                  - ssl
                  - unknown-tcp
                  - unknown-udp
                  description: The payload type.
                  example: http
        transaction_data:
          type: object
          description: The list of transactions of the session. One session may have one or many transactions.
          properties:
            transaction_id:
              type: string
              description: The transaction id.
              example: '0'
            payload_sha256:
              type: string
              description: The SHA256 hash value of the payload.
              example: a15e20ddc3a0850b64cdc87a23230b51466f9879345435973ce360e80e1f670e
            detection_results:
              type: object
              description: The detection results information.
              properties:
                detection_service:
                  type: string
                  description: The detection service.
                  example: Empire C2
                details:
                  type: object
                  description: Details information.
                  properties:
                    attack_analysis:
                      type: object
                      description: The attack analysis information.
                      properties:
                        Attack Description:
                          type: string
                          description: The attack description.
                          example: Your system is under an early Empire C2 attack stage. The malware in your system is trying to set up the connection channel with a C2 server 192.168.10.4.
                        Attack Details:
                          type: string
                          description: The attack details.
                          example: It is at the Empire C2 staging phase. The potential Empire C2 server is 192.168.10.4, and it is trying to install payloads in your system for future attacks.
                        Attack Evidences:
                          type: string
                          description: The attack evidence.
                          example: The session key is encoded with netbios.
                    payload_info:
                      type: object
                      description: The request payload information.
                      properties:
                        Connection:
                          type: string
                          description: A general header controls whether the network connection stays open after the current transaction finishes.
                          example: Keep-Alive
                        Cookie:
                          type: string
                          description: A header that contains stored HTTP cookies associated with the server.
                          example: session=/YMjhqiUqqLLm7Lt8PXbLiMtD3Q%3D
                        Host:
                          type: string
                          description: A header that specifies the host and port number of the server to which the request is being sent.
                          example: 192.168.10.4:1813
                        Method:
                          type: string
                          description: A header that defines the desired action to be performed for a given resource.
                          example: GET
                        URI:
                          type: string
                          description: A header that defines the resource.
                          example: /daeedrxc/
                        User-Agent:
                          type: string
                          description: A header that identifies the requesting user agent.
                          example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9
                        Version:
                          type: string
                          description: A header that specifies the HTTP version.
                          example: HTTP/1.1
                verdict:
                  type: integer
                  description: The verdict value.
                  example: 1
            reports:
              type: array
              description: The list of detection service reports.
              items:
                type: object
                properties:
                  ds_name:
                    type: string
                    description: The detection service name.
                    example: mlc2-http-ids
                  ds_report:
                    type: object
                    description: The list of detection service reports.
                    properties:
                      payload_info:
                        type: object
                        description: Optional payload information.
                        example: {}
                      malware_families:
                        type: object
                        description: The list of malware families.
                        properties:
                          malware_family_type:
                            type: string
                            description: The name/type of the malware family.
                            example: ''
                          confidence:
                            type: string
                            description: The confidence value.
                            example: '0.85'
                        example: {}
                  status:
                    type: string
                    description: A flag to indicate the report is ready or not.
                    example: ok
  securitySchemes:
    X-API-KEY:
      description: API key to query https://api.threatvault.paloaltonetworks.com/service/v1
      in: header
      name: X-API-KEY
      type: apiKey