
Rapid7 InsightVM (for CTEM)
Outline
About this document
This document provides step-by-step instructions to configure the Rapid7 InsightVM integration in SAFE and pull the assets that Rapid7 InsightVM Cloud scans, with their vulnerabilities, into SAFE.
Introduction
The SAFE integration with Rapid7 InsightVM ingests the hosts that InsightVM Cloud knows about (host name, IP address, MAC address, operating system, tags and last assessment time) and the vulnerabilities found on each of them. SAFE admins can configure this integration from the "Rapid7 InsightVM" card available on the SAFE Platform Integrations page.
SAFE uses AI to aggregate, normalise and deduplicate the ingested data from Rapid7 InsightVM, along with information from your existing IT and cybersecurity tools. This creates a unified view of your entire asset inventory, including its operational and business context.
Data pulled from Rapid7 InsightVM
| Assets | Host devices assessed by Rapid7 InsightVM Cloud: servers, virtual machines, desktops and laptops, discovered by a scan or by the Insight Agent. |
| Data | Host name, IP address, MAC address (when Rapid7 discovered one), operating system name, version, vendor, family and architecture, last assessment time, and Rapid7 tags (SITE, CRITICALITY, LOCATION, OWNER and custom tags). A LOCATION tag also fills the asset location and an OWNER tag fills the device owner. |
| Findings | Vulnerability findings, for CVE and non-CVE checks: name, CVE ID, severity, status, first and last found dates, port, protocol, description and remediation (solution) text. SAFE creates one finding per CVE, and one finding per check for checks that have no CVE. |
| Asset Matching Criteria | hostName |
| Sync Mode | Full sync on every run. No delta / incremental sync. |
| What Not Fetched | Hardware details (manufacturer, model, serial number, BIOS, CPU, memory), compliance (policy) results, and a standalone software inventory. The Rapid7 v4 Integrations API does not provide them. |
Prerequisites and Permissions
A Rapid7 Insight Platform organization with InsightVM Cloud (Vulnerability Management) data.
A Rapid7 Insight Platform user who can view that organization's vulnerability management sites, assets and vulnerabilities. The API key inherits that user's permissions.
The region of your Rapid7 organization (for example
us2).SAFE access with an admin role.
Outbound HTTPS (port 443) connectivity from SAFE to
<region>.api.insight.rapid7.com. SAFE connects to Rapid7; nothing needs to connect to SAFE and no agent is installed.
Generate connection details
To integrate SAFE with Rapid7 InsightVM, you need 2 details:
Rapid7 API Base URL
API Key
Find your Rapid7 API Base URL
Sign in to the Rapid7 Insight Platform and open Vulnerability Management.
Note the region: it is the first part of your Vulnerability Management URL. For example,
us2inus2.exposure-analytics.insight.rapid7.com.Your API Base URL is
https://<region>.api.insight.rapid7.com, for examplehttps://us2.api.insight.rapid7.com.
Rapid7 names these regions: us, us2, us3, eu, ca, au, ap, me1 and aps2. If the region does not match your organization, Rapid7 answers with no data, so use the region your organization is hosted in.
Generate an API key
SAFE authenticates with a Rapid7 Insight Platform API key sent in the X-Api-Key header. A user key is recommended: it can only see what its user can see, and any user can create one for an organization they have access to. An organization key also works, but it is a platform-wide key that can do everything across all Rapid7 products and can only be created by an administrator, so it gives SAFE more access than it needs.
Sign in to the Rapid7 Insight Platform and open Command Home.
Go to Administration > API Key Management and open User API Keys.
Click Generate New User Key.
Select your organization and enter a name for the key (for example,
SAFE).Click Save, then copy the key. Rapid7 shows the key only once; it cannot be retrieved later.
Click Done. Store the key securely. If the key is deleted, or the user behind it loses access to Vulnerability Management, update the SAFE integration as well, otherwise syncs will start failing.
Configure the Rapid7 InsightVM integration in SAFE
Navigate to Knowledge Graph > First Party > Integrations.
Click the + icon on the top right corner of the page and search for Rapid7 InsightVM.
Click the Rapid7 card to configure it.
Enter the integration name.
Enter the Rapid7 API Base URL. Example:
https://us2.api.insight.rapid7.comEnter the API Key.
[Optional] Enter the comma separated Rapid7 site names. When defined, only assets that belong to those sites are imported in SAFE. When empty, all assets are imported.
Enter the Asset last seen days filter. Only assets assessed within this many days are imported.
Enter the Auto Sync Frequency in number of days.
Click Test Connection once you have entered the credentials.
Once verified, click Save to save the integration.
Once the integration is saved, click Sync Now to trigger an on-demand sync.
Notes:
Rapid7 API Base URL can be pasted with a trailing
/; SAFE removes it. Any URL that is nothttps://<region>.api.insight.rapid7.comis rejected.Site Name takes site names exactly as they appear in Rapid7, separated by commas, for example
Prod, Dev. Enter the names only: do not add a prefix such asSite=. Names are matched ignoring upper and lower case, and surrounding spaces and quotes are ignored. A name that matches no Rapid7 site is skipped and reported.Asset last seen days filter keeps assets that were not assessed recently out of SAFE.
View Result
To view the assets and their findings:
From the SAFE Integrations page, click on the Rapid7 InsightVM card.
A page with the integration's assets and findings opens.
The asset list shows the hosts pulled or updated from Rapid7 InsightVM, with their name, IP address, operating system and last seen time.
Open an asset to see its network interface, operating system details, Rapid7 tags and its findings, and the integration on the Sources tab.
The findings list shows each vulnerability with its CVE, severity and the asset it was found on.
API Details
The Rapid7 InsightVM connector uses the Rapid7 Insight Platform Integrations API (v4). Authentication is an API key sent on every call in the X-Api-Key header. Every call is read-only: the search calls use POST only to carry search criteria, and nothing is written to Rapid7.
| API | Method | Endpoint | Purpose |
|---|---|---|---|
| Validation | GET | /validate |
Confirm the API Base URL (region) and the key are valid. Used by Test Connection. |
| Sites | POST | /vm/v4/integration/sites |
List Rapid7 sites so the Site Name filter can be matched. Called only when Site Names are set. Page size 500. |
| Assets | POST | /vm/v4/integration/assets |
Fetch assets together with their findings. Page size 50, cursor pagination, sorted by ID. The last-seen and Site Name filters are sent as search criteria. |
| Vulnerabilities | POST | /vm/v4/integration/vulnerabilities |
Fetch the details (title, CVEs, CVSS scores, severity, description, exploits) of the vulnerabilities the fetched assets reference, requested by ID in batches of 100. |
SAFE retries rate-limited requests and temporary Rapid7 server errors automatically. If Rapid7 refuses a request outright, the sync fails and reports the error.
FAQs
Q: How frequently does SAFE sync data from Rapid7 InsightVM?
A: Sync frequency depends on the Auto Sync configuration. Default is every 7 days. You can also trigger an on-demand sync at any time using Sync Now.
Q: Does the integration support incremental / delta sync?
A: No. Every run is a full sync of all assets that pass the filters. Use the Asset last seen days filter or the Site Name filter to reduce the volume.
Q: Test Connection fails.
A: Use the message shown in section 5. Common causes are an API Base URL region that does not match the Rapid7 organization, a key that was copied incompletely (Rapid7 shows it only once), or a key whose user has no access to Vulnerability Management.
Q: The sync completed but no assets appeared.
A: Check, in this order: the API Base URL region; that the key's user can see assets in Vulnerability Management; the Site Name filter; and the Asset last seen days filter. Assets that Rapid7 last assessed for vulnerabilities longer ago than the filter are not imported, and the default is 30 days. Increase the value or leave it empty. The sync's completion message tells you when Rapid7 returned no assets or when no Site Name matched.
Q: Fewer assets appear in SAFE than in Rapid7.
A: The Asset last seen days filter and the Site Name filter limit the import. SAFE also merges the same host reported by Rapid7 and by your other integrations into one asset, so the SAFE count can be lower than the Rapid7 count.
Q: How do I enter the Site Name filter?
A: Enter the site names only, separated by commas, for example Prod, Dev. Do not add a prefix such as Site=. Matching ignores upper and lower case. If one name matches no site, the sync still imports the matching sites and completes with a message naming the one that matched nothing.
Q: An asset's name in SAFE is an IP address.
A: SAFE decides the displayed name. When Rapid7 has no host name for the asset, or the host name only repeats the IP address (for example ip-172-31-42-3), SAFE names the asset after its IP address.
Q: The operating system vendor in SAFE differs from Rapid7 (for example Ubuntu shows as Canonical).
A: SAFE normalises the operating system vendor, so an Ubuntu host is shown with its publisher, Canonical.
Q: Why do I see no hardware details, compliance results or full software list?
A: The Rapid7 v4 Integrations API does not provide manufacturer, model, serial number, BIOS, CPU or memory, policy (compliance) results, or a standalone software inventory. Only the software named in a finding's evidence is shown, on that finding.
Q: A Rapid7 vulnerability is missing in SAFE.
A: Only findings with a status of vulnerable, potentially vulnerable or exception are imported (section 5). Checks that found nothing, were skipped or did not run are not.
Q: The same vulnerability appears more than once on one asset.
A: SAFE creates one finding per CVE and per port. A check that lists several CVEs, or that was found on several ports, appears once for each. The same check repeated across a host's network interfaces on the same port appears once.
Q: Why does the same vulnerability show a different severity in SAFE than in Rapid7?
A: The severity in section 5 is the starting value. SAFE recalculates the final severity using its threat intelligence for the CVE and the context of each asset.
Q: What happens to a finding Rapid7 marks as an approved exception?
A: It is imported with the status Mitigated.
Q: How are duplicate assets handled?
A: Assets are matched and deduplicated on hostName, together with the same devices from your other integrations.
Q: Does the integration change anything in Rapid7?
A: No. It is read-only.
Q: Can historical data be re-ingested?
A: Yes. Every sync is a full fetch, so triggering a new sync re-ingests all assets that pass the filters.
API reference documentation
Did this article help?
Let us know by leaving a star rating at the top of this article.
