Skip to main content

​
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 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.
All operations are read-only — Cymph never creates, modifies, enables, or disables a rule or playbook, and never runs a query.

​
Requirements

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.

​
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.
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.
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.

​
Permissions

The key inherits the role chosen when it is created. Cymph needs three permissions from that role, all read-only: 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.
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.
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.
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 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

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 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: When a preset reads correlation rules, two further messages can appear on the scope source:
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.

​
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 integration.