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 Object	Required	Maps to Data Model
Host	Yes	Host
Vulnerability	Yes	Vulnerability
Vulnerability Definition	Yes	Vulnerability 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

Expand the sections below to view the mappings between the source and the Brinqa data model attributes.

Host

Table 2: Host attribute mappings

Source Field Name	Maps to Attribute
asset.assessed_for_policies	Local variable
asset.credential_assessments	Local variable
asset.host_name	hostnames, publicDnsName, privateDnsName
asset.id	uid
asset.ip	publicIpAddress, ipAddresses, privateIpAddresses
asset.last_assessed_for_vulnerabilities	lastSeen, lastScanned
asset.mac	macAddresses
asset.os_architecture	Local variable
asset.os_family	Local variable
asset.os_name	Local variable
asset.os_system_name	Local variable
asset.os_type	Local variable
asset.os_vendor	Local variable
asset.os_version	Local variable
asset.risk_score	Local variable
asset.tags	tags
asset.type	categories
asset.unique_identifiers.id	Local variable
description	description
name	name
operating system	os
status	status
unique_identifiers	Local variable

Vulnerability

Table 3: Vulnerability attribute mappings

Source Field Name	Maps to Attribute
asset.host_name	hostnames
asset.id	targets
asset.ip	ipAddresses
status	status
status_category	statusCategory
uid	uid
vulnerability.first_found	firstFound
vulnerability.key	Local variable
vulnerability.last_found	lastFound
vulnerability.port	port
vulnerability.proof	results
vulnerability.protocol	protocol
vulnerability.vulnerability_id	type

Vulnerability Definition

Table 4: Vulnerability Definition attribute mappings

Source Field Name	Maps to Attribute
cvssv2.getAttackComplexity	cvssV2AttackComplexity
cvssv2.getAttackVector	cvssV2AttackVector
cvssv2.getAuthentication	cvssV2Authentication
cvssv2.getAvailability	cvssV2AvailabilityImpact
cvssv2.getConfidentiality	cvssV2ConfidentialityImpact
cvssv2.getExploitability	cvssV2Exploitability
cvssv2.getIntegrity	cvssV2IntegrityImpact
cvssv2.getRemediationLevel	cvssV2RemediationLevel
cvssv2.getReportConfidence	cvssV2ReportConfidence
cvssv2.getSeverity	cvssV2Severity
cvssv3.getAttackComplexity	cvssV3AttackComplexity
cvssv3.getAttackVector	cvssV3AttackVector
cvssv3.getAvailability	cvssV3AvailabilityImpact
cvssv3.getConfidentiality	cvssV3ConfidentialityImpact
cvssv3.getExploitability	cvssV3ExploitCodeMaturity
cvssv3.getIntegrity	cvssV3IntegrityImpact
cvssv3.getPrivilegesRequired	cvssV3PrivilegesRequired
cvssv3.getReportConfidence	cvssV3ReportConfidence
cvssv3.getRemediationLevel	cvssV3RemediationLevel
cvssv3.getSeverity	cvssV3Severity
cvssv3.getUserInteraction	cvssV3UserInteraction
score.getBaseScore	cvssV2BaseScore, cvssV3BaseScore
score.getTemporalScore	cvssV2TemporalScore, cvssV3TemporalScore
solution.getFix	recommendation
solution.getType	patchAvailable
vulnerability.added	sourceCreatedDate
vulnerability.categories	categories
vulnerability.cves	cveIds,cveRecords
vulnerability.cvss_v2_vector	cvssV2Vector
vulnerability.cvss_v3_vector	cvssV3Vector
vulnerability.denial_of_service	Local variable
vulnerability.description	description
vulnerability.exploits	exploits
vulnerability.id	uid
vulnerability.malware_kits	malware
vulnerability.modified	sourceLastModified
vulnerability.pci_severity_score	Local variable
vulnerability.pci_status	Local variable
vulnerability.published	publishedDate
vulnerability.references	references
vulnerability.risk_score	Local variable
vulnerability.severity	severity, sourceSeverity
vulnerability.title	name

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 Object	API Endpoint
Host	GET /vm/v4/integration/assets/{id}
Vulnerability	POST /vm/v4/integration/assets
Vulnerability Definition	POST /vm/v4/integration/vulnerabilities

Changelog

The Rapid7 InsightVM connector has undergone the following changes:

Table 6: Rapid7 InsightVM connector changelog

Version	Description
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	Added support for Data lifecycle management to the Host and Vulnerability objects.
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 on the Vulnerability Definition object.
3.1.1	Normalized the values for status.
3.0.2	Normalized the values for the HOSTNAME attribute.
3.0.0	Initial Integration+ release.