.. _palo_alto_xsoar_integration:

Palo Alto XSOAR Integration
###########################

.. admonition:: About Palo Alto XSOAR Integration

    - TrackMe provides a native integration with Palo Alto Cortex XSOAR, allowing to easily track and monitor Palo Alto XSOAR alerts and incidents.
    - This integration provides REST API integration capabilities with Palo Alto Cortex XSOAR for comprehensive incident management and monitoring.

Overview
========

**TrackMe XSOAR Integration (TA-trackme-xsoar)** is a Splunk Technology Add-on that provides seamless integration between TrackMe and Palo Alto Cortex XSOAR. This integration enables:

- **REST API Integration**: Create one or more XSOAR accounts in TrackMe to interact on-demand with Cortex XSOAR
- **Authentication**: Based on XSOAR key and key ID as per the XSOAR API
- **Incident Management**: Create or update incidents in a streaming manner
- **Resilient Backend**: Automatically stores and reattempts failing REST API calls
- **Comprehensive Logging**: Consistent and easy access to different logs

Key Features
============

**Core Functionality:**

- **XSOAR Command**: Use the generating command `xsoar` to run GET/POST/DELETE REST calls to the XSOAR API
- **Streaming Incidents**: Use the streaming command `xsoarstreamincident` to create or update incidents in a streaming manner
- **Resilient Store**: Automatically stores and reattempts failing REST API calls for incident management
- **Incident Store**: Stores incidents and key information in KVstore for tracking and management

**Authentication & Security:**

- XSOAR key and key ID based authentication
- FIPS compatible
- Compatible with both standalone instances and Search Head Cluster (SHC) deployments

Installation
============

**Installation Requirements:**

- No dependencies required
- Developed on top of the Splunk UCC framework
- Compatible with all supported versions of Splunk
- Compatible with both standalone instances and Search Head Cluster (SHC) deployments
- FIPS compatible

**Installation Steps:**

1. Download the application from the official download page
2. Install as usual in Splunk
3. Restart Splunk after the initial installation
4. Configure XSOAR accounts in the application

**Download:**

- **Official Download Page**: `https://downloads.trackme-solutions.com/TA-trackme-xsoar/`
- **GitHub Repository**: `https://github.com/trackme-limited/TA-trackme-xsoar`

Usage
=====

**XSOAR Command Usage:**

The `xsoar` command provides REST API access to XSOAR:

.. code-block::

    | xsoar account="xsoar" method="GET" endpoint="/incident"

**Streaming Incident Command:**

The `xsoarstreamincident` command creates or updates incidents:

.. code-block::

    | eval incident_name="TrackMe entity alert", incident_details="Entity status changed", incident_severity=2
    | xsoarstreamincident account="xsoar" incident_details="$incident_details$" incident_name="$incident_name$" incident_severity=2 incident_type="unclassified"

**Active Commands for TrackMe Integration:**

**For opened incidents:**

.. code-block::

    | eval incident_name="The TrackMe entity " . alias . " has received an incident", incident_details="The TrackMe entity " . alias . " has received an incident: " . object_state . ", detection_time: " . detection_time . ", messages: " . mvjoin(messages, "|") 
    | xsoarstreamincident account="xsoar" incident_details="$incident_details$" incident_name="$incident_name$" incident_severity=2 incident_type="unclassified" external_incident_id="$incident_id$"

**For closed incidents:**

.. code-block::

    | eval incident_name="The TrackMe entity " . alias . " has received an incident closure", incident_details="The TrackMe entity " . alias . " has received an incident closure update and is now in a non-alerting state: " . object_state . ", detection_time: " . detection_time . ", messages: " . mvjoin(messages, "|"), incident_reason="The TrackMe entity has returned to a non alerting state" 
    | xsoarstreamincident account="xsoar" incident_details="$incident_details$" incident_name="$incident_name$" incident_severity=2 incident_type="unclassified" incident_reason="$incident_reason$" incident_closeNotes="$incident_details$" external_incident_id="$incident_id$"

