Elisity integrates with Rapid7 InsightVM, a vulnerability management platform, as a method to enrich device discovery and identity. Once connected via API, Cloud Control Center pulls per-asset vulnerability data from InsightVM into IdentityGraph, so the vulnerability posture of each device is available alongside its other attributes when creating policies.
The connector imports the InsightVM risk score, vulnerability counts by severity, exploit and malware kit counts, and host and operating system inventory for each asset. Cloud Control Center matches InsightVM assets to devices by MAC address and by MAC address plus IP address. It displays the imported attributes on the device and makes them available as match criteria for Policy Group definition.
Prerequisites
- An InsightVM subscription on the Rapid7 Insight Platform.
- The InsightVM API URL, in the form
https://<region>.api.insight.rapid7.com. The first label of the URL is the Insight Platform region that holds your data, such as us, eu, or ca. For example,https://us.api.insight.rapid7.com. Enter the region base URL only, without an API path such as/vm/v4. - A Rapid7 Insight Platform User API key that belongs to a dedicated service account and is generated in the same region as the API URL. An API key works only in the region where it was generated. Step 1 below covers the service account and the key.
- Outbound HTTPS connectivity from Cloud Control Center to the InsightVM API address. See Platform Connectivity Requirements.
Steps to Connect Rapid7 InsightVM
Step 1. In the Rapid7 Insight Platform, create a service account and generate a User API key for the connector. The connector only reads asset data and never writes to InsightVM, so read-only access is sufficient. For more information about API keys, see the Rapid7 Managing Platform API Keys documentation.
- Create a dedicated service account user in the Insight Platform. Give it access to InsightVM with the Read Only product role.
- In InsightVM, give the service account access to all sites, or only to the sites whose assets should enrich devices in Cloud Control Center.
- Sign in to the Insight Platform as the service account and navigate to Administration > API Key Management. On the User API Keys tab, select Generate New User Key, choose the organization, and enter a name that identifies the Elisity connector.
- Copy the key immediately, because Rapid7 displays it only once. Note the Insight Platform region of the organization, which determines the API URL.
NOTE:
Use a User key on a dedicated service account, not an Organization key. An Organization key carries full administrator permissions across every Rapid7 product API, and it is not removed when the user who generated it is deleted. A User key carries only the permissions of its owner, and it stops working if that service account is deleted or deactivated.
NOTE:
Site access determines which assets the connector receives. A User key returns only the assets in sites that its owner can see. Devices whose InsightVM assets are in other sites are never enriched.
Step 2. Log into Elisity Cloud Control Center and navigate to IdentityGraph > Connectors, then select the + Add Connector button.
Step 3. A list of tiles slides out from the right side of the screen. Enter Rapid7 in the search field to filter the list, then select Configure on the Rapid7 InsightVM tile.
Step 4. On the Required Configuration tab of the Add Rapid7 InsightVM page, complete the connector fields.
| Field | Description |
|---|---|
| Endpoint Name | A name that identifies this InsightVM instance, such as InsightVM - US. Each endpoint name must be unique within the connector. |
| API URL | The base URL of your Insight Platform region, in the form https://<region>.api.insight.rapid7.com, where the first label is the region that holds your InsightVM data, such as us, eu, or ca. For example, https://us.api.insight.rapid7.com. The region must be the same region in which the API key was generated. Do not include an API path such as /vm/v4. Cloud Control Center adds the required API paths. |
| API Key | The Insight Platform API key generated in Step 1. The value is masked. When you edit an existing endpoint, the key remains masked and locked until you select the edit (pencil) icon. If you do not change it, the existing key is kept. |
NOTE:
The API URL must be the region base URL only. A URL that includes an API path, such as https://us.api.insight.rapid7.com/vm/v4, causes the connection to fail.
Step 5 (optional). Select the Advanced Settings tab to define Query Exclusion Rules and the Enrichment Lookback Window for the connector. These settings can also be changed after the connector exists.
| Setting | Description |
|---|---|
| Subnet | Enable this toggle and select the subnets to exclude. Devices attached from the selected subnets are not queried against InsightVM. Up to 100 subnets can be selected. |
| Virtual Edge Node | Enable this toggle and select the Virtual Edge Nodes to exclude. Devices connected through the selected Virtual Edge Nodes are not queried against InsightVM. Up to 100 Virtual Edge Nodes can be selected. |
| Random MAC | Enable this toggle to exclude devices that present a randomized MAC address. Randomized addresses are common on mobile, IoT, and BYOD endpoints, and they produce unreliable matches. This option is enabled by default. |
| Lookback Period | The Enrichment Lookback Window for the connector. Only InsightVM assets that were assessed for vulnerabilities within the selected period are used for enrichment. The window is measured against the last vulnerability assessment time of each asset, because Rapid7 does not report when an asset was last seen on the network. Assets are assessed less often than they are seen, which is why the default is 30 Days rather than a shorter window. Options are 1 Hour, 1 Day, 3 Days, 7 Days, 30 Days, and 90 Days. The default is 30 Days. |
Step 6. Select Add. Cloud Control Center verifies the API URL and API Key against InsightVM before it creates the connector. If verification fails, correct the API URL or API Key and select Add again.
A tenant can connect up to six Rapid7 InsightVM instances. Because an API key works only in the region where it was generated, connect a separate instance for each Insight Platform region that holds your InsightVM data. Repeat Steps 2 through 6 for each instance and give each one a distinct Endpoint Name. Each instance appears as an endpoint nested beneath the Rapid7 InsightVM row in the Connectors list. Select the expand arrow on the row to display them. Each endpoint enriches devices independently, and its Actions (⋮) menu provides Edit Endpoint and Delete Endpoint.
Advanced Settings
Two surfaces control how Cloud Control Center queries the Rapid7 InsightVM connector and how the data it returns is used. Query Exclusion Rules and the Enrichment Lookback Window are configured on the Advanced Settings tab of the connector itself. Connector Data Purging, Trusted Connector, and Initial Delay are configured in the Global Settings dialog for the connector.
Query Exclusion Rules and Enrichment Lookback Window
To change these settings after the connector exists, navigate to IdentityGraph > Connectors and expand the Rapid7 InsightVM row. Select Edit Endpoint from the Actions (⋮) menu of an endpoint, open the Advanced Settings tab, update the settings described in Step 5, and select Save Changes.
NOTE:
The Enrichment Lookback Window is shared by all Rapid7 InsightVM endpoints. Changing the Lookback Period while adding or editing one endpoint changes it for every endpoint of the connector.
Global Settings
To open the Global Settings dialog, navigate to IdentityGraph > Connectors, locate the Rapid7 InsightVM connector, and select Global Settings from the row's Actions (⋮) menu.
| Setting | Description |
|---|---|
| Connector Data Purging | When enabled, Cloud Control Center purges all data learned about a device from this connector if the device is no longer found when querying the connected application. Set the interval between purge events with the Time Period selector, which accepts a value between 1 and 90 days. The connector status changes from Up to Date to Stale if the device is no longer known by the connector but prior to the purge event. Disabled by default. |
| Trusted Connector | When enabled, enrichment from this source is set to Trusted for Policy Groups, and the connector is designated an authoritative identity source for Insights. Disabled by default. |
| Initial Delay | The delay in seconds before Cloud Control Center initiates the first query to the connector after initially discovering a new device. Default is 0 seconds. |
Connector Status
The connector status reflects its health and availability based on recent query performance. To ensure accuracy and reduce false positives, the status is determined using a rolling 15-minute evaluation window. The current status is displayed in the Status column of the Connectors list.
Connector Status Levels:
- Active: Normal operation with minimal query failures.
- Degraded: Increased query failures detected, but the connector is still operational.
- Inactive: The connector is unresponsive due to persistent failures.
Failures are defined as unsuccessful query responses, and the platform continuously monitors performance to update the status accordingly. These status changes are visible in the UI, event logs, and notifications pane for better troubleshooting. Email alerts can also be configured for connector status changes. If the connector has not been queried within the evaluation window, the last known status is retained.
Troubleshooting
The following table lists common Rapid7 InsightVM connector issues and how to resolve them.
| Symptom | Likely Cause | Check |
|---|---|---|
| Verification fails with a 401 error when you select Add. | The API key is invalid or has been deleted, or it was generated in a different region from the API URL. | Confirm that the key still exists under API Key Management in the Insight Platform, and that the region in the API URL matches the region in which the key was generated. |
| Verification succeeds, but no assets arrive, or Rapid7 returns a 404 error. | The owner of the key lacks InsightVM read access or site access. Rapid7 returns 404, not 403, when a valid key cannot read a resource. | Check the product role and the site access of the service account in the Insight Platform. |
| Fewer devices are enriched than expected. | The site access of the service account is limited, the Lookback Period is too short, the assets have no MAC address, or the assets have not been assessed recently. | Check the site access of the service account and the Lookback Period of the connector. Confirm that the missing assets have a MAC address and a recent vulnerability assessment in InsightVM. |
| The connector stops working after a change to Rapid7 user accounts. | User keys stop working when their user is deleted or deactivated. | Confirm that the service account still exists and is active in the Insight Platform. If it was removed, create a new service account and key, then edit the endpoint and enter the new API Key. |
Leveraging Rapid7 InsightVM with Elisity
When the Rapid7 InsightVM connector is active, Cloud Control Center retrieves InsightVM asset data on a regular schedule and enriches devices from it as soon as Elisity discovers them on the network. Changes in InsightVM, such as the results of a new scan, are reflected on matched devices within minutes. This enriched data is displayed on the IdentityGraph tab of the device.
Matched devices display Known in Rapid7 InsightVM under KNOWN IN in the Trust Attributes section, and the attributes InsightVM contributes are listed on the Rapid7 InsightVM source card.
The following asset attributes are imported from InsightVM. Attributes marked Yes in the Policy Group Match Criteria column can also be selected as match criteria when defining a Policy Group. The remaining attributes are displayed in IdentityGraph for visibility and troubleshooting but are not available in the Policy Group builder.
| Attribute | Description | Policy Group Match Criteria |
|---|---|---|
| Hostname | The host name InsightVM reports for the asset. Populates the Hostname Core Effective Attribute. | Yes |
| id | The unique identifier InsightVM assigns to the asset. | Yes |
| Rapid7 Type | Whether InsightVM reports the asset as a physical host or a virtual guest, such as physical or guest. | Yes |
| Operating System | The operating system name InsightVM reports for the asset. Populates the Operating System Core Effective Attribute. | Yes |
| OS Description | The full operating system description, such as Microsoft Windows 10 22H2. | Yes |
| Type | The InsightVM operating system type, such as Workstation or Server. Populates the Type Core Effective Attribute. | Yes |
| Risk Score | The InsightVM risk score for the asset, as a decimal number. | Yes |
| Critical Vulnerabilities | The number of critical-severity vulnerabilities found on the asset. | Yes |
| Severe Vulnerabilities | The number of severe-severity vulnerabilities found on the asset. | Yes |
| Moderate Vulnerabilities | The number of moderate-severity vulnerabilities found on the asset. | Yes |
| Total Vulnerabilities | The total number of vulnerabilities found on the asset. | Yes |
| Exploits | The number of known exploits InsightVM reports for the vulnerabilities on the asset. | Yes |
| Malware Kits | The number of malware kits InsightVM reports for the vulnerabilities on the asset. | Yes |
| Assessed for Vulnerabilities | Whether InsightVM has assessed the asset for vulnerabilities. Values are true and false. | Yes |
| Assessed For Policies | Whether InsightVM has assessed the asset for policy compliance. Values are true and false. | Yes |
| Tags | The names of the tags applied to the asset in InsightVM. An asset can have multiple values. | Yes |
| Unique Identifiers | Identifiers that agents and other sources report for the asset, each shown in the form source:identifier. An asset can have multiple values. | Yes |
| Matched on | How Cloud Control Center matched the device to an InsightVM asset. Values are MAC and MAC+IP. | No |
| Last Update | The time at which Cloud Control Center last refreshed this device's attributes from InsightVM. | No |
| Status | The freshness of the attributes contributed by this connector for the device. Values are Up to date and Stale. | No |
NOTE:
The MAC address and IP address values reported by InsightVM are used to match InsightVM assets to devices in IdentityGraph. They are not surfaced as InsightVM attributes on the device. InsightVM matching supports MAC + IP and MAC lookups; IP-only lookups are not supported. InsightVM assets without a MAC address are not used for enrichment.
Risk Score and the vulnerability, exploit, and malware kit counts are numeric and change as InsightVM rescans assets. When you use them as Policy Group match criteria, match them against a threshold, such as greater than or less than a value, rather than an exact value.
To manage enrichment for an individual device, select the options menu on the Rapid7 InsightVM source card and choose one of the following.
- Refresh Attributes: Queries InsightVM immediately and updates the attributes contributed to this device.
- Purge Attributes: Removes the attributes this connector contributed to this device.
To learn more about how to leverage IdentityGraph Core Effective Attributes, review the IdentityGraph article. To learn more about how to leverage IdentityGraph Trust Attributes, review Leveraging Trust Attributes for Policy Group Definition.