# Rapid7 InsightIDR SIEM Integration

Push Capsule detections, findings, and policy violations into Rapid7 InsightIDR through a Custom Logs webhook, so your SOC searches and alerts on AI-agent and shadow-AI signals next to the rest of its telemetry.

## Overview

Capsule sends each event to your Custom Logs webhook URL as it is produced. The webhook is a cloud event source, so there is no Collector to deploy.

| 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 Custom Logs webhook URL, as a JSON array
  → one InsightIDR event per array element
  → searchable in Log Search, in the log named after the event source
  → (optional) your detection rule opens an investigation
```

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


> **Rapid7 ships no detection rules for Custom Logs data.** Capsule events are searchable as soon as they land, but nothing raises an alert or investigation until you add a rule. See [Alerting on Capsule events](#alerting-on-capsule-events).


## Prerequisites

- A **Capsule** account with admin access, and the **SIEM** tab visible under **Settings**
- **Rapid7 InsightIDR** with the **Admin** role, which is needed to add an event source
- Nothing to install: the webhook collection method is cloud-only and needs no Collector


Rapid7 Incident Command uses the same event sources and the same **Data Connectors** menu, so the steps below apply unchanged.

## Step 1: Prepare Rapid7

1. In InsightIDR, click **Data Connectors** in the left menu and go to **SIEM → Data Collectors**.
2. Click **Setup Event Source → Add Event Source**.
3. Under **Add Raw Data**, click **Custom Logs**.
4. Name the event source, for example `capsule`. The name becomes the name of the log that holds Capsule's events in Log Search.
5. Under **Collection Method**, choose **Webhook**.
6. Leave **JSON Events Key** empty. Capsule sends a top-level JSON array, and InsightIDR makes each element its own event.
7. Copy the webhook URL and click **Save**.


> **The webhook URL is the only credential.** Anyone holding it can send events into your InsightIDR. Treat it like a password.


## Step 2: Create the SIEM integration in Capsule

1. In Capsule, go to **Settings → SIEM** and click **Add integration**.
2. Set **Destination** to **Rapid7 InsightIDR**.
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, Splunk, and OpenTelemetry exports.
  - **Compact** omits activity message bodies. Use it if events reach Rapid7's 100,000-character event limit, or where the transcript is not what you search on.
5. Paste the **Webhook URL** from Step 1, exactly as InsightIDR shows it. Capsule only accepts an `https` URL on a `*.insight.rapid7.com` host. The URL is stored as a secret and never shown again; the details drawer shows only its host.
6. Click **Save**, then **enable** the integration. A new integration starts disabled and exports nothing until you turn it on.


When you edit the integration later, leave **Webhook URL** empty to keep the saved one.

To rotate the URL, click **Generate a new Webhook URL** on the event source in InsightIDR, then paste the new URL into the integration and save. Rapid7 does not document what happens to the previous URL, so update Capsule straight away.

## Step 3: Verify

Use the row menu's **Send test event**. Capsule posts a single connection-test event to the webhook URL and reports whether Rapid7 accepted it, with Rapid7's error if it did not. The event is a `detection.created` whose `event.detection.detectionType` is `CAPSULE_CONNECTION_TEST`, so it is easy to exclude.

To see it in InsightIDR, open **Log Search**, select the **Raw Log** log set and the log named after your event source, and run:

```
where(event.detection.detectionType = "CAPSULE_CONNECTION_TEST")
```

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.

## What arrives in InsightIDR

### Where events land

Each event lands in the **Raw Log** log set, in the log named after the event source. InsightIDR parses JSON automatically, so every field of the envelope is a searchable key, with dots for nested fields such as `event.issue.severity`.

Log Search orders raw logs by ingestion time, the moment InsightIDR received them. Capsule's own timestamps are in the event: `exportedAt` is when Capsule sent it, and the record's `createdAt` (`event.detection.createdAt`, `event.finding.createdAt`, or `event.issue.createdAt`) is when it was raised.

### Event envelope

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

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

`eventType` is one of `detection.created`, `finding.created`, `policy_violation.created`. This is the same envelope the S3, Splunk, and OpenTelemetry destinations send, so a tenant exporting to more than one 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 under `event.issue`, the policy that raised it under `event.policy` 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.

Policy violations carry Capsule's severity at `event.issue.severity`, in lower case: `low`, `medium`, `high`, or `critical`. Capsule does not rank detections or findings, so those events have no severity field.

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


### Alerting on Capsule events

Rapid7 documents raw logs as a data source for **basic detection rules**. To open an investigation from Capsule events:

1. In **Log Search**, select the log named after your event source and run the query you want to alert on, for example one below.
2. Click **Query Actions (•••) → Create Basic Detection Rule** and choose **Log Pattern Detection Rule**.
3. Name the rule, confirm the log, set the default priority for the investigations it creates, and use your query as the trigger.


All detections:

```
where(eventType = "detection.created")
```

High and critical policy violations:

```
where(eventType = "policy_violation.created" AND event.issue.severity IN [high, critical])
```

Rapid7 also offers **custom detection rules**, created from the **Detection Rules** page with **Create Detection Rule**, which add thresholds, exceptions, and a choice of creating an alert or an investigation. Rapid7 documents them for logs from Collector event sources, the Insight Network Sensor, and the Insight Agent, and does not say whether webhook event sources are covered. If your Capsule log is offered as a data source there, the same LEQL applies.

For the full query syntax, see Rapid7's [Components for Building a Query](https://docs.rapid7.com/insightidr/components-for-building-a-query/).

## Delivery behaviour

- **Latency** - events are sent as they are produced, inline with the detection, finding, or violation being created.
- **Format** - each request is a JSON array of events, uncompressed, kept under 5 MB, half of Rapid7's 10 MB request limit.
- **Oversized events** - Rapid7 caps a single event at 100,000 characters. A larger event is not sent and never truncated: the integration reports an error, and the other events in the same delivery still go. Switching **Event detail** to Compact is the fix.
- **Retries** - Capsule retries `429`, `5xx`, timeouts, and network errors up to twice within 20 seconds, honouring `Retry-After`. Every other failure is a configuration error and is reported instead.
- **Timeouts** - each request has 10 seconds to complete.
- **Redirects** - never followed, so events only ever go to the host you configured.
- **Visibility** - the outcome of the most recent attempt is shown per integration in **Settings → SIEM**, with the full error in the details drawer. The webhook URL is masked in error text.
- **Backfill** - export begins when the integration is enabled. Events raised before that are not sent.


## Troubleshooting

### `The Rapid7 webhook URL redirected` (HTTP 3xx)

The saved URL is not the one InsightIDR issued, for example it was edited or copied through a link that forwards to it. Copy the URL from the event source again and paste it exactly.

### `Rapid7 rejected the webhook URL` (HTTP 401 or 403)

Rapid7 did not accept the URL. Click **Generate a new Webhook URL** on the event source, paste it into the integration, and save.

### `Rapid7 has no event source at this webhook URL` (HTTP 404)

The event source was deleted, or its URL was regenerated. Copy the current URL from the event source, or create a new event source as in Step 1, and save it on the integration.

### `Rapid7 rejected the request as too large` (HTTP 413)

Switch **Event detail** to Compact to shrink the events.

### `exceed Rapid7's 100000 character event limit`

One or more events were larger than Rapid7's per-event limit and were not sent. The rest of the delivery went through. Switch **Event detail** to Compact, which drops activity message bodies, the bulk of a large event. If Compact events still exceed the limit, contact support.

### `This Rapid7 integration has no webhook URL stored`

The integration has no saved URL. Edit it, paste the webhook URL from the event source, and save.

### 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 Rapid7.
- In **Log Search**, select the **Raw Log** log set and the log named after your event source. Capsule events do not appear in other logs.
- Events raised before the integration was enabled are not sent. Wait for a new detection, finding, or violation, or send a test event.


## Support

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