Skip to main content

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 for the detection-based scope option. All operations are read-only — Cymph never creates, modifies, or disables a search, and never runs one.

Requirements

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.

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

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

What Cymph reads

Cymph asks Splunk to do the filtering, so only the data it needs crosses the wire:
  • search=action.correlationsearch.enabled=1 disabled=0 — only correlation searches that are switched on are returned. action.correlationsearch.enabled marks a saved search as a correlation search; whether it actually runs is the separate disabled flag, and both are checked. A stock Enterprise Security install ships most of its content switched off, and none of that contributes to scope.
  • f=action.correlationsearch.annotations and f=disabled — the response is restricted to the annotations field and the disabled flag. Cymph does not read search queries, results, or any event data. The saved search name is always part of a REST entry and is kept so that validation issues can point at the search they came from.
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. Cymph re-checks the disabled flag on every entry it receives, so a search that is switched off is skipped even if the server-side filter were ignored. The schedule state (is_scheduled) is not considered: an enabled correlation search contributes its techniques whether or not its schedule is on. Splunk’s own ATT&CK coverage queries filter on both flags, so a count taken from such a query can be lower than what Cymph imports when a search is enabled but unscheduled.

How annotations are read

Each correlation search’s action.correlationsearch.annotations field is parsed as JSON and its mitre_attack array is read. The following rules apply:
  • Trimming. Leading and trailing whitespace, including tabs, is removed from each technique ID before validation. No other normalisation is applied: a lower-case t, a full-width T or a zero-width character makes an ID unknown, and it is reported as such.
  • Tactic IDs. Tactic IDs (TA0001 and so on) found in mitre_attack are ignored and not reported. With Expand tactics to their individual techniques on, each tactic adds its parent techniques only.
  • Other framework keys. Keys other than mitre_attack (kill_chain_phases, nist, cis20 and so on) are not read.
  • Annotations that cannot be parsed. A search whose annotations field is empty, is not valid JSON, is not a JSON object, or has no mitre_attack array contributes nothing and is not reported. To list such searches on the Splunk side, run the SPL below on the search head.
  • Rule names in issues. Each validation issue lists the correlation searches that carry the ID, up to 25 per ID. A value found in several searches appears once, with all of them.
The import summary counts every technique ID the searches contribute, sub-techniques included. Define Scope and the preset page count parent techniques, so a sub-technique and its parent count once there. See Two counts for one scope.

Stale technique IDs in shipped content

Splunk’s own content (the Enterprise Security built-in apps and ESCU) annotates a handful of detections with ATT&CK IDs that MITRE revoked or deprecated years ago, such as T1075 on Access - Cleartext Password At Rest. These IDs exist in no ATT&CK version Cymph ships, so they fail validation whichever framework version the preset uses, and a content update will put them back if you edit them locally. Each such ID is reported as an issue that names the correlation searches it was found in and suggests a remediation. To import the remaining techniques, switch on Ignore techniques not found in the framework on the detection-source step; the skipped IDs stay listed in the import summary. See Configure live source.

Presets saved before a content update

A preset built from a live source re-reads Splunk every time it is opened, with the switch setting that was saved on it. If the switch is off and a later ESCU or ES content update adds an unknown ID to an enabled search, the preset still opens: its page shows an empty scope, zero coverage, and a banner that names the ID and the correlation searches it was found in. Open Edit Preset, enable the switch, and save, or correct the ID in Splunk. The same banner, without the switch hint, appears when Splunk cannot be reached; the scope is read again on the next open. See When a live scope cannot be resolved.

Testing the connection

Test Connection calls the server-info endpoint and reports what it found:
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.

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