Rapid7

Rapid7 InsightVM Integration

Overview

The Rapid7 InsightVM integration syncs assets and vulnerabilities from Rapid7 InsightVM into RegScale. It supports both on-premises Console API v3 (HTTP Basic Auth) and InsightVM Cloud Integrations API v4 (API key), with automatic pagination, vulnerability enrichment, and site-based filtering.

---

Prerequisites

• RegScale CLI installed and configured (regscale init)
• One of the following:
  • Console (on-prem): Network access to the InsightVM Security Console (default port 3780), a user account with at least Security Manager role
  • Cloud: A valid InsightVM Cloud API key from the Insight Platform
• An existing RegScale Security Plan or Component to sync into

---

Configuration

Add the following variables to your init.yaml file (created by regscale init):

Variable	Type	Required	Default	Description
rapid7DeploymentType	string	No	console	"console" for on-prem v3 API, "cloud" for InsightVM Cloud v4 API
rapid7Url	string	Console only	—	Console base URL (e.g., https://insightvm.company.com:3780)
rapid7Username	string	Console only	—	Console user with Security Manager permissions
rapid7Password	string	Console only	—	Console user password
rapid7VerifySsl	bool	No	true	Verify SSL certificates (Console only)
rapid7ApiKey	string	Cloud only	—	InsightVM Cloud API key
rapid7Region	string	Cloud only	us	Cloud region: us, us2, us3, eu, ca, au, ap
rapid7SiteIds	string	No	"" (all sites)	Comma-separated site IDs to filter (Console only)
rapid7PageSize	int	No	500	Page size for API pagination (max 500 for v3, max 1000 for v4)

Console (On-Prem) Example

YAML

rapid7DeploymentType: "console"
rapid7Url: "https://insightvm.company.com:3780"
rapid7Username: "regscale-service-account"
rapid7Password: "your-password"
rapid7VerifySsl: true
rapid7SiteIds: ""
rapid7PageSize: 500

Cloud Example

YAML

rapid7DeploymentType: "cloud"
rapid7ApiKey: "your-insight-platform-api-key"
rapid7Region: "us"
rapid7PageSize: 1000

---

Commands

Test Connection

Verify that the configured Rapid7 credentials are valid and the API is accessible.

Bash

regscale rapid7 test_connection

Sync Assets

Fetch all assets from Rapid7 InsightVM and synchronize them into the specified RegScale record.

Bash

regscale rapid7 sync_assets --regscale-id <ID> --regscale-module <MODULE>

Options:

Flag	Short	Description
--regscale-id	-id	RegScale record ID (Security Plan or Component)
--regscale-module	-m	RegScale module (securityplans, components)

Sync Findings

Fetch vulnerabilities from Rapid7 InsightVM and synchronize them as findings into the specified RegScale record.

Bash

regscale rapid7 sync_findings --regscale-id <ID> --regscale-module <MODULE>

Sync All

Synchronize both assets and findings in a single operation. Assets are synced first so that findings can be linked to the correct assets.

Bash

regscale rapid7 sync_all --regscale-id <ID> --regscale-module <MODULE>

---

How It Works

Asset Synchronization

1. Fetches all assets (or assets from specified sites) via the Rapid7 API
2. Maps Rapid7 asset fields to RegScale IntegrationAsset objects
3. Uses otherTrackingNumber (Rapid7 asset ID) as the unique identifier for deduplication
4. Creates or updates assets in the target RegScale Security Plan or Component

Asset field mapping:

Rapid7 Field	RegScale Field	Notes
id	otherTrackingNumber	Unique identifier for deduplication
hostName	fqdn, name	Falls back to IP if hostname is empty
ip / addresses[].ip	ipAddress	First available IP address
addresses[].mac	macAddress	First available MAC address
os.family	operatingSystem	Mapped to RegScale OS enum
os.version	osVersion	—
os.cpe.v2.3	cpe	CPE v2.3 string
type	assetType	hypervisor/guest → VM, physical → Physical Server
riskScore	—	Used internally for prioritization
tags[].name	description	Comma-separated tag names

Vulnerability Synchronization

Console API v3 (Two-Step Enrichment)

The Console API v3 uses a two-step process because the per-asset vulnerability endpoint (GET /api/3/assets/{id}/vulnerabilities) returns lightweight VulnerabilityFinding objects that only contain:

• id (vulnerability ID string)
• status (e.g., vulnerable, vulnerable-version)
• since (first detection timestamp)
• port, protocol, proof

Full vulnerability details (title, description, CVSS scores, CVEs, severity, solutions) are not included in the per-asset response. The integration enriches each finding by calling GET /api/3/vulnerabilities/{id} and caching the results so each vulnerability definition is fetched at most once.

Flow:

1. Iterate over cached assets
2. For each asset, fetch lightweight vulnerability findings
3. For each unique vulnerability ID, fetch full definition (cached)
4. Merge finding-level data (status, proof, port) with definition-level data (title, CVSS, CVEs)
5. Map to RegScale IntegrationFinding objects

Cloud API v4

The Cloud API v4 returns full vulnerability details in a single response from POST /vm/v4/integration/vulnerabilities, so no enrichment step is needed.

Vulnerability field mapping:

Rapid7 Field	RegScale Field	Notes
id	pluginName, pluginId	Rapid7 vulnerability ID string
title	title	—
description	description	Text content (HTML stripped)
cvss.v3.score	cvssV3Score	Preferred for severity mapping
cvss.v2.score	cvssV2Score	Fallback if v3 not available
cvss.v3.vector	cvssV3Vector	—
cves[0]	cve	First CVE identifier
severity	severity	Critical/Severe/Moderate → RegScale severity
status	status	vulnerable → Open, not-vulnerable → Closed
solutions[0].fix	remediation	First available fix
proof	evidence	HTML-formatted proof of exploitation
since	firstSeen	First detection date

Severity mapping:

CVSS Score	RegScale Severity
> = 9.0	Critical
> = 7.0	High
> = 4.0	Moderate
< 4.0	Low

If no CVSS score is available, the Rapid7 severity label is used:

Rapid7 Severity	RegScale Severity
Critical	Critical
Severe	High
Moderate	Moderate

---

API Compatibility

Console API v3

Feature	Status	Notes
HTTP Basic Auth	Supported	Username/password from init.yaml
Asset listing	Supported	GET /api/3/assets with page-based pagination
Site-filtered assets	Supported	GET /api/3/sites/{id}/assets
Per-asset vulnerabilities	Supported	GET /api/3/assets/{id}/vulnerabilities (lightweight findings)
Vulnerability details	Supported	GET /api/3/vulnerabilities/{id} (full definitions, cached)
Site listing	Supported	GET /api/3/sites
Connection test	Supported	GET /api/3/administration/info
Max page size	500	Enforced by Rapid7 API

Cloud Integrations API v4

Feature	Status	Notes
API key auth	Supported	X-Api-Key header
Asset listing	Supported	POST /vm/v4/integration/assets with cursor-based pagination
Vulnerability listing	Supported	POST /vm/v4/integration/vulnerabilities
Connection test	Supported	POST /vm/v4/integration/assets with size=1
Max page size	1000	Enforced by Rapid7 API

Supported Cloud Regions

Region Code	Location
us	United States (default)
us2	United States 2
us3	United States 3
eu	Europe
ca	Canada
au	Australia
ap	Asia Pacific (Japan)

Additional regions (me1 for UAE, aps2 for India) may be available — check Rapid7 documentation for the latest list.

---

Site Filtering

For Console deployments, you can restrict the sync to specific scan sites by setting rapid7SiteIds in init.yaml:

YAML

rapid7SiteIds: "1,3,5"

When set, only assets belonging to the specified sites are fetched. When empty (default), all assets across all sites are returned.

---

Performance Considerations

• Vulnerability detail caching: Each unique vulnerability definition is fetched once and cached in memory for the duration of the sync. With 200 unique vulnerability definitions across 500 assets, this results in ~200 API calls instead of ~5000
• Page size: Set rapid7PageSize to the maximum supported value (500 for Console, 1000 for Cloud) to minimize the number of pagination requests
• Asset pre-loading: When running sync_findings without a prior sync_assets, the integration automatically pre-loads all assets to enable finding-to-asset linkage
• Batch operations: Assets and vulnerabilities are submitted to RegScale in batches for efficient processing

---

Troubleshooting

Issue	Solution
Authentication failed	Verify rapid7Username/rapid7Password (Console) or rapid7ApiKey (Cloud) in init.yaml
Authorization failed - insufficient permissions	Console user needs at least Security Manager role
SSL certificate verify failed	Set rapid7VerifySsl: false for self-signed certs (Console only)
Connection refused	Verify rapid7Url is correct and Console is accessible on port 3780
Findings have no title/CVSS/CVE	Ensure GET /api/3/vulnerabilities/{id} is accessible (Console)
Empty results with site filter	Verify site IDs exist via GET /api/3/sites
Cloud API returns 401	Regenerate API key from Insight Platform
Slow vulnerability sync	Expected for Console — each unique vuln requires a detail lookup. Subsequent syncs benefit from deduplication

---

Changelog

• Initial release: Asset and vulnerability synchronization for Console API v3 and Cloud API v4
• Vulnerability enrichment: Per-asset vulnerability findings are enriched with full definitions from the vulnerability details endpoint (Console v3)
• Page size optimization: Cloud API v4 supports up to 1000 records per page (v3 remains capped at 500)