Skip to main content

Rapid7: Overview and Setup

Sync Rapid7 investigations with Atomicwork incidents

R
Written by Riya Sebastian
Updated over a week ago

The Atomicwork–Rapid7 InsightIDR integration enables automatic syncing of Rapid7 incidents with your Atomicwork account. This integration ensures that any new investigation triggered in Rapid7 automatically creates a corresponding incident request in your configured Atomicwork workspace, streamlining communication between security and IT teams. This is not a 2 way sync at the moment so context from Atomicwork will not be synced automatically and needs to be synced via workflows.

Permissions

The integration setup owner needs to have access to a Rapid7 Platform Admin account and an Atomicwork admin account.

Setup

Webhook configuration in Rapid7 and Atomicwork

  1. Log in to the Atomicwork portal. Click Settings in the bottom-left corner.

  2. Navigate to Integrations > App Store > Rapid7 InsightIDR.

  3. You need to provide an API Key and Region from Rapid7. Open the Rapid7 platform and from the left navigation panel, select Administration > API Key Management > Organization Key.

  4. Click Generate New Organization Key. Select the required Organization and enter a name for the API key. Click Submit.

  5. Copy and save the generated Organization API key securely. Paste the Rapid7 Organization API Key you generated and select the appropriate Rapid7 region.

  6. After saving, the Webhook Configuration section will appear automatically. Save the displayed Webhook URL for use in the Rapid7 Data Exporter.

  7. Open the Rapid7 home screen. In the left panel under Solutions, select SIEM > Data Collection.

  8. Use the top navigation bar to switch to Data Exporters > Add Data Exporter.

  9. Fill out the form as per these specifications.

    1. Select a Collector.

    2. Set Data Exporter Type to Universal Webhook.

    3. Enter a name for the data exporter.

    4. Paste the Webhook URL copied from Atomicwork into the URL field.

  10. After entering the URL, copy the auto-generated Secret value. Do NOT hit Save.

Important: Do not save the configuration in Rapid7 yet. You must complete the Atomicwork configuration first because Rapid7 sends a test event upon saving, which requires the Atomicwork side to be ready.

Configure the webhook secret in Atomicwork

  1. Paste the Secret copied from Rapid7 into the Webhook Secret field in Atomicwork.

  2. Select the target workspace where Rapid7 incidents should be created.

  3. Click Save to complete the configuration in Atomicwork.

Generate an Atomicwork public API key

  1. In Atomicwork, click the Profile icon in the top-right corner.

  2. Select Public API Token > Generate New Token. Copy the generated token. Rapid7 will use this token for webhook authentication.

  3. Return to the Rapid7 Data Exporter configuration page. In the Headers section, add a new header:

    1. Key: X-Api-Key

    2. Value: Paste the Atomicwork Public API token generated in the previous step.

  4. Now, you can Save your configuration. Upon saving, Rapid7 will trigger a test event. This process creates three custom request attributes in Atomicwork:

    1. External Sync ID

    2. External Sync Source

    3. External Sync Type

Supported workflow actions

  • Get Investigations. This action retrieves information about Rapid7 investigations from Rapid7. You need to provide the Rapid7 Investigation ID to enable this action.

  • Update Investigation. This action updates Investigation fields in Rapid7. Once you provide the Investigation ID, you can update Rapid7 fields.

Troubleshooting

If you encounter issues, please verify the API keys and Webhook secrets. Generate again and reconnect if you do not have a saved copy to confirm.

Did this answer your question?