# Hunters SIEM Integration

Stream Capsule detections, findings, and policy violations into [Hunters](https://www.hunters.ai/) so your SOC can triage AI-agent and shadow-AI signals alongside the rest of your security telemetry.

## Overview

Capsule continuously exports security events to a **dedicated Amazon S3 bucket that Capsule provisions and manages** for each integration. Hunters ingests directly from that bucket by assuming a read-only IAM role, scoped with the **External ID** Hunters gives you.

| 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, including the offending request or response |


Events are written verbosely as newline-delimited JSON (NDJSON) as they are produced, so Hunters receives the same detail Capsule holds internally.


```
Capsule event (detection / finding / policy violation)
  → written to Capsule-managed S3 bucket (one per integration)
  → Hunters assumes the read-only role (External ID enforced)
  → Hunters ingests the objects
```

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


### How this differs from Hunters' standard setup

Hunters' [Set up bucket access](https://docs.hunters.ai/docs/step-3-set-up-bucket-access-1#IAMrole) guide, under **"Create a new IAM role for Hunters manually"**, normally asks you to create the S3 bucket and the IAM role yourself in your own AWS account.

**With Capsule you don't do any of that.** Capsule owns the bucket and creates the read role for you. Your only job is to copy the **Principal ARN** and **External ID** that Hunters shows you into Capsule — Capsule provisions everything else and hands you back the connection details to finish the Hunters side.

## Prerequisites

Before you begin, ensure you have:

- A **Capsule** account with admin access, and the **SIEM** tab visible under **Settings**
- A **Hunters** account with permission to add an AWS S3 data source (**Data > Connect Data Source**)


## Step 1: Get the Principal ARN and External ID from Hunters

In Hunters, begin the bucket-access setup and choose **Create a new IAM role for Hunters manually** (see the [Hunters guide](https://docs.hunters.ai/docs/step-3-set-up-bucket-access-1#IAMrole)).

1. Locate the **Principal ARN** — Hunters' AWS identity, e.g. `arn:aws:iam::685648138888:root`.
2. Locate the **External ID** — a unique value Hunters generates for this connection.
3. Keep both values handy. Leave the Hunters tab open; you'll return to it in Step 3.


> **Stop after copying these two values.** Do **not** follow Hunters' AWS instructions to create the bucket, the `HuntersBucketAccess` policy, or the `hunters-assume-role` role. Capsule performs all of that for you in the next step.


## Step 2: Create the SIEM integration in Capsule

1. In Capsule, go to **Settings → SIEM** and click **Add integration**.
2. **Destination** is fixed to **Amazon S3** — this is the bucket Hunters will read from.
3. Enable the event types you want Hunters to receive: **Detections**, **Findings**, and **Policy violations**.
4. Paste the **Principal ARN** from Step 1 into the **Principal ARN** field.
5. Paste the **External ID** from Step 1 into the **External ID** field. An External ID is required whenever a Principal ARN is set — this is what protects the role against confused-deputy access.
6. Click **Save**.


On save, Capsule provisions a **dedicated S3 bucket** for this integration and a **read-only IAM role** whose trust policy allows the Hunters Principal ARN to assume it, but only when the request carries your External ID.

> You can create more than one SIEM integration — each gets its own isolated bucket and role, so different Hunters environments or event scopes never share a destination.


## Step 3: Copy the connection details back to Hunters

1. In the SIEM list, open the integration's row menu and choose **View details**.
2. Under **Connection details**, copy the values Capsule generated:
  - **Bucket name** — the S3 bucket Hunters ingests from
  - **Region** — the AWS region the bucket lives in
  - **Read role ARN** — the role Hunters assumes to read the bucket
3. Return to the Hunters tab and provide these values where Hunters asks for the bucket and the role it should assume, then run Hunters' connection validation to finish.


> **Connection details will appear once the bucket is provisioned.** If the section shows a pending hint, give provisioning a moment and reopen the drawer.


## Data format and retention

- **Layout** — objects are keyed by event type and date: `<event-type>/YYYY/MM/DD/<timestamp>-<id>.ndjson`.
- **Format** — each object is NDJSON: one JSON event per line, with the full verbose record.
- **Retention** — objects expire automatically **30 days** after they are written. Configure Hunters to ingest continuously so nothing is missed before expiry.


### Ingestion prefixes

Every object lives under one of three top-level prefixes — these are the only keys at the bucket root:


```
detections/
findings/
policy-violations/
```

Hunters asks for a **Prefix** here (it rejects the setup with `must have required property 'Prefix(es)'` until you provide one). The field is **not** a free-form regex — it's a comma-separated list of path templates. Each entry may contain literal segments (`[\w\-.]`), `/` separators, `*` wildcards, and the date placeholders `{YYYY}` `{MM}` `{DD}` `{HH}` `{mm}`. Use no leading slash, no spaces, and no trailing comma.

Because Capsule partitions objects by date, point the placeholders at that layout so Hunters lists new partitions efficiently:


```
detections/{YYYY}/{MM}/{DD}/,findings/{YYYY}/{MM}/{DD}/,policy-violations/{YYYY}/{MM}/{DD}/
```

If you don't need date partitioning, the plain literal prefixes also validate:


```
detections/,findings/,policy-violations/
```

Drop any event types you didn't enable from the list.

## How access is scoped

- The bucket and role live in **Capsule's managed AWS account**, not yours — there is nothing to maintain on your side.
- The read role grants only `s3:ListBucket`, `s3:GetBucketLocation`, and `s3:GetObject`, and only on that one integration's bucket.
- The trust policy requires **both** the Hunters Principal ARN **and** the matching External ID, so no other party can assume the role even if the ARN is known.


## Troubleshooting

### Connection details never appear

- Confirm the integration is **enabled** and has at least one event type turned on.
- Reopen the details drawer after a short wait — the bucket and role are provisioned on save.


### Hunters can't read the bucket

- Verify the **External ID** in Capsule matches exactly what Hunters displays — a mismatch blocks the role assumption.
- Verify the **Principal ARN** you pasted is the one from Hunters (no trailing spaces or truncation).
- Confirm Hunters is configured with the **Read role ARN** and **Bucket name** exactly as shown in the Capsule details drawer.


### No events arriving

- Confirm the relevant event types (**Detections**, **Findings**, **Policy violations**) are enabled on the integration.
- New events flow only after the integration is created — historical events are not backfilled.
- Remember objects expire after 30 days; a paused ingestion can miss older data.


## Support

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

For Hunters-side configuration:

- [Hunters: Set up bucket access](https://docs.hunters.ai/docs/step-3-set-up-bucket-access-1#IAMrole)