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

# Splunk Enterprise Security

> Read Splunk ES correlation searches and map their MITRE ATT&CK techniques.

## What Cymph uses it for

Cymph connects to Splunk Enterprise Security to read your **correlation searches** and collect the MITRE ATT\&CK techniques annotated 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.

All operations are **read-only** — Cymph never creates, modifies, or disables a search, and never runs one.

## Requirements

| Field            | Description                                                                                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Instance URL** | The address of the Splunk management API, e.g. `https://splunk.example.com:8089`. This is the **management** port (8089 by default), not Splunk Web (8000) |
| **Token**        | A Splunk authentication token                                                                                                                              |

<Info>
  The Splunk management API listens on port **8089** by default and is separate from Splunk Web (port 8000). Pointing the integration at Splunk Web will fail the connection test.
</Info>

## Token setup

Cymph authenticates with a **bearer token**, not a username and password. In Splunk Web, go to **Settings → Tokens** and create a token for the account Cymph should use.

Token authentication must be enabled on the instance first (**Settings → Tokens → Enable Token Authentication**).

<Tip>
  Create a dedicated Splunk account for Cymph rather than reusing an administrator's. It keeps the access read-only and makes the integration's activity easy to identify in your Splunk audit logs.
</Tip>

## Permissions

The token inherits the roles of the Splunk user it was issued for. Splunk authorisation has **two independent layers**, and read access needs both — granting capabilities alone is the most common reason a token authenticates but returns nothing:

1. **Role capabilities** — `rest_properties_get`, which permits reading configuration objects over the REST API.
2. **Object ACLs** — the role must appear in the **read** ACL of the correlation searches themselves. In Splunk Enterprise Security these are managed on the **ES Permissions** page; a custom role shows up there within about a minute of being created.

The simplest option that satisfies both is Enterprise Security's built-in read-only analyst role, **`ess_user`**, which already carries ES app access and read ACLs on correlation searches.

<Tip>
  Start with a dedicated user holding `ess_user`. If the connection test passes but no techniques come back, the gap is almost always layer 2 — the role is not in the read ACL for the correlation searches.
</Tip>

Cymph needs no write capability of any kind: not `edit_correlationsearches`, not `schedule_search`, and no ability to dispatch searches. It reads saved-search configuration only and never runs a search.

<Note>
  Splunk deployments vary considerably in how ES roles are customised. Treat `ess_user` as the recommended starting point rather than a guarantee, and validate against your own instance — your ES administrator may have altered the shipped roles' ACLs.
</Note>

## What Cymph reads

| Purpose                                               | Splunk REST call               |
| ----------------------------------------------------- | ------------------------------ |
| Test the connection                                   | `GET /services/server/info`    |
| Read correlation searches and their MITRE annotations | `GET /services/saved/searches` |

Cymph asks Splunk to do the filtering, so only the data it needs crosses the wire:

* `search=action.correlationsearch.enabled=1` — **only enabled correlation searches** are returned. Disabled ones are ignored and do not contribute to scope.
* `f=action.correlationsearch.annotations` — the response is restricted to the annotations field alone. Cymph does not read search queries, results, or any event data.

Results are read in pages of 100 until every matching search has been seen. Only searches carrying `mitre_attack` annotations contribute techniques; searches without them are read and ignored.

## Testing the connection

**Test Connection** calls the server-info endpoint and reports what it found:

| Message                                          | Meaning                                                                                                                |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Valid Splunk ES instance**                     | The token was accepted and the URL is a Splunk management API                                                          |
| **Authorization failed**                         | The instance was reached but rejected the token                                                                        |
| **Connection timed out**                         | No response within 5 seconds — check network reachability and any firewall or allowlist between Cymph and the instance |
| **Target does not seem to be a Splunk instance** | Something answered, but not a Splunk API — usually Splunk Web or the wrong port                                        |
| **Failed with response status *N***              | Splunk answered with another error status                                                                              |

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

## Limitations

Splunk ES is a detection source only — playbooks cannot be deployed to it, and it does not import assets.

If you want to deploy playbooks to Splunk, that is the separate [Splunk SOAR](/integrations/automation/splunk-soar) integration.