> ## 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 InsightVM

> Configure Rapid7 InsightVM integration with RAD Security for live vulnerability management.

# Rapid7 InsightVM Integration Setup

This guide walks you through integrating Rapid7 InsightVM with RAD Security for live vulnerability management and risk assessment, allowing you to correlate vulnerability data with runtime security events.

Rapid7 InsightVM provides continuous vulnerability monitoring with live dashboards, risk-based prioritization, and automated remediation tracking.

## Prerequisites

Before you begin, ensure you have:

<Check>
  * Admin access to Rapid7 InsightVM
  * 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 Account 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: Log in to Rapid7 InsightVM

<Steps>
  <Step title="Access Rapid7 Console">
    Log in to Rapid7 InsightVM 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>
</Steps>

***

## Step 2: Create Service User with Minimum Permissions

<Info>
  API Keys inherit the same permissions as the user they're associated with. While you can use an existing user, it's recommended to create a dedicated service user with only the necessary permissions.
</Info>

<Steps>
  <Step title="Create New User">
    Click the **Create User** button in the Users interface
  </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">
    Under **Manage Individual Permissions > Products** tab:

    1. Assign the user to the **InsightVM** product
    2. Select **Your Organization name**
  </Step>

  <Step title="Assign Roles">
    Under **Manage Individual Permissions > Roles** tab:

    Assign the following role:

    * **Administrator (shared)**

    <Info>
      This is the minimum role required for vulnerability data access. You can assign higher 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 Account">
    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 3: Create Platform API Key

<Steps>
  <Step title="Log in as Service User">
    Log in to Rapid7 InsightVM using the service user credentials you just created
  </Step>

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

  <Step title="Access Organization Keys">
    In the left navigation, go to:

    **API KEY MANAGEMENT > Organization Keys**
  </Step>

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

    1. Click **New Organization 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 4: Configure in RAD Security

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

### Required Parameters

| Parameter    | Description                                                     | Example                             |
| ------------ | --------------------------------------------------------------- | ----------------------------------- |
| **Base URL** | Regional base URL for Rapid7 InsightVM API (no path components) | `https://us.api.insight.rapid7.com` |
| **Secret**   | Platform API key from Step 3                                    | `your-api-key-here`                 |

### Regional URLs

Select the appropriate regional URL for your Rapid7 instance:

<CodeGroup>
  ```text United States theme={null}
  https://us.api.insight.rapid7.com
  ```

  ```text United States 2 theme={null}
  https://us2.api.insight.rapid7.com
  ```

  ```text United States 3 theme={null}
  https://us3.api.insight.rapid7.com
  ```

  ```text Europe theme={null}
  https://eu.api.insight.rapid7.com
  ```

  ```text Canada theme={null}
  https://ca.api.insight.rapid7.com
  ```

  ```text Australia theme={null}
  https://au.api.insight.rapid7.com
  ```

  ```text Japan theme={null}
  https://ap.api.insight.rapid7.com
  ```
</CodeGroup>

<Note>
  Make sure to use the base URL **without any path components**. For example, use `https://us.api.insight.rapid7.com` not `https://us.api.insight.rapid7.com/vm/v4`.
</Note>

***

## Verify Integration

After completing the setup, verify your integration is working:

1. Navigate to **Data Sources > Integrations > Vulnerabilities** in RAD Security
2. Locate your Rapid7 InsightVM integration
3. Check the connection status shows as **Connected**
4. Verify vulnerability data is being synced

<Check>
  Your Rapid7 InsightVM integration is now configured! RAD Security can now import live vulnerability data and correlate it with runtime security events.
</Check>

## What Data is Synced

Once configured, RAD Security will sync the following data from Rapid7 InsightVM:

<AccordionGroup>
  <Accordion title="Vulnerability Findings" icon="bug">
    * CVE identifiers and details
    * Vulnerability severity and CVSS scores
    * CVSS v2 and v3 vectors
    * Affected assets and services
    * Vulnerability age and trends
    * Exploit availability and maturity
    * Malware kit associations
  </Accordion>

  <Accordion title="Asset Information" icon="server">
    * Asset inventory and details
    * Operating systems and versions
    * Installed software and services
    * Network information (IPs, MACs, hostnames)
    * Asset tags and classifications
    * Last assessment dates
  </Accordion>

  <Accordion title="Risk Context" icon="chart-line">
    * Real-time risk scores
    * Asset criticality ratings
    * Vulnerability remediation projects
    * Risk trends over time
    * Policy compliance status
  </Accordion>

  <Accordion title="Remediation Data" icon="wrench">
    * Available patches and updates
    * Remediation procedures
    * Estimated remediation time
    * Remediation project tracking
    * Exception and acceptance records
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Live Vulnerability Monitoring" icon="signal-stream">
    Monitor vulnerabilities in real-time as they're discovered, with continuous updates from InsightVM.
  </Card>

  <Card title="Risk-Based Prioritization" icon="ranking-star">
    Prioritize vulnerabilities using InsightVM's real risk scores combined with RAD's runtime context.
  </Card>

  <Card title="Remediation Tracking" icon="list-check">
    Track remediation efforts across your environment with automated validation.
  </Card>

  <Card title="Exploit Correlation" icon="crosshairs">
    Identify when vulnerabilities are actively exploited by correlating with runtime security events.
  </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 Administrator (shared) role
    * User not assigned to InsightVM product
    * Organization-level permissions not set

    **Solution:**

    * Log in as admin and verify user roles
    * Ensure user is assigned to InsightVM product
    * Verify user has Administrator (shared) role at minimum
    * Check organization-level permissions are properly configured
  </Accordion>

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

    * No vulnerability scans completed yet
    * Assets not reporting to InsightVM
    * Initial sync still in progress

    **Solution:**

    * Verify vulnerability scans have been run in InsightVM
    * Check that assets are actively reporting
    * Allow up to 15 minutes for initial data sync
    * Review integration logs in RAD Security for specific errors
  </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://us.api.insight.rapid7.com`)
    * Remove any path components like `/vm/v4`
    * Check your Rapid7 console URL to determine your region
  </Accordion>

  <Accordion title="API Key Expired or Revoked" icon="key-skeleton">
    **Possible causes:**

    * API key was manually revoked
    * Key expired due to organization policy
    * Service user password was changed

    **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>
</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 Access" icon="shield-halved">
    Only assign Administrator (shared) role unless higher permissions are specifically required.
  </Card>

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

  <Card title="Regular Key Rotation" icon="rotate">
    Periodically rotate API keys as part of your security hygiene practices.
  </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>

## Next Steps

<CardGroup cols={2}>
  <Card title="Vulnerabilities Overview" icon="shield-halved" href="/rad-security/integrations/vulnerabilities/overview">
    Explore other vulnerability integration options
  </Card>

  <Card title="Runtime Security" icon="shield" href="/rad-security/integrations/runtime-security">
    Learn how RAD correlates vulnerabilities with runtime threats
  </Card>

  <Card title="Rapid7 InsightIDR" icon="chart-line" href="/rad-security/integrations/siem/overview">
    Add Rapid7 InsightIDR for SIEM integration
  </Card>

  <Card title="Alerts & Incidents" icon="bell" href="/rad-security/platform/workspace">
    Configure alerts for vulnerability-related events
  </Card>
</CardGroup>