> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cymph.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cortex XSIAM

> Read Cortex XSIAM correlation rules and map their MITRE ATT&CK techniques.

## What Cymph uses it for

Cymph connects to Palo Alto Networks Cortex XSIAM for two things:

* **Detection scope** — it reads your **correlation rules** and collects the MITRE ATT\&CK techniques mapped on each one, so a preset's scope can be derived from what you actually detect. See [Manage presets](/how-tos/create-and-manage-presets) for the detection-based scope option.
* **Playbook import** — it lists the **playbooks** on the tenant and converts the ones you pick into Cymph playbooks. See [Import playbooks](/howto/import_playbook).

All operations are **read-only** — Cymph never creates, modifies, enables, or disables a rule or playbook, and never runs a query.

## Requirements

| Field          | Description                                                                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Base URL**   | The tenant's **API host**, e.g. `https://api-mytenant.xdr.eu.paloaltonetworks.com`. This is the console FQDN with an `api-` prefix, not the console address itself |
| **API Key**    | A **Standard** API key                                                                                                                                             |
| **API Key ID** | The numeric ID shown next to the key in the console                                                                                                                |

<Info>
  Cortex XSIAM serves its public API on a dedicated host: take your console address and prefix the hostname with `api-`. Pointing the integration at the console host itself will fail the connection test.
</Info>

## API key setup

In the Cortex XSIAM console, go to **Settings → Configurations → Integrations → API Keys** and create a new key. Choose the **Standard** security level. Copy the key when it is shown — it cannot be displayed again — and note the **ID** column of the new row, which is the API Key ID.

Cymph sends the key as the `Authorization` header and the ID as `x-xdr-auth-id` on every request, which is why both are required and both are stored encrypted.

<Note>
  **Advanced** keys are not supported. They require a per-request nonce and timestamp signature that Cymph does not implement. Create the key with the **Standard** level.
</Note>

<Tip>
  Create a dedicated key for Cymph rather than reusing one issued to a person or another tool. It keeps the key's role scoped to what Cymph needs and makes the integration's activity easy to identify in the Cortex audit log.
</Tip>

## Permissions

The key inherits the **role** chosen when it is created. Cymph needs three permissions from that role, all read-only:

| What Cymph does           | Permission in the role editor                                    | Used by                      |
| ------------------------- | ---------------------------------------------------------------- | ---------------------------- |
| Read one incident         | **Incidents & Alerts → Incidents**, level *View*                 | The connection test          |
| Read correlation rules    | **Detections & Threat Intel → Detections → Rules**, level *View* | Preset scope from detections |
| Search and read playbooks | **Automation → Playbooks**, level *View*                         | Playbook import              |

Everything else can stay at *None*. Cymph never runs a playbook or a query, never changes a rule, and does not read alerts, endpoints, or event data.

<Note>
  Component labels differ slightly between Cortex XSIAM console versions. Look for the Incidents, Rules, and Playbooks entries in **Settings → Configurations → Access Management → Roles** and grant *View* on each.
</Note>

<Warning>
  **The correlation rules API is the exception.** Palo Alto Networks documents it as needing the Rules permission, but tenants consistently report that a custom role is refused with *403 — insufficient permissions for api key* even with Rules set to View/Edit, and that only the built-in **Instance Administrator** (or **Account Admin**) role is accepted. A feature request for granular access (CXDR-I-2505) is open. Start with the least-privilege role above; if reading rules fails with the permission error, re-issue the key with **Instance Administrator** as its role.
</Warning>

