openapi: 3.1.0
info:
  title: Palo Alto Networks Cortex XDR REST API
  description: >-
    REST API for the Cortex XDR extended detection and response platform.
    Provides programmatic access to incidents, alerts, endpoints, scripts,
    XQL queries, and audit logs. Cortex XDR correlates data from network,
    endpoint, cloud, and third-party sources to detect and investigate threats.
    Authentication uses a custom HMAC-SHA256 scheme: generate an API key ID
    and secret from the Cortex XDR settings, then sign each request using the
    x-xdr-auth-id, x-xdr-nonce, x-xdr-timestamp, and x-xdr-hmac-v2 headers.
    All API endpoints use POST with JSON request bodies containing a request_data
    object for filters and parameters.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/cortex/docs/xdr/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api-{fqdn}/public_api/v1
  description: Cortex XDR tenant API endpoint.
  variables:
    fqdn:
      description: >-
        Tenant FQDN from the Cortex XDR settings page (e.g.,
        example.xdr.us.paloaltonetworks.com).
      default: example.xdr.us.paloaltonetworks.com
security:
- xdrAuth: []
tags:
- name: Alerts
  description: Alert retrieval and management.
- name: Audit
  description: Audit and management log retrieval.
- name: Endpoints
  description: Endpoint management, isolation, and scanning.
- name: Incidents
  description: Incident management and investigation.
- name: Scripts
  description: Script execution and results retrieval.
- name: XQL
  description: XQL (Extended Query Language) query execution.