Command Parameters
==================

**xsoarstreamincident Command Parameters:**

The following arguments are available for the `xsoarstreamincident` command:

- **external_incident_id**: The external incident ID for lookup and update
- **incident_closeNotes**: Notes for closing the incident
- **incident_closeReason**: Reason for closing the incident
- **incident_closed**: The date the incident was closed
- **incident_createInvestigation**: Whether to create an investigation for the incident
- **incident_customFields**: Custom fields for the incident, as a JSON string
- **incident_details**: The details of the incident
- **incident_labels**: Labels for the incident, as a JSON string
- **incident_modified**: The date the incident was last modified
- **incident_name**: The name of the incident
- **incident_playbookId**: The ID of the playbook to run for the incident
- **incident_rawJSON**: The raw JSON of the incident
- **incident_reason**: The reason for the incident
- **incident_severity**: The severity of the incident (number)
- **incident_sla**: The SLA for the incident (number)
- **incident_status**: The status of the incident (number)
- **incident_type**: The type of the incident

Data Storage
============

**Incident Store:**

The application stores incidents and their key information in the following KVstore collection:

- **KVstore name**: kv_xsoar_incidents_store
- **KVstore transforms name**: xsoar_incidents_store

**Access the KVstore content:**

.. code-block::

    | inputlookup xsoar_incidents_store | eval keyid=_key
    | eval _time=mtime
    | sort - 0 _time

**Resilient Store:**

The application stores failing calls in a Splunk KVstore for automated reattempt purposes:

- **KVstore name**: kv_xsoar_resilient_store
- **KVstore transforms name**: xsoar_resilient_store

**Access the resilient store content:**

.. code-block::

    | inputlookup xsoar_resilient_store | eval keyid=_key
    | eval _time=ctime
    | sort - 0 _time

**Resilient Store Configuration:**

- Enable or disable resilient store functionalities (default is enabled)
- Define maximum number of attempts for a given REST call
- Automated reattempts using the command `xsoarresilient`
- Orchestrated by the saved search: xsoarresilient (scheduled by default)

Troubleshooting
===============

**Log Access:**

The application provides comprehensive logging for troubleshooting:

**Application internal REST API:**
.. code-block::

    index=_internal sourcetype=xsoar:rest_api

**Command xsoar:**
.. code-block::

    index=_internal sourcetype=xsoar:custom_commands:xsoar

**Command xsoarstreamincident:**
.. code-block::

    index=_internal sourcetype=xsoar:custom_commands:xsoarstreamincident

**Command xsoarresilient:**
.. code-block::

    index=_internal sourcetype=xsoar:custom_commands:xsoarresilient

**Audit & Troubleshoot Menu:**

The application provides an "Audit && Troubleshoot" menu with shortcuts to internal log events. Use the extracted field `log_level` to filter on certain types of log events such as `error`.

**Resilient Store Behaviors:**

- When a reattempt is needed and processed successfully, the information is logged and the KVstore record is permanently deleted
- When a transaction ID record reaches the maximum number of attempts, the information is logged and the KVstore record is permanently deleted

**Resilient Store Limitations:**

- Updates or closures require first the response from XSOAR to know the incident id
- Updates or closures cannot be re-attempted if the initial incident opening call has not been successful
- The resilient store can re-attempt an update of an incident only if the incident could be opened successfully first

Documentation References
========================

**Official Documentation:**

- **Cortex SOAR REST API Documentation**: `https://docs-cortex.paloaltonetworks.com/r/Cortex-XSOAR-8-API`
- **Create or Update Incident API**: `https://docs-cortex.paloaltonetworks.com/r/Cortex-XSOAR-8-API/Create-or-update-an-incident`

**Resources:**

- **GitHub Repository**: `https://github.com/trackme-limited/TA-trackme-xsoar`
- **Download Page**: `https://downloads.trackme-solutions.com/TA-trackme-xsoar/`

**Related TrackMe Documentation:**

- :ref:`trackme_admin_alerts` - For information about TrackMe alerting capabilities