> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rad.security/llms.txt
> Use this file to discover all available pages before exploring further.

# Rapid7 InsightIDR

> Configure Rapid7 InsightIDR integration with RAD Security for user behavior analytics and threat detection.

# Rapid7 InsightIDR Integration Setup

This guide walks you through integrating Rapid7 InsightIDR with RAD Security for advanced user behavior analytics, threat detection, and incident investigation, enabling you to correlate security events and leverage InsightIDR's SIEM capabilities.

Rapid7 InsightIDR provides user behavior analytics, attacker behavior detection, and automated investigation capabilities for comprehensive security monitoring.

## Prerequisites

Before you begin, ensure you have:

<Check>
  * Admin access to Rapid7 InsightIDR
  * Ability to create users in your Rapid7 organization
  * Access to the email account you'll use for the service user
  * Access to RAD Security workspace with integration permissions
</Check>

<Info>
  **Service User Recommended:** Create a dedicated service user for this integration rather than using a personal account. This ensures continuity when team members change roles.
</Info>

***

## Step 1: Create Service User (Optional but Recommended)

Creating a dedicated service user allows you to limit API key permissions and maintain better security hygiene.

<Steps>
  <Step title="Log in as Administrator">
    Log in to Rapid7 InsightIDR with an administrator account
  </Step>

  <Step title="Navigate to User Management">
    Click the **settings gear** icon in the top right corner and select **Users**
  </Step>

  <Step title="Create New User">
    Click the **Create User** button
  </Step>

  <Step title="Enter User Details">
    Fill in the user information:

    * **First Name** (e.g., "RAD Security")
    * **Last Name** (e.g., "Integration")
    * **Email Address** (use a service email account)

    <Note>
      You'll need access to this email to activate the account. In production, use a service account email (e.g., `security-integrations@company.com`) to ensure the integration remains active when employees change roles.
    </Note>
  </Step>

  <Step title="Assign Product Access">
    Assign the user to the **Insight IDR** product
  </Step>

  <Step title="Assign Roles">
    Assign the following roles to the user:

    * **Insight IDR Analyst**
    * **Log Search View Only**

    <Info>
      These are the minimum roles required for the integration to function properly. You can assign higher-level roles if additional permissions are needed for your use case.
    </Info>
  </Step>

  <Step title="Create User">
    Click **Add User** to confirm creation
  </Step>

  <Step title="Log Out">
    Log out of your administrator account
  </Step>

  <Step title="Activate Service User">
    1. Open the email account associated with the new user
    2. Find the activation link from Rapid7
    3. Click the link to activate the account
    4. Complete the activation process and set a password
  </Step>
</Steps>

<Warning>
  **Save the activation link!** Make sure to activate the account promptly. If you lose the activation email, you may need to request a new one from your administrator.
</Warning>

***

## Step 2: Create Platform API Key