The connection test only reads incidents, so a key with a lesser role can test green and still fail later when a preset reads correlation rules or an import lists playbooks. In both cases the error names the missing permission — see [Testing the connection](#testing-the-connection) below.

On some tenants the correlation rules API is switched off server-side and returns *not found* even for an administrator. If a key with Instance Administrator still cannot read rules, ask Palo Alto Networks support to enable the endpoint for your tenant.

## What Cymph reads

| Purpose                                         | Cortex XSIAM API call                                        |
| ----------------------------------------------- | ------------------------------------------------------------ |
| Test the connection                             | `POST /public_api/v1/incidents/get_incidents` (one incident) |
| Read correlation rules and their MITRE mappings | `POST /public_api/v1/correlations/get`                       |
| List playbooks                                  | `POST /xsoar/public/v1/playbook/search`                      |
| Fetch a playbook to import                      | `GET /xsoar/public/v1/playbook/{id}`                         |

Rules are read in windows of 100 until every rule has been seen. For each rule Cymph looks at two fields only:

* `is_enabled` — **only enabled rules contribute to scope**. Rules reported as `DISABLED` are read and ignored.
* `mitre_defs` — the rule's ATT\&CK mapping, keyed by tactic with the techniques listed as `T1070.001 - Clear Windows Event Logs` style strings. Cymph keeps the technique or sub-technique ID and discards the name.

Cymph does not read rule queries (XQL), alerts, incidents beyond the single one used by the connection test, or any event data.

### Playbook import

Cortex XSIAM runs the same automation engine as Cortex XSOAR 8 and serves its playbook API under the XSOAR-compatible `/xsoar/public/v1` paths on the same `api-` host. Cymph therefore converts XSIAM playbooks with the **Cortex XSOAR converter** — the mapping of tasks, conditions, and embedded playbooks is identical to a [Cortex XSOAR](/integrations/automation/cortex-xsoar) import, and the same YAML files can also be uploaded directly.

If a playbook carries **MITRE ATT\&CK technique IDs as tags** (for example `T1566` or `T1566.001`), Cymph recognises them during conversion and records them as the playbook's ATT\&CK for Enterprise mappings, so the imported playbook is scoped without any manual tagging. Tags that are not valid technique IDs are kept as ordinary labels.

## Testing the connection

**Test Connection** asks for a single incident and reports what it found:

| Message                                                | Meaning                                                                                                              |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **Valid Cortex XSIAM instance**                        | The key and key ID were accepted and the URL is a Cortex XSIAM API host                                              |
| **Authorization failed**                               | The tenant was reached but rejected the key or key ID                                                                |
| **API key role lacks permission to view incidents**    | The credentials are right, but the key's role cannot read incidents — change the role rather than the key            |
| **Connection timed out**                               | No response within 5 seconds — check network reachability and any firewall or allowlist between Cymph and the tenant |
| **Target does not seem to be a Cortex XSIAM instance** | Something answered, but not the Cortex API — usually the console host instead of the `api-` host                     |
| **Failed with response status *N***                    | The tenant answered with another error status                                                                        |

When a preset reads correlation rules, two further messages can appear on the scope source:

| Message                                                                                                                | Meaning                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API key role lacks permission to read correlation rules (grant Rules view, or use the Instance Administrator role)** | The key works but its role cannot read rules — see [Permissions](#permissions); in practice this usually means re-issuing the key with Instance Administrator |
| **Correlation rules API not found on target**                                                                          | Either the Base URL is wrong, or the endpoint is disabled on this tenant — see [Permissions](#permissions)                                                    |
| **Unable to get playbooks** / **Unable to get playbook** (on import)                                                   | The playbook API refused or did not answer — usually the role lacks Playbooks *View*, or the Base URL is the console host rather than the `api-` host         |

<Note>
  Every request Cymph makes to Cortex XSIAM times out after 5 seconds. If Cymph reaches your tenant through a source-IP allowlist, confirm the egress addresses are permitted — see [Networking](/deployment/networking#egress-control).
</Note>

## Limitations

Cortex XSIAM is a **read-only** integration — Cymph imports playbooks from it and reads its correlation rules, but playbooks cannot be deployed to it, and it does not import assets.

If you want to deploy playbooks to the Cortex platform, that is the separate [Cortex XSOAR](/integrations/automation/cortex-xsoar) integration.