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

# Rapid7

> Connect ThreatAware to Rapid7 InsightIDR for security monitoring and threat detection data

## Overview

The Rapid7 integration enables ThreatAware to collect data from your Rapid7 InsightIDR platform, providing visibility into security events, threat detection, and investigation data.

<Info>
  **Connection Method**: API
  **Setup Time**: 15 minutes
  **Access Required**: Rapid7 Organisation Administrator account
</Info>

## Data collected

The Rapid7 integration provides:

* Security event data
* Threat detection information
* Investigation metadata
* Asset vulnerability information
* User investigation data

## Use cases

<CardGroup cols={2}>
  <Card title="Security Event Monitoring" icon="shield">
    Monitor security events and threats detected across your infrastructure
  </Card>

  <Card title="Threat Detection Integration" icon="triangle-exclamation">
    View threat detections from InsightIDR within ThreatAware
  </Card>

  <Card title="Investigation Support" icon="magnifying-glass">
    Access investigation data and findings from Rapid7 analysts
  </Card>

  <Card title="Compliance Evidence" icon="file-contract">
    Generate reports showing security monitoring coverage and detections
  </Card>
</CardGroup>

## Setup instructions

<Steps>
  <Step title="Log in to ThreatAware Dashboard">
    Navigate to your ThreatAware instance and go to **Settings** > **Systems**.
  </Step>

  <Step title="Search for Rapid7">
    Use the search bar to find "Rapid7" in the integrations list.
  </Step>

  <Step title="Click Connect">
    Click **Connect** to open the connection popup window. Keep this window open.
  </Step>

  <Step title="Access Rapid7 Platform">
    Log in to your [Rapid7 Platform](https://insight.rapid7.com/login) using your administrator credentials.
  </Step>

  <Step title="Generate Organisation API Key">
    In the Rapid7 console:

    * Navigate to **Settings** > **API Keys** from the top-right menu
    * Click **Generate New Key**
    * Select **Organisation Key**
    * Name it "ThreatAware" for easy identification
    * Copy the generated key for use in ThreatAware
  </Step>

  <Step title="Obtain Organisation ID">
    Still in Rapid7 Settings:

    * Navigate to **Organisation Settings** on the left sidebar
    * Locate and copy your **Organisation ID**
    * This ID is required for ThreatAware configuration
  </Step>

  <Step title="Identify API Region">
    Determine your Rapid7 API region:

    * Access **Insight IDR** and check the URL format: `{region}.idr.insight.rapid7.com`
    * The region will be one of: **us**, **us2**, **us3**, **eu**, **ca**, **au**, or **ap**
    * Note this region for ThreatAware configuration

    <Tip>
      If your URL is `us2.idr.insight.rapid7.com`, your region is "us2"
    </Tip>
  </Step>

  <Step title="Input Details into ThreatAware">
    Return to the ThreatAware integration popup and enter:

    * **API Key**: The organisation API key from step 5
    * **Organisation ID**: From step 6
    * **API Region**: From step 7
    * Click **Connect** to establish the integration
  </Step>

  <Step title="Verify Connection">
    After connecting:

    * Check that the **Integration Status** shows as **Active**
    * Verify data is appearing in ThreatAware by viewing security events
    * Wait up to 15 minutes for the first data sync
  </Step>
</Steps>

## Required credentials

<AccordionGroup>
  <Accordion title="API Key" icon="lock">
    **Field Name**: Rapid7 Organisation API Key
    **Type**: Password (encrypted)
    **Description**: The API key generated in Rapid7 for organisation-level access

    This must be an Organisation Key, not a personal API key.
  </Accordion>

  <Accordion title="Organisation ID" icon="building">
    **Field Name**: Rapid7 Organisation ID
    **Type**: String
    **Description**: Your unique Rapid7 organisation identifier

    Found in **Settings** > **Organisation Settings**
  </Accordion>

  <Accordion title="API Region" icon="globe">
    **Field Name**: Rapid7 API Region
    **Type**: String
    **Description**: The region of your Rapid7 InsightIDR instance

    **Valid Values**: us, us2, us3, eu, ca, au, ap
    **Example**: us2
  </Accordion>
</AccordionGroup>

## Verification and testing

After setup, verify the integration is working correctly:

1. **Check Integration Status**
   * Navigate to **Settings** > **Integrations** in ThreatAware
   * Confirm Rapid7 shows **Active** status
   * Check the last sync timestamp

2. **Verify Data Collection**
   * Wait 15 minutes for the initial data poll
   * Check for security events in ThreatAware
   * Verify event data matches what you see in Rapid7

3. **Test Queries**
   * Create a test query to filter events from Rapid7
   * Verify the results match your expectations

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid API Key Error" icon="triangle-exclamation">
    **Symptoms**: Integration status shows authentication failure

    **Solutions**:

    * Verify the **API Key** is correct and was copied without extra spaces
    * Ensure the API key is an **Organisation Key**, not a personal key
    * Check that the API key has not been revoked in Rapid7
    * Ensure your administrator account is still active
    * Generate a new API key if needed
  </Accordion>

  <Accordion title="Invalid Organisation ID" icon="ban">
    **Symptoms**: Connection fails with organisation ID error

    **Solutions**:

    * Verify the **Organisation ID** is correct
    * Navigate to **Settings** > **Organisation Settings** in Rapid7 to confirm
    * Ensure the Organisation ID was copied without extra spaces
    * Check that you have the correct Rapid7 organisation
  </Accordion>

  <Accordion title="Invalid API Region" icon="map-pin">
    **Symptoms**: Connection fails with region error

    **Solutions**:

    * Verify the **API Region** matches your Rapid7 instance
    * Check your Rapid7 InsightIDR URL for the region: `{region}.idr.insight.rapid7.com`
    * Valid regions are: us, us2, us3, eu, ca, au, ap
    * Ensure the region was entered in lowercase
  </Accordion>

  <Accordion title="No Data After 15 Minutes" icon="database">
    **Symptoms**: Integration shows active but no security event data appears

    **Solutions**:

    * Verify there is security event data in Rapid7 to collect
    * Check the API key permissions in Rapid7
    * Confirm your organisation has active threat investigations
    * Review ThreatAware integration logs (contact support if needed)
    * Wait up to 30 minutes for initial data sync to complete
  </Accordion>

  <Accordion title="Connection Timeout" icon="clock">
    **Symptoms**: Integration fails to connect or times out

    **Solutions**:

    * Verify your Rapid7 platform is accessible and online
    * Check firewall rules allow outbound HTTPS (443) to Rapid7
    * Test the region URL in a browser to ensure it's reachable
    * Verify your internet connection is stable
    * Try connecting again after waiting a few minutes
  </Accordion>
</AccordionGroup>

## Additional resources

<CardGroup cols={2}>
  <Card title="Rapid7 API Documentation" icon="book" href="https://docs.rapid7.com/">
    Official Rapid7 API documentation for detailed API information
  </Card>

  <Card title="ThreatAware Support" icon="life-ring" href="mailto:help@threataware.com">
    Contact ThreatAware support for integration assistance
  </Card>
</CardGroup>

## Best practices

<Tip>
  **API Key Management**

  * Create a dedicated API key specifically for ThreatAware
  * Document the API key location in your organisation's credential manager
  * Rotate API keys annually or per your security policy
  * Monitor for authentication failures in ThreatAware regularly
</Tip>

<Tip>
  **Security Considerations**

  * Use Organisation Keys only (never share personal API keys)
  * Limit API key scope to read-only operations
  * Review Rapid7 audit logs periodically to monitor API usage
  * Follow your organisation's principle of least privilege
</Tip>