<Steps>
  <Step title="Log in as Service User">
    Log in to Rapid7 InsightIDR using the service user credentials you just created (or the existing user you want to use)
  </Step>

  <Step title="Navigate to API Keys">
    Click the **settings gear** icon in the top right corner and select **API Keys**
  </Step>

  <Step title="Create User Platform API Key">
    Follow [Rapid7's documentation for creating a User Platform API key](https://docs.rapid7.com/insight/managing-platform-api-keys/)

    1. Click **New User Key**
    2. Enter a descriptive name (e.g., "RAD Security Integration")
    3. Click **Generate**
  </Step>

  <Step title="Copy and Save API Key">
    **Immediately copy the API key** to a secure location

    <Warning>
      **This is your only chance to view the key!** If you lose it, you cannot retrieve it and will need to generate a new one.
    </Warning>
  </Step>
</Steps>

***

## Step 3: Determine Regional API URL

Rapid7 InsightIDR uses different API endpoints based on your data center location.

<AccordionGroup>
  <Accordion title="Regional URLs" icon="globe">
    Refer to [Rapid7's supported regions documentation](https://docs.rapid7.com/insight/product-apis/#supported-regions) to find the correct endpoint for your region.

    **Common Regional URLs:**

    | Region          | API Endpoint                         |
    | --------------- | ------------------------------------ |
    | United States   | `https://us.api.insight.rapid7.com`  |
    | United States 2 | `https://us2.api.insight.rapid7.com` |
    | United States 3 | `https://us3.api.insight.rapid7.com` |
    | Europe          | `https://eu.api.insight.rapid7.com`  |
    | Canada          | `https://ca.api.insight.rapid7.com`  |
    | Australia       | `https://au.api.insight.rapid7.com`  |
    | Japan           | `https://ap.api.insight.rapid7.com`  |

    <Note>
      Use the base URL **without any path components**. For example: `https://us2.api.insight.rapid7.com`
    </Note>
  </Accordion>
</AccordionGroup>

***

## Step 4: Configure in RAD Security

Navigate to your RAD Security workspace and configure the Rapid7 InsightIDR integration with the following parameters:

### Required Parameters

| Parameter | Description                                                      | Example                              |
| --------- | ---------------------------------------------------------------- | ------------------------------------ |
| **URL**   | Regional base URL for Rapid7 InsightIDR API (no path components) | `https://us2.api.insight.rapid7.com` |
| **Token** | Platform API key from Step 2                                     | `your-api-key-here`                  |

***

## Verify Integration

After completing the setup, verify your integration is working:

1. Navigate to **Data Sources > Integrations > SIEM** in RAD Security
2. Locate your Rapid7 InsightIDR integration
3. Check the connection status shows as **Connected**
4. Verify security events are being synced

<Check>
  Your Rapid7 InsightIDR integration is now configured! RAD Security can now correlate security events with InsightIDR's user behavior analytics and threat detection capabilities.
</Check>

## What Data is Synced

Once configured, RAD Security will sync the following data with Rapid7 InsightIDR:

<AccordionGroup>
  <Accordion title="Security Events" icon="shield-virus">
    * Threat detections and alerts
    * Security incidents
    * Attacker behavior indicators
    * Investigation findings
    * Alert timeline data
  </Accordion>

  <Accordion title="User Behavior Data" icon="users">
    * Authentication events
    * User activity patterns
    * Anomalous behavior detections
    * Privilege escalation attempts
    * Account compromise indicators
  </Accordion>

  <Accordion title="Log Data" icon="file-lines">
    * Security event logs
    * Authentication logs
    * Network activity logs
    * Endpoint activity
    * Custom log sources
  </Accordion>

  <Accordion title="Investigation Data" icon="magnifying-glass-chart">
    * Incident timelines
    * Investigation notes
    * Evidence artifacts
    * Threat actor TTPs
    * Correlation results
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="User Behavior Analytics" icon="chart-line">
    Correlate RAD Security runtime events with InsightIDR's user behavior analytics to detect anomalous activities.
  </Card>

  <Card title="Attacker Behavior Detection" icon="crosshairs">
    Identify attacker tactics, techniques, and procedures (TTPs) across endpoints and containerized infrastructure.
  </Card>

  <Card title="Automated Investigation" icon="wand-magic-sparkles">
    Leverage InsightIDR's automated investigation capabilities with RAD Security's runtime context.
  </Card>

  <Card title="Incident Response" icon="siren">
    Streamline incident response by correlating container security events with broader organizational security data.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Failed" icon="triangle-exclamation">
    **Possible causes:**

    * API key is incorrect or expired
    * Service user account was deactivated
    * Wrong regional API URL

    **Solution:**

    * Verify the API key is copied correctly (no extra spaces)
    * Check that the service user account is still active
    * Confirm you're using the correct regional URL for your instance
    * Generate a new API key if the current one is lost or compromised
  </Accordion>

  <Accordion title="Insufficient Permissions" icon="shield-exclamation">
    **Possible causes:**

    * Service user doesn't have required roles
    * User not assigned to Insight IDR product
    * Roles were removed or changed

    **Solution:**

    * Log in as admin and verify user roles
    * Ensure user has both "Insight IDR Analyst" and "Log Search View Only" roles
    * Verify user is assigned to Insight IDR product
    * Check that roles haven't been modified
  </Accordion>

  <Accordion title="No Data Syncing" icon="database-slash">
    **Possible causes:**

    * No security events in InsightIDR yet
    * Initial sync still in progress
    * Log sources not configured
    * API rate limits reached

    **Solution:**

    * Verify InsightIDR has active log sources
    * Allow up to 15 minutes for initial data sync
    * Check that collectors are sending data to InsightIDR
    * Review integration logs in RAD Security for specific errors
    * Monitor API usage to ensure you're within rate limits
  </Accordion>

  <Accordion title="Wrong Regional URL" icon="globe">
    **Possible causes:**

    * Using incorrect regional endpoint
    * Including path components in URL
    * Using old API endpoint format

    **Solution:**

    * Verify you're using the correct region (US, US2, US3, EU, CA, AU, AP)
    * Ensure URL is base only (e.g., `https://us2.api.insight.rapid7.com`)
    * Remove any path components like `/api/3`
    * Check your InsightIDR console URL to determine your region
  </Accordion>

  <Accordion title="API Key Issues" icon="key">
    **Possible causes:**

    * API key was manually revoked
    * Service user password was changed
    * Key expired or deleted

    **Solution:**

    * Log in as the service user
    * Navigate to API Keys management
    * Check if the key still exists and is active
    * Generate a new API key if needed
    * Update the key in RAD Security integration settings
  </Accordion>

  <Accordion title="Service User Account Problems" icon="user-slash">
    **Possible causes:**

    * Service user was deleted or suspended
    * Account locked due to failed login attempts
    * Email address changed or invalid

    **Solution:**

    * Log in as admin and verify the service user exists
    * Check the account status is Active
    * Unlock the account if it was locked
    * Verify the email address is accessible
    * Reactivate the account if it was suspended
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Service Accounts" icon="user-gear">
    Create a dedicated service account with a service email address to ensure continuity.
  </Card>

  <Card title="Least Privilege Roles" icon="shield-halved">
    Only assign Insight IDR Analyst and Log Search View Only roles unless higher permissions are specifically required.
  </Card>

  <Card title="Rotate API Keys" icon="rotate">
    Periodically rotate API keys as part of your security hygiene practices.
  </Card>

  <Card title="Secure Key Storage" icon="lock">
    Store API keys in a secure password manager or secrets vault. Never commit them to version control.
  </Card>

  <Card title="Monitor API Usage" icon="chart-line">
    Review API key usage in Rapid7 to detect any anomalous activity.
  </Card>

  <Card title="Audit User Access" icon="clipboard-list">
    Regularly review service user permissions and ensure they remain appropriate.
  </Card>
</CardGroup>

## API Key Management

To manage your API keys:

<Steps>
  <Step title="View Existing Keys">
    Log in as the service user and navigate to API Keys to view all active keys
  </Step>

  <Step title="Rotate Keys">
    1. Create a new API key with a different name
    2. Update RAD Security with the new key
    3. Verify the integration works
    4. Delete the old key
  </Step>

  <Step title="Revoke Compromised Keys">
    If a key is compromised, immediately revoke it and generate a new one
  </Step>
</Steps>

## Additional Resources

<CardGroup cols={2}>
  <Card title="Platform API Keys" icon="key" href="https://docs.rapid7.com/insight/managing-platform-api-keys/">
    Official guide to managing Rapid7 platform API keys
  </Card>

  <Card title="Supported Regions" icon="globe" href="https://docs.rapid7.com/insight/product-apis/#supported-regions">
    Complete list of regional API endpoints
  </Card>

  <Card title="Rapid7 InsightVM" icon="shield-halved" href="/rad-security/integrations/vulnerabilities/rapid7-insightvm-setup">
    Configure Rapid7 InsightVM for vulnerability management
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="SIEM Integrations Overview" icon="chart-line" href="/rad-security/integrations/siem/overview">
    Explore other SIEM integration options
  </Card>

  <Card title="Runtime Security" icon="shield" href="/rad-security/integrations/runtime-security">
    Learn what runtime events are correlated with InsightIDR
  </Card>

  <Card title="Alerts & Incidents" icon="bell" href="/rad-security/platform/workspace">
    Configure alert rules and incident management
  </Card>

  <Card title="Threat Models" icon="crosshairs" href="/rad-security/security-and-compliance/overview">
    Understand how threats are detected and classified
  </Card>
</CardGroup>