Skip to main content

Rapid7 InsightVM

Rapid7 InsightVM is a vulnerability management tool that provides visibility into potential vulnerabilities associated with your assets. You can bring asset and security data from Rapid7 InsightVM into Brinqa, combining the vulnerability management capabilities of Rapid7 InsightVM with the risk management and prioritization capabilities of Brinqa, to gain a comprehensive view of your attack surface and strengthen your cybersecurity posture.

This document details the information you must provide for the connector to authenticate with Rapid7 InsightVM and how to obtain that information from Rapid7. See create a data integration for step-by-step instructions on setting up the integration.

Required connection settings​

When setting up a data integration, select Rapid7 InsightVM from the Connector drop-down. If you cannot find the connector in the drop-down, make sure that you have installed it first. You must provide the following information to authenticate Rapid7 InsightVM with Brinqa:

  • API URL: The Rapid7 InsightVM API URL. The URL format is https//<region>.api.insight.rapid7.com.

    info

    Replace <region> with the specific region your Rapid7 InsightVM server is located in. For example, if your server is in the United States, the API URL might be https://us.api.insight.rapid7.com/.

    You can find your region by checking the Insight platform Home page as described in Rapid7's documentation. For a list of supported regions and corresponding URLs, please refer to the Rapid7 Insight API documentation.

  • API key: The access key associated with the Rapid7 InsightVM account, which must have permissions to log in to the API server and return data.

Create a Rapid7 InsightVM API key​

For the Rapid7 InsightVM connector to use the Rapid7 InsightVM API, you must provide the API key from Rapid7. There are two types of API keys for Rapid7 InsightVM:

  • User key: The user key is tied to a specific user account and can be used to authenticate API requests made by that user. The user key inherits the permissions of the user who creates the API key.

  • Organization key: The organization key is tied to an organization as a whole. An organization key can be used to authenticate API requests and also provides access to all data within the organization, including assets, vulnerabilities, and reports. Only administrators can create organization API keys.

To generate a user API key, follow these steps:

  1. Log in to your organization's Rapid7 InsightVM account as an administrator.

  2. Navigate to API Keys > User Key and then click New User Key.

  3. Select a user and provide a name for the key.

    The new user API key displays. You cannot view the key again. Copy the API key and save it in a secure location.

To generate an organization API key, follow these steps:

  1. Log in to your Rapid7 InsightVM account as an administrator.

  2. Navigate to API Keys > Organization Key and click New Organization Key.

  3. Select an organization and provide a name for the key.

    The new organization API key displays. You cannot view the key again. Copy the API key and save it in a secure location.

note

The above steps describe the minimum requirements for the Rapid7 InsightVM connector to work properly. For additional information, see Rapid7 Documentation.

Additional settings​

The Rapid7 InsightVM connector contains additional options for specific configuration:

  • Page size: The maximum number of records to get per API request. The default setting is 500. It is not recommended to go over 500.

  • Parallel requests: The maximum number of parallel API requests. The default setting is 8.

  • Maximum retries: The maximum number of times that the integration attempts to connect to the Rapid7 InsightVM API before giving up and reporting a failure. The default setting is 5.

Types of data to retrieve​

The Rapid7 InsightVM connector can retrieve the following types of data from the InsightVM API:

Table 1: Data retrieved from Rapid7 InsightVM

Connector ObjectRequiredMaps to Data Model
HostYesHost
VulnerabilityYesVulnerability
Vulnerability DefinitionYesVulnerability Definition
info

The Rapid7 InsightVM connector does not currently support operation options for the types of data it retrieves.

For detailed steps on how to view the data retrieved from Rapid7 InsightVM in the Brinqa Platform, see How to view your data.

Attribute mappings​

Click the tabs below to view the mappings between the source and the Brinqa data model attributes.

Table 2: Host attribute mappings

Source Field NameMaps to Attribute
asset.assessed_for_policiesLocal variable
asset.credential_assessmentsLocal variable
asset.host_namehostnames, publicDnsName, privateDnsName
asset.iduid
asset.ippublicIpAddress, ipAddresses, privateIpAddresses
asset.last_assessed_for_vulnerabilitieslastSeen, lastScanned
asset.macmacAddresses
asset.os_architectureLocal variable
asset.os_familyLocal variable
asset.os_nameLocal variable
asset.os_system_nameLocal variable
asset.os_typeLocal variable
asset.os_vendorLocal variable
asset.os_versionLocal variable
asset.risk_scoreLocal variable
asset.tagstags
asset.typecategories
asset.unique_identifiers.idLocal variable
descriptiondescription
namename
operating systemos
statusstatus
unique_identifiersLocal variable
info

Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.

APIs​

The Rapid7 InsightVM connector uses the InsightVM Cloud Integrations API v4. Specifically, it uses the following endpoints:

Table 5: Rapid7 InsightVM API Endpoints

Connector ObjectAPI Endpoint
HostGET /vm/v4/integration/assets/{id}
VulnerabilityPOST /vm/v4/integration/assets
Vulnerability DefinitionPOST /vm/v4/integration/vulnerabilities

Changelog​

The Rapid7 InsightVM connector has undergone the following changes:

3.4.7

  • Added the SOLUTION_SUMMARY attribute to the Vulnerability Definition object.

3.4.6

  • Added the TARGET_LAST_ASSESSED attribute to the Vulnerability object.

3.4.5

  • No change.

3.4.4

  • Code-clean up for data lifecycle management status on the Host object.

3.4.3

  • Added status to error messages in the Rapid7 InsightVM connector configuration to improve troubleshooting.

3.4.2

  • No change.

3.4.1

  • No change.

3.4.0

  • Changed the attribute used to determine data lifecycle management status on the Host object from LAST_SEEN to LAST_CAPTURED.

3.3.3

3.3.2

  • Changed the ASSESSED_FOR_VULNERABILITIES attribute type on the Host object from string to boolean.

3.2.8

  • Filtered the SITES tag from the TAGS attribute on the Host object.

3.2.5

  • Updated the paging logic.

3.2.0

  • Updated to fetch azure_vmid as the Instance ID for Azure assets.

3.1.2

  • Added a SEVERITY_SCORE attribute in the Vulnerability Definition object.

  • Fixed an issue causing vulnerability definition syncs to become stuck.

  • Improved the Results and Recommendation fields.

3.1.1

  • Normalized the values for status.

3.0.2

  • Normalized the values for the HOSTNAME attribute.

3.0.0

Last updated on