# Splunk SIEM Integration

Push Capsule detections, findings, and policy violations straight into Splunk over HTTP Event Collector (HEC), already sourcetyped, so your SOC triages AI-agent and shadow-AI signals next to the rest of its telemetry.

## Overview

Capsule sends each event to your HEC endpoint as it is produced. There is no bucket to poll, no SQS plumbing, and no AWS add-on.

| Event type | What gets exported |
|  --- | --- |
| **Detections** | Real-time detections raised on agent activity, with full event context |
| **Findings** | Posture and configuration findings across your AI inventory |
| **Policy violations** | Guardrail and policy breaches, with the full evidence the decision was made on |


```
Capsule event (detection / finding / policy violation)
  → POST to your HEC endpoint, gzipped, as capsule:<type>
  → searchable in your index
  → (optional) the Capsule Technology Add-on maps it to CIM
  → Enterprise Security sees it through the Alerts and Intrusion Detection data models
```

> This is separate from **Settings → Notifications**. Notifications push individual alerts to a channel; the SIEM integration streams the full, verbose event record for ingestion and long-term correlation.


You can also reach Splunk through Capsule's Amazon S3 destination, but only via the Splunk Add-on for AWS and the SQS notification plumbing it expects. HEC is the supported path.

## Prerequisites

- A **Capsule** account with admin access, and the **SIEM** tab visible under **Settings**
- **Splunk Cloud** or **Splunk Enterprise** with HTTP Event Collector enabled. On Splunk Cloud, HEC is on by default
- Permission in Splunk to create a HEC token, and to install an add-on if you want CIM normalisation


## Step 1: Create a HEC token in Splunk

1. In Splunk, go to **Settings → Add Data**, choose **Monitor**, and pick **HTTP Event Collector**.
2. Give the token a **Name**, for example `capsule`, and click **Next**.
3. On **Input Settings**, leave **Source type** as **Automatic** - Capsule sets the sourcetype on every event.
4. Still on **Input Settings**, choose the index Capsule should write to and make sure that index is in **Select Allowed Indexes**. An event naming an index outside that list is rejected with `HTTP 400, code 7`.
5. Click **Review**, then **Submit**.
6. Copy the **token value** Splunk shows, and note your HEC endpoint:
  - Splunk Cloud: `https://http-inputs-<your-stack>.splunkcloud.com`
  - Splunk Enterprise: `https://<splunk-host>:8088`


> The token is shown once on this screen. To find it again later, go to **Settings → Data inputs → HTTP Event Collector**.


> **Indexer acknowledgement must stay off.** Splunk Cloud does not support it for HEC except through AWS Kinesis Firehose, and Capsule does not use it. Delivery is at-least-once with client-side retry.


## Step 2: Create the SIEM integration in Capsule

1. In Capsule, go to **Settings → SIEM** and click **Add integration**.
2. Set **Destination** to **Splunk (HEC)**.
3. Enable the event types you want: **Detections**, **Findings**, **Policy violations**.
4. Choose an **Event detail** level:
  - **Full** sends the whole envelope, matching the S3 export byte for byte.
  - **Compact** omits activity message bodies. Splunk bills by ingested volume and those bodies dominate an event's size, so use Compact if the transcript is not what you search on.
5. Paste the **HEC URL** and **HEC token** from Step 1. The token is stored encrypted and never shown again.
6. Optionally set an **Index**. Leave it blank to use the token's default index.
7. Leave **Sourcetype prefix** blank unless you have a naming standard - the Technology Add-on expects `capsule`.
8. Click **Save**, then **enable** the integration. A new integration starts disabled and exports nothing until you turn it on.


> Use the row menu's **Send test event** to confirm the endpoint, token, and index before you rely on it. The **Delivery** column on the SIEM list shows the outcome of the most recent attempt, and the details drawer shows the last error in full.


## Step 3 (optional): Install the Capsule Technology Add-on

Events are searchable in your index as soon as Step 2 is done. The add-on is only needed for CIM normalisation, so skip this step if you search the raw JSON directly or normalise it yourself.

Install it if you run **Enterprise Security**. ES detections run `tstats` over accelerated data models with `summariesonly=true`, which returns nothing for data that is not CIM-mapped, so without the add-on ES stays blind to Capsule events.

1. Install **Capsule Security Add-on (TA-capsule)** from Splunkbase onto your search heads. Also install it on indexers or heavy forwarders if you route these events through one.
2. Add the index your HEC token writes to, to the **index allow-list of every CIM data model** you expect Capsule events in: **Splunk_SA_CIM → Settings → Data Model Indexes**.


