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.infoReplace
<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 behttps://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:
-
Log in to your organization's Rapid7 InsightVM account as an administrator.
-
Navigate to API Keys > User Key and then click New User Key.
-
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:
-
Log in to your Rapid7 InsightVM account as an administrator.
-
Navigate to API Keys > Organization Key and click New Organization Key.
-
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.
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 |
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.
- Host
- Vulnerability
- Vulnerability Definition
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 |
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 |
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 |
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:
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.
3.1.1
- Normalized the values for status.
3.0.2
- Normalized the values for the HOSTNAME attribute.
3.0.0
- Initial Integration+ release.