# Rapid7 InsightIDR Integration

Connect your Rapid7 InsightIDR account to Capsule Security to inventory the endpoints running the Insight Agent and discover the AI coding agents and AI apps in use across them.

## Overview

This integration uses the Rapid7 Log Search API to sync:

- **Devices** - Every endpoint whose Insight Agent reported to the Endpoint Health log set in the last 15 days (hostname, last seen), owned by the account that signs in to it most often according to the Asset Authentication log set
- **AI coding agents** - Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf, and similar developer agents detected from Insight Agent process start events
- **AI apps** - Browser and web-app usage of AI services, detected from DNS and web proxy logs you forward to InsightIDR


Capsule connects with a read-only API key and never installs software on endpoints or writes to your Rapid7 account.

## Prerequisites

Before you begin, ensure you have:

- An active **InsightIDR** account with the **Insight Agent** deployed to your endpoints
- **Enhanced Endpoint Telemetry**, included in the InsightIDR **Advanced** and **Ultimate** packages
- Access to create users and assign roles in the **Rapid7 Command Platform**
- The **region** your account runs in (shown in your console URL)
- A **Capsule Security** account with admin access


> **Required for AI agent discovery - Enhanced Endpoint Telemetry.** Capsule detects AI agents from the process start events the Insight Agent sends with Enhanced Endpoint Telemetry. The Advanced package keeps these events for 7 days and the Ultimate package for 13 months. Capsule checks for them when you connect and tells you if they are missing.


> **AI app discovery needs forwarded network logs.** The Insight Agent does not collect DNS lookups from endpoints. Capsule finds AI app usage in the **DNS Query** and **Web Proxy Activity** log sets, which hold the DNS server and web proxy logs you forward to InsightIDR. Without them, device inventory and AI agent discovery still work.


## Step 1: Create a Dedicated User

A Rapid7 User key carries the permissions of the user who creates it. Create a user that exists only for Capsule so the key can read Log Search and nothing else.

### Steps

1. Sign in to the **Rapid7 Command Platform** as an administrator.
2. Add a new user for the integration, for example `capsule-integration@acme.com`.
3. Give the user access to **InsightIDR** with the Rapid7-managed **Log Search View Only** role. Do not assign any other role.
4. Complete the invitation and sign in once as the new user.


## Step 2: Generate a User Key

### Steps

1. Sign in to the Rapid7 Command Platform **as the dedicated user** from Step 1.
2. Go to **Platform Home → API Key Management**.
3. On the **User Key** tab, click **New User Key**.
  - **Organization**: Select the organization that owns your InsightIDR data.
  - **Name**: Enter a descriptive name, for example `Capsule Security Integration`.
4. Generate the key and **copy it immediately**. Rapid7 shows the key only once. If you lose it, generate a new one.


### Finding your region

Your InsightIDR console URL starts with your region code. For example, a console at `us2.idr.insight.rapid7.com` is in the `us2` region. Select the matching region in Capsule:

| Region | Console | API host |
|  --- | --- | --- |
| United States 1 | `us.idr.insight.rapid7.com` | `us.api.insight.rapid7.com` |
| United States 2 | `us2.idr.insight.rapid7.com` | `us2.api.insight.rapid7.com` |
| United States 3 | `us3.idr.insight.rapid7.com` | `us3.api.insight.rapid7.com` |
| Europe | `eu.idr.insight.rapid7.com` | `eu.api.insight.rapid7.com` |
| Canada | `ca.idr.insight.rapid7.com` | `ca.api.insight.rapid7.com` |
| Australia | `au.idr.insight.rapid7.com` | `au.api.insight.rapid7.com` |
| Japan | `ap.idr.insight.rapid7.com` | `ap.api.insight.rapid7.com` |
| Middle East (UAE) | `me1.idr.insight.rapid7.com` | `me1.api.insight.rapid7.com` |
| India | `aps2.idr.insight.rapid7.com` | `aps2.api.insight.rapid7.com` |


### Security notes

- The key is stored encrypted and is never written to logs or returned to the browser after setup.
- Capsule only reads. It does not quarantine assets, run jobs on agents, or change any InsightIDR configuration.
- Deleting the key in **API Key Management**, or deactivating the dedicated user, immediately stops all Capsule access.


## Step 3: Configure the Integration in Capsule

### Steps

1. In the Capsule portal, go to **Settings → Integrations**.
2. Find **Rapid7 InsightIDR** and click **Connect**.
3. Enter your details:
  - **Region**: The region code from your console URL.
  - **API Key**: The User key you copied in Step 2.
4. Capsule tests the connection as you type and reports success or the specific failure.
5. Click **Save**.


### After setup

- Initial sync begins automatically.
- The first sync covers the last 7 days in one-day windows, so it may take several runs to catch up.
- View synced endpoints in **Inventory → Devices**.
- View detected AI coding agents and AI apps in **Discovery → Agents**, mapped back to the device and user they ran on.


Discovery runs on a recurring schedule to pick up new endpoints, endpoints that stopped reporting, and newly observed AI activity.

## Query Volume

Log Search aggregates results on the Rapid7 side, so each sync reads a small summary rather than raw events. A typical run issues about five Log Search queries, well within Rapid7's limit of 1,500 queries per 15 minutes.

## Feature Availability

| Capsule feature | Requires |
|  --- | --- |
| **Device inventory** (hostnames, last seen, owner) | Insight Agent + **Log Search View Only** role |
| **AI coding-agent detection** (Claude Code, Cursor, Copilot, Codex, and others) | Insight Agent + **Enhanced Endpoint Telemetry** |
| **AI app detection** (AI services used from the browser) | DNS server or web proxy logs forwarded to InsightIDR |


If the process or network search fails during a sync, device inventory still syncs in full and Capsule retries the failed window on the next run rather than skipping it.

## Troubleshooting

### The connection test rejects the API key (401)

- The key is wrong, was deleted, or belongs to a deactivated user. Generate a new User key as the dedicated user and enter it again.


### The connection test reports missing permissions (403)

- The dedicated user does not hold the **Log Search View Only** role for InsightIDR. Assign the role and test again.


### The connection test reports that Enhanced Endpoint Telemetry is missing

- Your account has no Endpoint Activity data. Confirm your InsightIDR package includes Enhanced Endpoint Telemetry and that it is enabled for your agents.


### The connection test cannot find your data

- The selected **region** does not match your account. Check your console URL against the [region table](#finding-your-region) and reconnect with the right one.


### Devices appear but no AI agents are discovered

- Confirm AI agents have actually launched on endpoints with the Insight Agent within the window Capsule is processing. An account catching up on its first 7 days processes older windows first.


### AI agents appear but no AI apps are discovered

- This is expected when no DNS or web proxy logs are forwarded to InsightIDR. See [Feature availability](#feature-availability).


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your tenant ID, integration status, InsightIDR region, and any error messages from the Capsule portal


For Rapid7 user, role, or API key issues:

- **Rapid7 Command Platform**: **Platform Home → API Key Management**
- **Reference**: [Managing Platform API Keys](https://docs.rapid7.com/insight/managing-platform-api-keys/)