Rapid7 InsightVM

Rapid7 InsightVM is the vulnerability-scanner source. The integration pulls scanned assets, the vulnerability findings on each asset, and (where available) the installed-software inventory per asset. It follows the shared integration lifecycle.

• Router: app/api/v1/endpoints/rapid7.py, mounted at /api/v1/rapid7
• Client: src/vulnmgmt/integrations/rapid7/client.py (Rapid7Client)
• Config collection: rapid7_config (keyed by tenant_id)

Authentication

Rapid7 uses a platform API key plus a region. The region selects the regional Insight API host; the key is sent in the X-Api-Key header.

X-Api-Key: <api_key>
Base URL: https://<region>.api.insight.rapid7.com   (us, us2, us3, eu, ca, au, ap)

Config fields (Rapid7ConfigIn):

Field	Meaning
api_key	Rapid7 platform API key (user or org key)
region	Insight region — us (default), us2, us3, eu, ca, au, ap
organization_id	Optional organization id
enabled	Whether the integration is active

Env seeding (_seed_rapid7_config) reads RAPID7_API_KEY, RAPID7_REGION and optional RAPID7_ORG_ID. test-connection posts to /validate.

What the sync pulls

The background _run_sync builds cross-reference maps from Intune and SentinelOne (by hostname, matching both the full and short/FQDN-stripped name), then works in phases:

1. Assets — get_assets(fetch_all=True) pages the v4 integration API. Each asset is bulk-upserted into rapid7_assets with risk score, vuln counts (total / critical / severe), OS family, IP/MAC, last scan date, and the matched intune_device_id / s1_agent_id / owner. Interim stats are written after this phase so the UI shows data while findings still load.

2. Findings + software (batched, 20 assets per batch) — for each asset:

   • Vulnerability findings via get_asset_vulnerabilities(asset_id) (uses GET /assets/{id}?includeSame=true) → upserted into rapid7_findings (status, first/last found, proof, solution summary/type).
   • Installed software via get_asset_software(asset_id) (/vm/v4/assets/{id}/software) → upserted into inventory_items tagged source="rapid7" so it joins the Software rollup.

   Progress is written to sync_progress on the config doc each batch (phase, current/total batch, assets processed, finding count).

Data	Written to
Assets	rapid7_assets
Per-asset vulnerability findings	rapid7_findings
Per-asset installed software	inventory_items (source=rapid7)

Stale assets, findings and inventory rows (whose IDs are no longer live) are deleted, then rebuild_applications refreshes the Software rollup.

Software circuit breaker

Some InsightVM instances don’t expose the per-asset /software sub-resource (it returns 404). Rather than hammer it for every asset — each with a rate-limit sleep — the sync tracks consecutive failures and disables software collection after 15 in a row, logging a single notice. Findings collection continues normally; only software is skipped for the rest of that run.

Stale-sync guard on sync-status

Because the sync runs in-process, a backend restart mid-sync would otherwise leave sync_status stuck at running forever. GET /sync-status guards against this: if the status is running but sync_started_at is more than 20 minutes old, it flips the status to error (“Sync was interrupted (service restart)…”) and clears sync_progress, so the UI recovers and the operator can re-run.

Routes

Method	Path	Purpose
GET / POST / DELETE	/api/v1/rapid7/config	Get / save / remove config
POST	/api/v1/rapid7/test-connection	Live credential test
POST	/api/v1/rapid7/sync	Start a background sync
GET	/api/v1/rapid7/sync-status	Poll status (with stale-sync guard + progress)
GET	/api/v1/rapid7/stats	Summary counts, severity totals, OS breakdown
GET	/api/v1/rapid7/assets	List synced assets
GET	/api/v1/rapid7/findings/{asset_id}	Findings for one asset
GET	/api/v1/rapid7/apps	Installed apps aggregated by name
GET	/api/v1/rapid7/device-by-name/{hostname}	Asset record by hostname (full or short)
POST	/api/v1/rapid7/research-finding	Extract the CVE from a finding slug, look it up in NVD, save to vulnerabilities

See the overview for the lifecycle these routes share.