paths:
  /incidents/get_incidents:
    post:
      operationId: getIncidents
      summary: Palo Alto Networks List Incidents
      description: >-
        Returns a list of incidents matching the specified filter criteria.
        Incidents group related alerts into a unified investigation context.
        Supports filtering by incident ID, status, severity, and creation time.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                      description: Filter criteria to apply to the incident list.
                    search_from:
                      type: integer
                      description: Pagination offset (zero-based).
                      default: 0
                    search_to:
                      type: integer
                      description: Upper bound of the result range.
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetIncidentsRequestExample:
                summary: Default getIncidents request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
                    - field: example-field
                      operator: lte
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Incidents returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      incidents:
                        type: array
                        items:
                          $ref: '#/components/schemas/Incident'
              examples:
                GetIncidents200Example:
                  summary: Default getIncidents 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 176
                      result_count: 940
                      incidents:
                      - incident_id: '877543'
                        incident_name: Branch Gateway 82
                        description: Firewall traffic applied alert threat blocked Security rule.
                        status: resolved_threat_handled
                        severity: informational
                        assigned_user_mail: analyst1@example.com
                        assigned_user_pretty_name: Carlos Smith
                        alert_count: 509
                        low_severity_alert_count: 929
                        med_severity_alert_count: 295
                        high_severity_alert_count: 602
                        critical_severity_alert_count: 936
                        user_count: 170
                        host_count: 720
                        creation_time: 1707012665747
                        modification_time: 1744706901976
                        detection_time: 1704757310414
                        starred: true
                        xdr_url: https://portal.acme-systems.org/0455da
                        rule_based_score: 942
                        manual_score: 174
        '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
  /incidents/get_incident_extra_data:
    post:
      operationId: getIncidentExtraData
      summary: Palo Alto Networks Get Incident Details
      description: >-
        Returns detailed information about a specific incident including
        all associated alerts, network artifacts, file artifacts, and
        endpoint details.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - incident_id
                  properties:
                    incident_id:
                      type: string
                      description: Unique identifier of the incident.
                    alerts_limit:
                      type: integer
                      description: Maximum number of alerts to include in response.
                      default: 1000
            examples:
              GetIncidentExtraDataRequestExample:
                summary: Default getIncidentExtraData request
                x-microcks-default: true
                value:
                  request_data:
                    incident_id: '709824'
                    alerts_limit: 1000
      responses:
        '200':
          description: Incident details returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      incident:
                        $ref: '#/components/schemas/IncidentDetail'
                      alerts:
                        type: object
                        properties:
                          total_count:
                            type: integer
                          data:
                            type: array
                            items:
                              $ref: '#/components/schemas/Alert'
                      network_artifacts:
                        type: object
                      file_artifacts:
                        type: object
              examples:
                GetIncidentExtraData200Example:
                  summary: Default getIncidentExtraData 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      incident: example-incident
                      alerts:
                        total_count: 428
                        data:
                        - alert_id: '999423'
                          detection_timestamp: 1733555086833
                          name: Staging Policy 70
                          category: custom
                          description: Rule incident incident firewall suspicious monitoring activity threat rule monitoring suspicious detected.
                          host_ip: &id001
                          - example-host_ip_item
                          - example-host_ip_item
                          host_name: Corporate Agent 14
                          user_name: jsmith
                          mac: &id002
                          - example-mac_item
                          source: example-source
                          action: alert
                          action_pretty: alert
                          severity: informational
                          matching_status: running
                          alert_type: standard
                          resolution_status: enabled
                          resolution_comment: Monitoring threat applied Security investigation Security configured.
                      network_artifacts: {}
                      file_artifacts: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /incidents/update_incident:
    post:
      operationId: updateIncident
      summary: Palo Alto Networks Update Incident
      description: >-
        Updates the status, severity, assignee, or other mutable fields of a
        specific incident. Only the fields provided in the request body are
        modified.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - incident_id
                  properties:
                    incident_id:
                      type: string
                    status:
                      type: string
                      enum:
                      - new
                      - under_investigation
                      - resolved_threat_handled
                      - resolved_known_issue
                      - resolved_duplicate
                      - resolved_false_positive
                      - resolved_other
                    severity:
                      type: string
                      enum:
                      - high
                      - medium
                      - low
                    assigned_user_mail:
                      type: string
                      description: Email of the user to assign the incident to.
                    assigned_user_pretty_name:
                      type: string
                    resolve_comment:
                      type: string
                      description: Resolution comment (required when closing an incident).
                    add_comment:
                      type: string
                      description: Comment to add to the incident timeline.
            examples:
              UpdateIncidentRequestExample:
                summary: Default updateIncident request
                x-microcks-default: true
                value:
                  request_data:
                    incident_id: '498189'
                    status: resolved_duplicate
                    severity: high
                    assigned_user_mail: security-ops@example.com
                    assigned_user_pretty_name: Jane Garcia
                    resolve_comment: Detected endpoint configured policy firewall Security malware rule suspicious alert incident network.
                    add_comment: Endpoint detected suspicious incident network firewall threat malware configured blocked alert investigation.
      responses:
        '200':
          description: Incident updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: boolean
              examples:
                UpdateIncident200Example:
                  summary: Default updateIncident 200 response
                  x-microcks-default: true
                  value:
                    reply: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alerts/get_alerts:
    post:
      operationId: getAlerts
      summary: Palo Alto Networks Get Alerts
      description: >-
        Returns alerts matching the specified filter criteria. Alerts represent
        individual detections from endpoint, network, or cloud data sources.
        Supports filtering by alert ID, severity, category, and timestamp.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetAlertsRequestExample:
                summary: Default getAlerts request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Alerts returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      alerts:
                        type: array
                        items:
                          $ref: '#/components/schemas/Alert'
              examples:
                GetAlerts200Example:
                  summary: Default getAlerts 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 56
                      result_count: 969
                      alerts:
                      - alert_id: '999423'
                        detection_timestamp: 1733555086833
                        name: Staging Policy 70
                        category: custom
                        description: Rule incident incident firewall suspicious monitoring activity threat rule monitoring suspicious detected.
                        host_ip: *id001
                        host_name: Corporate Agent 14
                        user_name: jsmith
                        mac: *id002
                        source: example-source
                        action: alert
                        action_pretty: alert
                        severity: informational
                        matching_status: running
                        alert_type: standard
                        resolution_status: enabled
                        resolution_comment: Monitoring threat applied Security investigation Security configured.
                      - alert_id: '999423'
                        detection_timestamp: 1733555086833
                        name: Staging Policy 70
                        category: custom
                        description: Rule incident incident firewall suspicious monitoring activity threat rule monitoring suspicious detected.
                        host_ip: *id001
                        host_name: Corporate Agent 14
                        user_name: jsmith
                        mac: *id002
                        source: example-source
                        action: alert
                        action_pretty: alert
                        severity: informational
                        matching_status: running
                        alert_type: standard
                        resolution_status: enabled
                        resolution_comment: Monitoring threat applied Security investigation Security configured.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /endpoints/get_endpoints:
    post:
      operationId: getEndpoints
      summary: Palo Alto Networks List Endpoints
      description: >-
        Returns a list of endpoints enrolled in Cortex XDR. Supports filtering
        by endpoint ID, hostname, IP address, operating system, and protection
        status.
      tags:
      - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetEndpointsRequestExample:
                summary: Default getEndpoints request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
                    - field: example-field
                      operator: lte
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Endpoints returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      endpoints:
                        type: array
                        items:
                          $ref: '#/components/schemas/Endpoint'
              examples:
                GetEndpoints200Example:
                  summary: Default getEndpoints 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 1
                      result_count: 161
                      endpoints:
                      - endpoint_id: '472938'
                        endpoint_name: Branch Sensor 33
                        endpoint_type: WORKSTATION
                        endpoint_status: UNINSTALLED
                        os_type: AGENT_OS_LINUX
                        ip: &id003
                        - example-ip_item
                        - example-ip_item
                        users: &id004
                        - example-users_item
                        domain: api.example.com
                        alias: example-alias
                        first_seen: 568
                        last_seen: 191
                        content_version: 6.3.8
                        installation_package: example-installation_package
                        active_directory: example-active_directory
                        install_date: 551
                        endpoint_version: 4.5.5
                        is_isolated: PENDING_ISOLATION
                        isolation_reason: example-isolation_reason
                        scan_status: SCAN_STATUS_PENDING
                        group_name: &id005
                        - Production Gateway 60
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /endpoints/isolate:
    post:
      operationId: isolateEndpoints
      summary: Palo Alto Networks Isolate Endpoints
      description: >-
        Isolates one or more endpoints from the network, preventing all
        inbound and outbound communications except to the Cortex XDR service.
        Use endpoint IDs, IP addresses, or hostnames to identify targets.
      tags:
      - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  properties:
                    endpoint_id:
                      type: string
                      description: Single endpoint ID to isolate.
                    endpoint_id_list:
                      type: array
                      items:
                        type: string
                      description: List of endpoint IDs to isolate.
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                      description: Filter to select endpoints for isolation.
            examples:
              IsolateEndpointsRequestExample:
                summary: Default isolateEndpoints request
                x-microcks-default: true
                value:
                  request_data:
                    endpoint_id: '873939'
                    endpoint_id_list:
                    - '727469'
                    - '227456'
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
      responses:
        '200':
          description: Endpoint isolation initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      action_id:
                        type: string
                        description: Action ID to poll for completion status.
                      status:
                        type: integer
                      endpoints_count:
                        type: integer
              examples:
                IsolateEndpoints200Example:
                  summary: Default isolateEndpoints 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      action_id: '179327'
                      status: 199
                      endpoints_count: 392
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /endpoints/unisolate:
    post:
      operationId: unisolateEndpoints
      summary: Palo Alto Networks Unisolate Endpoints
      description: >-
        Removes network isolation from one or more endpoints, restoring full
        network connectivity. Use this endpoint after an investigation is
        complete and the threat has been remediated.
      tags:
      - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  properties:
                    endpoint_id:
                      type: string
                    endpoint_id_list:
                      type: array
                      items:
                        type: string
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
            examples:
              UnisolateEndpointsRequestExample:
                summary: Default unisolateEndpoints request
                x-microcks-default: true
                value:
                  request_data:
                    endpoint_id: '692398'
                    endpoint_id_list:
                    - '178680'
                    - '543834'
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
      responses:
        '200':
          description: Endpoint unisolation initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      action_id:
                        type: string
                      status:
                        type: integer
                      endpoints_count:
                        type: integer
              examples:
                UnisolateEndpoints200Example:
                  summary: Default unisolateEndpoints 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      action_id: '168979'
                      status: 596
                      endpoints_count: 930
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /endpoints/scan:
    post:
      operationId: scanEndpoints
      summary: Palo Alto Networks Scan Endpoints
      description: >-
        Initiates a malware scan on one or more endpoints. The scan runs the
        Cortex XDR agent's local analysis engine to detect and quarantine
        malicious files.
      tags:
      - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  properties:
                    endpoint_id_list:
                      type: array
                      items:
                        type: string
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
            examples:
              ScanEndpointsRequestExample:
                summary: Default scanEndpoints request
                x-microcks-default: true
                value:
                  request_data:
                    endpoint_id_list:
                    - '586813'
                    - '318804'
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
      responses:
        '200':
          description: Endpoint scan initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      action_id:
                        type: string
                      status:
                        type: integer
                      endpoints_count:
                        type: integer
              examples:
                ScanEndpoints200Example:
                  summary: Default scanEndpoints 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      action_id: '902089'
                      status: 779
                      endpoints_count: 286
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /scripts/run_script:
    post:
      operationId: runScript
      summary: Palo Alto Networks Execute Script on Endpoints
      description: >-
        Executes a script from the script library on one or more endpoints.
        Scripts can perform remediation actions, collect forensic data, or
        run custom commands. Returns an action ID for polling execution status.
      tags:
      - Scripts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - script_uid
                  properties:
                    script_uid:
                      type: string
                      description: Unique identifier of the script from the script library.
                    endpoint_ids:
                      type: array
                      items:
                        type: string
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    parameters_values:
                      type: object
                      description: Script parameter key-value pairs.
                      additionalProperties: true
                    timeout:
                      type: integer
                      description: Script execution timeout in seconds.
                      default: 600
            examples:
              RunScriptRequestExample:
                summary: Default runScript request
                x-microcks-default: true
                value:
                  request_data:
                    script_uid: '595817'
                    endpoint_ids:
                    - '221362'
                    - '707960'
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
                    - field: example-field
                      operator: lte
                      value: example-value
                    parameters_values: {}
                    timeout: 600
      responses:
        '200':
          description: Script execution initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      action_id:
                        type: string
                        description: Action ID to poll for script execution results.
              examples:
                RunScript200Example:
                  summary: Default runScript 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      action_id: '583622'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /scripts/get_script_execution_results:
    post:
      operationId: getScriptExecutionResults
      summary: Palo Alto Networks Get Script Execution Results
      description: >-
        Retrieves the execution results and output for a previously initiated
        script run identified by the action ID.
      tags:
      - Scripts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - action_id
                  properties:
                    action_id:
                      type: string
                      description: Action ID returned by the run_script endpoint.
            examples:
              GetScriptExecutionResultsRequestExample:
                summary: Default getScriptExecutionResults request
                x-microcks-default: true
                value:
                  request_data:
                    action_id: '766787'
      responses:
        '200':
          description: Script execution results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      action_id:
                        type: string
                      status:
                        type: string
                        enum:
                        - PENDING
                        - IN_PROGRESS
                        - COMPLETED_SUCCESSFULLY
                        - FAILED
                        - TIMEOUT
                        - CANCELED
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            endpoint_id:
                              type: string
                            endpoint_name:
                              type: string
                            endpoint_status:
                              type: string
                            domain:
                              type: string
                            ip_address:
                              type: string
                            is_isolated:
                              type: string
                            standard_output:
                              type: string
                            standard_error:
                              type: string
                            retrieved_files:
                              type: integer
                            return_value:
                              type: integer
              examples:
                GetScriptExecutionResults200Example:
                  summary: Default getScriptExecutionResults 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      action_id: '941630'
                      status: TIMEOUT
                      results:
                      - endpoint_id: '625820'
                        endpoint_name: Branch Sensor 63
                        endpoint_status: running
                        domain: portal.test-corp.net
                        ip_address: 10.32.174.246
                        is_isolated: example-is_isolated
                        standard_output: example-standard_output
                        standard_error: example-standard_error
                        retrieved_files: 667
                        return_value: 543
                      - endpoint_id: '670746'
                        endpoint_name: Production Gateway 55
                        endpoint_status: running
                        domain: mail.acme-systems.org
                        ip_address: 10.171.214.174
                        is_isolated: example-is_isolated
                        standard_output: example-standard_output
                        standard_error: example-standard_error
                        retrieved_files: 653
                        return_value: 89
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /xql/start_xql_query:
    post:
      operationId: startXqlQuery
      summary: Palo Alto Networks Execute XQL Query
      description: >-
        Initiates an XQL (Extended Query Language) query against the Cortex
        XDR data lake. XQL is a domain-specific language for querying endpoint,
        network, and cloud telemetry data. Returns a query ID for retrieving
        results asynchronously.
      tags:
      - XQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - query
                  properties:
                    query:
                      type: string
                      description: XQL query string to execute.
                    timeframe:
                      type: object
                      description: Time range for the query.
                      properties:
                        relativeTime:
                          type: string
                          description: Relative time range (e.g., last_24_hours, last_7_days).
                        startTime:
                          type: integer
                          description: Absolute start time as Unix epoch milliseconds.
                        endTime:
                          type: integer
                          description: Absolute end time as Unix epoch milliseconds.
                    max_results:
                      type: integer
                      description: Maximum number of results to return.
                      default: 1000
                      maximum: 10000
            examples:
              StartXqlQueryRequestExample:
                summary: Default startXqlQuery request
                x-microcks-default: true
                value:
                  request_data:
                    query: example-query
                    timeframe:
                      relativeTime: example-relativeTime
                      startTime: 1729966197370
                      endTime: 1717632192421
                    max_results: 1000
      responses:
        '200':
          description: XQL query initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: string
                    description: Query execution ID for retrieving results.
              examples:
                StartXqlQuery200Example:
                  summary: Default startXqlQuery 200 response
                  x-microcks-default: true
                  value:
                    reply: example-reply
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /xql/get_query_results:
    post:
      operationId: getXqlQueryResults
      summary: Palo Alto Networks Get XQL Query Results
      description: >-
        Retrieves the results of an XQL query previously initiated via the
        start_xql_query endpoint. Poll this endpoint until the status is
        SUCCESS or FAILED.
      tags:
      - XQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - query_id
                  properties:
                    query_id:
                      type: string
                      description: Query ID returned by start_xql_query.
                    pending_duration:
                      type: integer
                      description: Number of seconds to wait for query completion before returning.
                      default: 0
                    max_results:
                      type: integer
                      description: Maximum number of result rows to return.
                      default: 1000
                    format:
                      type: string
                      enum:
                      - json
                      - json_simple
            examples:
              GetXqlQueryResultsRequestExample:
                summary: Default getXqlQueryResults request
                x-microcks-default: true
                value:
                  request_data:
                    query_id: '629000'
                    pending_duration: 0
                    max_results: 1000
                    format: json_simple
      responses:
        '200':
          description: XQL query results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                        - PENDING
                        - SUCCESS
                        - FAILED
                        - CANCELED
                      number_of_results:
                        type: integer
                      query_cost:
                        type: object
                        additionalProperties:
                          type: number
                      remaining_quota:
                        type: number
                      results:
                        type: object
                        properties:
                          data:
                            type: array
                            items:
                              type: object
                              additionalProperties: true
              examples:
                GetXqlQueryResults200Example:
                  summary: Default getXqlQueryResults 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      status: FAILED
                      number_of_results: 884
                      query_cost: {}
                      remaining_quota: 53.19
                      results:
                        data:
                        - {}
                        - {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /audit/get_audit_management_logs:
    post:
      operationId: getAuditManagementLogs
      summary: Palo Alto Networks Get Audit Management Logs
      description: >-
        Retrieves audit management logs recording administrative actions
        performed in the Cortex XDR console. Includes user logins, policy
        changes, and configuration modifications.
      tags:
      - Audit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetAuditManagementLogsRequestExample:
                summary: Default getAuditManagementLogs request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
                    - field: example-field
                      operator: lte
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Audit management logs returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AuditLog'
              examples:
                GetAuditManagementLogs200Example:
                  summary: Default getAuditManagementLogs 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 974
                      result_count: 325
                      data:
                      - timestamp: 1725583298090
                        actor_primary_username: jsmith
                        actor_email: example-actor_email
                        actor_type: API
                        sub_type: custom
                        result: FAIL
                        reason: Incident investigation threat Security malware applied detected.
                        ip: 10.144.244.59
                        description: Firewall activity alert investigation alert on detected threat network.
                      - timestamp: 1725583298090
                        actor_primary_username: jsmith
                        actor_email: example-actor_email
                        actor_type: API
                        sub_type: custom
                        result: FAIL
                        reason: Incident investigation threat Security malware applied detected.
                        ip: 10.144.244.59
                        description: Firewall activity alert investigation alert on detected threat network.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    xdrAuth:
      type: apiKey
      in: header
      name: x-xdr-hmac-v2
      description: >-
        Cortex XDR uses a custom HMAC-SHA256 authentication scheme. Each
        request requires four headers: x-xdr-auth-id (API key ID), x-xdr-nonce
        (64-character random string), x-xdr-timestamp (Unix epoch milliseconds),
        and x-xdr-hmac-v2 (SHA-256 hash of apikey + nonce + timestamp). Generate
        API keys from Cortex XDR Settings > Configurations > API Keys.
  responses:
    BadRequest:
      description: Malformed request body or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid authentication headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions for the requested operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Filter:
      type: object
      description: A filter criterion for querying XDR resources.
      required:
      - field
      - operator
      - value
      properties:
        field:
          type: string
          description: Field name to filter on (e.g., incident_id, status, severity).
          example: example-field
        operator:
          type: string
          enum:
          - in
          - contains
          - gte
          - lte
          - eq
          - neq
          description: Comparison operator.
          example: lte
        value:
          description: >-
            Filter value. Use an array for the "in" operator, a string or
            integer for others.
          oneOf:
          - type: string
          - type: integer
          - type: array
            items:
              oneOf:
              - type: string
              - type: integer
          example: example-value
    SortOrder:
      type: object
      description: Sorting specification for result sets.
      properties:
        field:
          type: string
          description: Field to sort by.
          example: example-field
        keyword:
          type: string
          enum:
          - asc
          - desc
          description: Sort direction.
          example: asc
    Incident:
      type: object
      description: A Cortex XDR incident grouping related alerts.
      properties:
        incident_id:
          type: string
          example: '877543'
        incident_name:
          type: string
          example: Branch Gateway 82
        description:
          type: string
          example: Firewall traffic applied alert threat blocked Security rule.
        status:
          type: string
          enum:
          - new
          - under_investigation
          - resolved_threat_handled
          - resolved_known_issue
          - resolved_duplicate
          - resolved_false_positive
          - resolved_other
          example: resolved_threat_handled
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - informational
          - unknown
          example: informational
        assigned_user_mail:
          type: string
          example: analyst1@example.com
        assigned_user_pretty_name:
          type: string
          example: Carlos Smith
        alert_count:
          type: integer
          example: 509
        low_severity_alert_count:
          type: integer
          example: 929
        med_severity_alert_count:
          type: integer
          example: 295
        high_severity_alert_count:
          type: integer
          example: 602
        critical_severity_alert_count:
          type: integer
          example: 936
        user_count:
          type: integer
          example: 170
        host_count:
          type: integer
          example: 720
        creation_time:
          type: integer
          description: Incident creation timestamp as Unix epoch milliseconds.
          example: 1707012665747
        modification_time:
          type: integer
          description: Last modification timestamp as Unix epoch milliseconds.
          example: 1744706901976
        detection_time:
          type: integer
          example: 1704757310414
        starred:
          type: boolean
          example: true
        xdr_url:
          type: string
          description: Direct URL to the incident in the XDR console.
          example: https://portal.acme-systems.org/0455da
        rule_based_score:
          type: integer
          example: 942
        manual_score:
          type: integer
          example: 174
    IncidentDetail:
      allOf:
      - $ref: '#/components/schemas/Incident'
      - type: object
        properties:
          network_artifacts:
            type: object
          file_artifacts:
            type: object
          hosts:
            type: array
            items:
              type: string
          users:
            type: array
            items:
              type: string
          incident_sources:
            type: array
            items:
              type: string
          mitre_tactics_ids_and_names:
            type: array
            items:
              type: string
          mitre_techniques_ids_and_names:
            type: array
            items:
              type: string
    Alert:
      type: object
      description: A Cortex XDR alert representing a single detection event.
      properties:
        alert_id:
          type: string
          example: '999423'
        detection_timestamp:
          type: integer
          description: Detection timestamp as Unix epoch milliseconds.
          example: 1733555086833
        name:
          type: string
          description: Alert name or rule name that triggered this alert.
          example: Staging Policy 70
        category:
          type: string
          description: Alert category (e.g., Malware, Exploit, Lateral Movement).
          example: custom
        description:
          type: string
          example: Rule incident incident firewall suspicious monitoring activity threat rule monitoring suspicious detected.
        host_ip:
          type: array
          items:
            type: string
          example: *id001
        host_name:
          type: string
          example: Corporate Agent 14
        user_name:
          type: string
          example: jsmith
        mac:
          type: array
          items:
            type: string
          example: *id002
        source:
          type: string
          description: Data source that generated the alert.
          example: example-source
        action:
          type: string
          description: Action taken on the alert.
          example: alert
        action_pretty:
          type: string
          example: alert
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - informational
          - unknown
          example: informational
        matching_status:
          type: string
          example: running
        alert_type:
          type: string
          example: standard
        resolution_status:
          type: string
          example: enabled
        resolution_comment:
          type: string
          example: Monitoring threat applied Security investigation Security configured.
    Endpoint:
      type: object
      description: An endpoint enrolled in Cortex XDR protection.
      properties:
        endpoint_id:
          type: string
          description: Unique endpoint identifier.
          example: '472938'
        endpoint_name:
          type: string
          description: Endpoint hostname.
          example: Branch Sensor 33
        endpoint_type:
          type: string
          enum:
          - SERVER
          - WORKSTATION
          - LAPTOP
          example: WORKSTATION
        endpoint_status:
          type: string
          enum:
          - CONNECTED
          - DISCONNECTED
          - LOST
          - UNINSTALLED
          example: UNINSTALLED
        os_type:
          type: string
          enum:
          - AGENT_OS_WINDOWS
          - AGENT_OS_LINUX
          - AGENT_OS_MAC
          example: AGENT_OS_LINUX
        ip:
          type: array
          items:
            type: string
          description: IP addresses assigned to the endpoint.
          example: *id003
        users:
          type: array
          items:
            type: string
          description: Users logged into the endpoint.
          example: *id004
        domain:
          type: string
          example: api.example.com
        alias:
          type: string
          example: example-alias
        first_seen:
          type: integer
          description: First connection timestamp as Unix epoch milliseconds.
          example: 568
        last_seen:
          type: integer
          description: Last connection timestamp as Unix epoch milliseconds.
          example: 191
        content_version:
          type: string
          description: Cortex XDR agent content version.
          example: 6.3.8
        installation_package:
          type: string
          example: example-installation_package
        active_directory:
          type: string
          example: example-active_directory
        install_date:
          type: integer
          example: 551
        endpoint_version:
          type: string
          description: Cortex XDR agent version.
          example: 4.5.5
        is_isolated:
          type: string
          enum:
          - AGENT_ISOLATED
          - AGENT_UNISOLATED
          - PENDING_ISOLATION
          - PENDING_UNISOLATION
          example: PENDING_ISOLATION
        isolation_reason:
          type: string
          example: example-isolation_reason
        scan_status:
          type: string
          enum:
          - SCAN_STATUS_NONE
          - SCAN_STATUS_PENDING
          - SCAN_STATUS_IN_PROGRESS
          - SCAN_STATUS_DONE
          - SCAN_STATUS_FAILED
          - SCAN_STATUS_CANCELLED
          example: SCAN_STATUS_PENDING
        group_name:
          type: array
          items:
            type: string
          example: *id005
    AuditLog:
      type: object
      description: An audit management log entry recording an administrative action.
      properties:
        timestamp:
          type: integer
          description: Action timestamp as Unix epoch milliseconds.
          example: 1725583298090
        actor_primary_username:
          type: string
          description: Username of the administrator who performed the action.
          example: jsmith
        actor_email:
          type: string
          example: example-actor_email
        actor_type:
          type: string
          enum:
          - User
          - API
          example: API
        sub_type:
          type: string
          description: Action subtype (e.g., Login, Logout, Policy Update).
          example: custom
        result:
          type: string
          enum:
          - SUCCESS
          - FAIL
          example: FAIL
        reason:
          type: string
          description: Failure reason if result is FAIL.
          example: Incident investigation threat Security malware applied detected.
        ip:
          type: string
          description: Source IP address of the action.
          example: 10.144.244.59
        description:
          type: string
          example: Firewall activity alert investigation alert on detected threat network.
    ErrorResponse:
      type: object
      properties:
        reply:
          type: object
          properties:
            err_code:
              type: integer
              example: 782
            err_msg:
              type: string
              example: example-err_msg
            err_extra:
              type: string
              example: example-err_extra
          example:
            err_code: 270
            err_msg: example-err_msg
            err_extra: example-err_extra