---
url: https://docs.realmsec.info/integration/rapid7_insightidr.md
---

# Rapid7 InsightIDR Integration

![Rapid7 InsightIDR Architecture](../images/rapid7_insightidr.png)

### Send Realm Data to Rapid7 InsightIDR

This guide walks you through connecting [Rapid7 InsightIDR](https://www.rapid7.com/products/insightidr/) to Realm as a destination. The integration uses a webhook-based approach — Realm sends log data directly to InsightIDR's Custom Logs webhook endpoint, allowing you to forward security events and other data streams to your SIEM for centralized analysis.

## Prerequisites

* Active Rapid7 InsightIDR account with administrator access
* Access to the Realm Security console
* Ability to generate and copy webhook URLs from InsightIDR

## Generate a Custom Logs Webhook URL in Rapid7 InsightIDR

1. Log in to your Rapid7 InsightIDR console.
2. In the left sidebar, click **Data Collection**.

![InsightIDR Data Collection sidebar](../images/insightidr_data_collection.png)

3. Click **Event Sources**.

![InsightIDR Event Sources](../images/insightidr_event_sources.png)

4. Click **Add Event Source** and search for or select **Rapid7 Custom Logs** from the list.

![InsightIDR Add Event Source](../images/insightidr_add_event_source.png)

5. In the event source configuration panel, set the source type to **Webhook**.
6. Complete the configuration and save. InsightIDR will generate a unique **Webhook URL** for this source.

![InsightIDR Configure Event Source](../images/insightidr_configure_event_source.png)

7. Copy the **Webhook URL** — you will need it when setting up the Realm output feed.

> **Important:** The webhook URL is unique and should be treated as a secret. Do not share it or commit it to version control. Copy and save it - you will need it when configuring the output feed in the Realm Console.

8. (Optional) If you need to send specific fields as events, note the **JSON Events Key** field name — Realm can use this to extract events from a nested field in the JSON payload (supports dot notation for nested paths).

## Configure the Destination in Realm

1. In the Realm Security console, navigate to **Settings > Data Outputs** (or your configured destination management area).
2. Click **Add Destination** or **Create New Destination**.
3. Fill in the destination configuration:

> **Name:** `Rapid7 InsightIDR`\
> **Type:** `Rapid7 InsightIDR`\
> **Endpoint:** `<your Rapid7 InsightIDR Custom Logs Webhook URL>`

4. Save the destination configuration.

Once configured, Realm will begin forwarding data to the InsightIDR Custom Logs webhook as NDJSON (newline-delimited JSON).

## Export Detections for Detection Integrity

[Detection Integrity](/product/detection_integrity) checks your log optimization rules against your Rapid7 InsightIDR detections, so optimizations never drop data a detection depends on. Export your detections as described below, then upload them to Realm.

Export both kinds of rules your team creates in InsightIDR with the API: **Custom Detection Rules** and **Basic Detection Rules** (formerly Custom Alerts). The export keeps only your team's rules, not the 25,000+ rules Rapid7 publishes, and includes each rule's LEQL query.

> **Note:** The InsightIDR console export does not include each rule's LEQL query, so use the API export below.

### Export with the API

1. Create an Insight Platform API key (see [Managing Platform API Keys](https://docs.rapid7.com/insight/managing-platform-api-keys/)). This key needs permissions for both SIEM and Log Search access.
2. Run the commands for your platform below, setting the region variable to your Insight region (`us`, `us2`, `us3`, `ca`, `eu`, `au`, or `ap`). The commands prompt for the API key and keep it out of your shell history.
3. The commands first fetch your Basic Detection Rules in a single request. They then page through the full detection rule library, including Rapid7's published rules, and keep only your Custom Detection Rules. The API returns at most 100 rules per page, so the export can take 30 minutes or more. Each page prints a progress line.
4. The commands write both kinds of rules, one rule per line, to `rapid7_detection_rules.jsonl`. If they print `unexpected response`, the export is incomplete. Check the API key and region, then run the commands again.

#### macOS and Linux

Requires `curl` and `jq`.

```shell
R7_REGION="us"
printf 'Rapid7 API key: '; read -rs R7_KEY; echo
R7_KEY=${R7_KEY//[[:space:][:cntrl:]]/}

out="rapid7_detection_rules.jsonl"
: > "$out"

resp=$(curl -s "https://$R7_REGION.rest.logs.insight.rapid7.com/management/tags" \
  -H @<(printf 'X-Api-Key: %s\n' "$R7_KEY"))

if printf '%s' "$resp" | jq -e '.tags' >/dev/null 2>&1; then
  printf '%s' "$resp" | jq -c '.tags[] | del(.sources[]?.token)' >> "$out"
  echo "$(wc -l < "$out" | tr -d ' ') basic detection rules fetched" >&2
else
  echo "Unexpected response for basic detection rules: $resp" >&2
fi

position=""
page=0

while true; do
  pos_args=()
  [ -n "$position" ] && pos_args=(--data-urlencode "position=$position")

  resp=$(curl -s -G "https://$R7_REGION.api.insight.rapid7.com/idr/v1/rules" \
    -H @<(printf 'X-Api-Key: %s\n' "$R7_KEY") \
    -H "Accept-version: strong-force-preview" \
    --data-urlencode "size=100" \
    "${pos_args[@]}")

  page=$((page + 1))

  if ! printf '%s' "$resp" | jq -e '.data' >/dev/null 2>&1; then
    echo "Unexpected response on page $page: $resp" >&2
    break
  fi

  matched=$(printf '%s' "$resp" | jq -c '.data[] | select(.rule_set == "CDR")')
  if [ -n "$matched" ]; then
    printf '%s\n' "$matched" >> "$out"
    count=$(printf '%s\n' "$matched" | wc -l | tr -d ' ')
  else
    count=0
  fi
  echo "page $page fetched ($count CDR rules)" >&2

  position=$(printf '%s' "$resp" | jq -r '.position // empty')
  [ -z "$position" ] && break
done

unset R7_KEY
echo "$(wc -l < "$out" | tr -d ' ') detection rules written to $out"
```

#### Windows

Requires PowerShell 5.1 or later.

```powershell
$R7Region = "us"
$SecureKey = Read-Host "Rapid7 API key" -AsSecureString
$R7Key = [Net.NetworkCredential]::new("", $SecureKey).Password -replace '[\s\p{C}]', ''

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
$ProgressPreference = "SilentlyContinue"

$Out = Join-Path (Get-Location) "rapid7_detection_rules.jsonl"
$Lines = [Collections.Generic.List[string]]::new()
$TagHeaders = @{ "X-Api-Key" = $R7Key }
$Headers = @{ "X-Api-Key" = $R7Key; "Accept-version" = "strong-force-preview" }

function Get-R7Body($Uri, $Headers) {
  try {
    (Invoke-WebRequest -Uri $Uri -Headers $Headers -UseBasicParsing).Content
  } catch {
    if ($_.ErrorDetails.Message) { $_.ErrorDetails.Message } else { $_.Exception.Message }
  }
}

$Body = Get-R7Body "https://$R7Region.rest.logs.insight.rapid7.com/management/tags" $TagHeaders
$Resp = $null
try { $Resp = $Body | ConvertFrom-Json } catch { }
if ($Resp -and $Resp.PSObject.Properties.Name -contains "tags") {
  foreach ($Rule in $Resp.tags) {
    foreach ($Source in @($Rule.sources)) { if ($Source) { $Source.PSObject.Properties.Remove("token") } }
    $Lines.Add(($Rule | ConvertTo-Json -Depth 20 -Compress))
  }
  Write-Host "$($Lines.Count) basic detection rules fetched"
} else {
  Write-Host "Unexpected response for basic detection rules: $Body"
}

$Position = $null
$Page = 0

while ($true) {
  $Uri = "https://$R7Region.api.insight.rapid7.com/idr/v1/rules?size=100"
  if ($Position) { $Uri += "&position=" + [uri]::EscapeDataString($Position) }
  $Page++

  $Body = Get-R7Body $Uri $Headers

  $Resp = $null
  try { $Resp = $Body | ConvertFrom-Json } catch { }
  if (-not ($Resp -and $Resp.PSObject.Properties.Name -contains "data")) {
    Write-Host "Unexpected response on page ${Page}: $Body"
    break
  }

  $Count = 0
  foreach ($Rule in $Resp.data) {
    if ($Rule.rule_set -eq "CDR") {
      $Lines.Add(($Rule | ConvertTo-Json -Depth 20 -Compress))
      $Count++
    }
  }
  Write-Host "page $Page fetched ($Count CDR rules)"

  $Position = $Resp.position
  if (-not $Position) { break }
}

[IO.File]::WriteAllLines($Out, $Lines)
Remove-Variable R7Key, SecureKey, Headers, TagHeaders
Write-Host "$($Lines.Count) detection rules written to $Out"
```

### Upload the Export to Realm

Upload the exported file as described in [Upload Detections to Realm](/product/detection_integrity#upload-detections), selecting your Rapid7 InsightIDR destination.

## Support

For additional details, refer to the official [Rapid7 InsightIDR documentation](https://docs.rapid7.com/insightidr/).

If you encounter any issues or require assistance, contact Realm Security support.