> **Do not skip the allow-list.** An index missing from it never enters the accelerated summary, and every ES detection over that model silently misses Capsule events. Nothing errors.


Confirm the events are landing and normalised:

```
| tstats summariesonly=false count from datamodel=Alerts where nodename=Alerts source="capsule:siem-export" by sourcetype
```

## What arrives in Splunk

### Sourcetypes

| Sourcetype | Event |
|  --- | --- |
| `capsule:detection` | A detection raised on AI agent activity |
| `capsule:finding` | A posture or configuration finding on an AI resource |
| `capsule:policy_violation` | A policy violation with the evidence behind it |


Every event is sent with `source=capsule:siem-export` and `host=capsule`.

### Event envelope

Each event carries the same envelope, with the record under `event`:

```json
{ "schemaVersion": 2, "eventType": "policy_violation.created", "tenantId": "...", "exportedAt": "...", "event": { ... } }
```

This is the same envelope the S3 destination writes, so a tenant exporting to both sees identical content.

Every event carries its anchor resource in full - id, name, type, external id, parent, and the environment and connector it was discovered through - so events correlate against the rest of your inventory without a lookup.

- **`policy_violation.created`** is self-contained: the violation, the policy that raised it including its conditions, and the complete finding, detection and activity records the decision was made on.
- **`detection.created`** carries the detection, its evidence, and the session activities it was raised on.
- **`finding.created`** carries the finding, its evidence, and its remediation steps.


Triage state is exported on all three. Secrets Capsule identified in evidence are masked to a short prefix before export, in evidence text and activity message bodies alike.

> **One violation, one event.** A violation is exported once, when it is first raised. If it is later resolved and the same condition re-triggers, Capsule reuses the existing violation and does not emit a second `policy_violation.created`.


### CIM mapping

The add-on populates **Alerts** from all three sourcetypes, and additionally **Intrusion Detection** from `capsule:detection`.

No other data model is claimed. CIM has no AI or agent model, and Capsule does not carry the fields Web, Authentication or Change require - a partial mapping returns misleading results under `summariesonly=true`.

Capsule does not rank detections or findings, so those arrive with `severity="unknown"`. Policy violations carry Capsule's own severity, which already uses the CIM vocabulary (`low`, `medium`, `high`, `critical`).

## Delivery behaviour

- **Batching** - events are gzipped and split to stay under Splunk Cloud's 1 MB HEC request limit. Splunk Enterprise defaults far higher; Capsule holds both to the Cloud limit.
- **Oversized events** - a single event that still exceeds the limit after compression is rejected and surfaced on the integration, never truncated. Switching **Event detail** to Compact is the fix.
- **Retries** - Capsule retries on `429`, `5xx`, and network errors with exponential backoff, honouring `Retry-After`. A rejected token or a disallowed index is not retried - it is a configuration error and is reported instead.
- **Visibility** - the outcome of the most recent attempt is shown per integration in **Settings → SIEM**, with the full error in the details drawer.
- **Backfill** - export begins when the integration is enabled. Events raised before that are not sent.


## Troubleshooting

### `Splunk rejected the index` (HTTP 400, code 7)

The index you configured is not on the HEC token's allowed-index list. Add it in Splunk under **Settings → Data inputs → HTTP Event Collector**, edit the token, or clear the **Index** field in Capsule to use the token's default.

### `Splunk rejected the HEC token` (HTTP 401 or 403)

The token is wrong, disabled, or was regenerated in Splunk. Paste the current value into the integration and save - leaving the field blank keeps the old token.

### Events are in the index but Enterprise Security sees nothing

Almost always the CIM index allow-list. Confirm the index is listed for the Alerts and Intrusion Detection data models in **Splunk_SA_CIM → Settings → Data Model Indexes**, then rebuild acceleration.

If the allow-list is right, check the sourcetype: a custom **Sourcetype prefix** in Capsule needs a matching `local/props.conf` override in the add-on.

### Nothing arrives at all

- Confirm the integration is **enabled** and at least one event type is turned on.
- Use **Send test event** - it reports the exact error from Splunk.
- If your Splunk Cloud stack has an IP allow-list configured, Capsule's egress addresses need to be on it. Contact support for the current list.


## Support

For help with this integration, contact [support@capsule.security](mailto:support@capsule.security).