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

# Splunk

> Connect Serval to Splunk Cloud and Splunk Enterprise Security so workflows can pull findings into tickets, run searches for enrichment, and write results back.

## About Splunk

Splunk Cloud Platform is a log and event platform; Splunk Enterprise Security (ES) is the security app layered on top of it, where correlation searches produce **findings** — called **notable events** before ES 8. The Serval Splunk integration connects to your stack's management port with a Splunk authentication token so workflows can read findings, run searches, and update investigations. The integration is marked **Beta** in Serval's connect UI.

**Authentication:** Splunk authentication token (Bearer). Serval stores the token encrypted and sends it only to the host you configure.

**Data sync:** On demand only. There is no background sync or asset ingestion.

## What the Splunk integration enables

| Capability                      | Description                                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Enterprise Security API request | Typed access to the ES 8.x API — findings, investigations, notes, response plans, queues, risk scores, assets, and identities. |
| Platform API request            | Typed access to the Splunk platform API — dispatch and read search jobs, list saved searches, and read server info.            |

Reading findings is the path most teams start with: `GET /public/v2/findings` filters by time, urgency, status, owner, and correlation-search title, so a scheduled workflow can turn new findings into Serval tickets.

## Before you connect

Splunk Cloud does not expose its REST API by default. Two prerequisites, both handled by a Splunk admin.

<Steps>
  <Step title="Open the management port to Serval">
    The REST API listens on port 8089, and Splunk Cloud rejects traffic from any address that is not on the stack's search-api allow list. Add Serval's egress IPs using the Admin Config Service `search-api/ipallowlists` endpoint, or open a Splunk support case requesting REST API access for those addresses. Contact **[support@serval.com](mailto:support@serval.com)** for the current IP list.
  </Step>

  <Step title="Create a service account and token">
    In Splunk, create a dedicated user for Serval, give it a role with its own search quota, then generate a token under **Settings → Tokens**. A dedicated role keeps Serval's searches from competing with analyst searches on the same search head.
  </Step>
</Steps>

<Warning>
  Free trial Splunk Cloud accounts cannot access the REST API at all. The connection will fail regardless of credentials.
</Warning>

The role needs read access to findings.

## Connect in Serval

<Steps>
  <Step title="Open the Splunk connect form">
    In Serval, add the Splunk integration. It is labeled **Beta**.
  </Step>

  <Step title="Management Host (required)">
    Enter your search head and management port, with no `https://` and no trailing path — for example `acme.splunkcloud.com:8089`. The port is required; the Splunk REST API is never served on 443.
  </Step>

  <Step title="Authentication Token (required)">
    Paste the token you generated above.
  </Step>

  <Step title="Save and verify">
    Submit the form. Serval runs three health checks (below).
  </Step>
</Steps>

<Note>
  When editing an existing connection, leave the token field as its obfuscated placeholder to keep the stored token, or paste a new token to rotate.
</Note>

## Verifying the connection

Three health checks run after you connect:

1. **Get Server Info** — calls `/services/server/info` and reports the Splunk version. Failure here means the host, port, token, or IP allow list is wrong.
2. **Check Enterprise Security Version** — reads the ES app version and fails the connection below 8.0, since the findings API this integration reads does not exist on older releases.
3. **List Findings** — reads one finding through the ES 8.x findings API, the endpoint that ticket ingestion depends on.

<Tip>
  If **Get Server Info** fails but your token is definitely valid, suspect the allow list before the credential. Splunk Cloud refuses non-allowlisted addresses in a way that is easy to mistake for an authentication problem.
</Tip>

## Enterprise Security version requirement

This integration requires **Enterprise Security 8.0 or later**. ES 8.0 renamed notable events to *findings* and gave them a REST surface — `GET /public/v2/findings`, plus investigations and notes — and that is what Serval reads. ES 7 has no equivalent; notables could only be read by running a search, which is why older releases are not supported.

<Warning>
  Saying "notables" does not tell you which version a stack is on. The `notable` index and the `@@notable@@` event ID format both survive into ES 8, and the term stays in common use long after the rename. The **Check Enterprise Security Version** health check reads the real version at connect time, so an unsupported stack is caught there rather than by an ingestion workflow that quietly returns nothing.
</Warning>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Serval's searches consume your search concurrency">
    Search jobs dispatched by Serval run on the same search head your analysts use. Give the Serval service account its own role and quota, and prefer the findings API over a search whenever it can answer the question — it costs no search slots.
  </Accordion>

  <Accordion title="Findings pages cap at 100">
    `GET /public/v2/findings` returns at most 100 items per call. Page with `limit` and `offset` until a short page is returned, and use the `total` field to size the work.
  </Accordion>

  <Accordion title="Repeated findings can create duplicate tickets">
    A workflow that polls on a time watermark will see the same finding again across overlapping windows, and a re-fired correlation search reuses the same identity. Deduplicate on the finding's `event_id` before creating a ticket.
  </Accordion>

  <Accordion title="Customers who cannot allowlist Serval's IPs">
    Some organizations will not add a vendor's addresses to the search-api allow list. Those connections must egress from a self-hosted worker instead; contact **[support@serval.com](mailto:support@serval.com)** to set that up.
  </Accordion>

  <Accordion title="Searches are asynchronous">
    The platform search API dispatches a job and returns a search ID. Poll the job until it reports done, read its results with paging, then delete the job so its dispatch directory is cleaned up rather than left to Splunk's quota reaper.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Splunk integration.