Rapid7 InsightVM

1. About this document

This document provides the step-by-step procedure to configure Rapid7 InsightVM in SAFE.

2. Introduction

SAFE integrates with Rapid7 InsightVM and allows you todiscover and import assets from Rapid7 InsightVM along with the respective vulnerability assessment results in SAFE.

Here are the key highlights of this integration:

• Import Assets and Vulnerability Assessment Results: With this integration, you can now discover and import assets from Rapid7 InsightVM along with the respective vulnerability assessment results for a comprehensive view of your assets' security posture.
• Automated and On-Demand Sync: You can set a pre-configured time interval for automatic synchronization of assessment results for assets. Also, it allows you to Initiate on-demand pulling of assessment results for assets as needed.
• On-Premise Connector: Rapid7 InsightVM is an on-premises deployed solution, and now, SAFE supports seamless communication with it. Configure an on-premise connector in your environment using Docker technology that ensures a secure and efficient data transfer between Rapid7 InsightVM and SAFE.

3. Prerequisites

3.1. Functional Prerequisites

To proceed, make sure the following prerequisites are met:

• Host Machine with Docker: You must have a host machine with Docker already installed. This will be used to download, install, and configure an on-premise Docker-based component that facilitates communication with SAFE.

• Rapid7 InsightVM User Credentials: You must have credentials (Rapid7 InsightVM Username and Password) to access Rapid7 InsightVM APIs. Refer to generate credentials for Rapid7 InsightVM.
• SAFE API Credentials: Refer to Accessing SAFE APIs to create SAFE API credentials.
• Network Access: Your host machine should have network access to the following resources:
  • SAFE Instance: refer to SAFE’s Outgoing IP Addresses
  • Rapid7 InsightVM Instance
• Encryption Key: SAFE's on-premise connector for Rapid7 InsightVM employs offline encryption to secure both Rapid7 InsightVM and SAFE API credentials stored on the local machine. To enable this encryption, an exact 32-character encryption key is required. This key must be provided each time the container needs to be initiated, updated, or restarted. You can generate a 32-byte encryption key using online tools such as RANDOM.ORG's String Generator.

3.2. Host Prerequisites

To host the connector successfully, your server must meet the following prerequisites:

• Docker Engine: Ensure that Docker Engine is installed and operational on the server where you intend to deploy the connector.
• For optimal performance and compatibility, we recommend the following server specifications:
  • CPU: At least 2 virtual CPUs (vCPUs).
  • RAM: A minimum of 8 Gigabytes (GB) of RAM.
  • Storage: Allocate at least 100 Gigabytes (GB) of disk storage.

4. Generate Rapid7 InsightVM Credentials

To integrate SAFE with Rapid7 insightVM, SAFE needs a user that has permission to view Site and Group Asset Data and view Vulnerability Investigations. If a user with this level of permissions is available, then the same can be used for configuring the connector.

If not, then follow the steps mentioned in the sections below and create a custom user with the minimum required permissions.

4.1. Create Custom Role

Follow the below steps to create a custom role:

1. Login to your Rapid7 InsightVM account as Admin.
2. From the Main menu, Navigate to Administration.
3. Click the Custom Roles option available under User.
   
4. Click the Create User Role option.
   
5. Enter the Role Name and Description.
6. Click Next.
   
7. Select the below permissions from the permission list.
   1. Select View Site Asset Data availabe under Sites.
   2. Select View Group Asset Dataavailabe under Asset Groups.
   3. Select View Vulnerability Investigations available underVulnerability Exceptions and Policy Overrides.
8. After selecting the above permission, click the Add button. Now, you have to add a user with this custom role.
   

4.2. Add a User with a Custom Role

1. Login to your Rapid7 InsightVM as Admin.
2. Navigate to Administration.
3. Click the User Management option available under Users.
   
4. Click the Add User button.
5. Enter the Username, Full Name, Email, AuthorizationMethod, and Password.
6. Click Next.
   
7. Select the Existing Custom Role option. The system displays all the custom roles available.
8. Select the Custom Role you have created above.
9. Click Next.
   
10. Select the Site Permissions. Here, select all the sites that you want to be assessed. We recommend selecting all the sites.
11.  Click Next.
    
12. Select the Asset Group Permissions. We recommend selecting all.
13. Click the Save button. The system creates the user.

5. Configure Rapid7 InsightVM in SAFE

Follow the below steps to configure the Rapid7 InsightVM integration in SAFE.

5.1. SAFE Setup

1. Navigate to SAFE Hooks.
2. Click the Rapid7 InsightVM card.
   
3. Click the Generate Integration ID. The system displays the commands on the UI.
4. The generated commands need to be configured on the on-premise connector. Refer to the next section for the step-by-step procedure.
   

5.2. On-Premise connector setup

1. Run the Docker Pull Command on the terminal.
   docker pull safesecurity/rapid7-connector:1.0.0
2. Run the Docker Start Command and replace '<MOUNT_PATH_IN_HOST_MACHINE>' with the actual value.
   docker run -d -v <MOUNT_PATH_IN_HOST_MACHINE>:/app/config --name safe-rapid7-connector safesecurity/rapid7-connector:1.0.0 && docker exec -it safe-rapid7-connector bash initialise.sh
3. Fill in the required details as per the prompt shown on the terminal.
   

5.3. Proxy Setup (Optional)

Follow the below steps to set the proxy:

On the prompt Do you want to configure a proxy? (Yes/No): If Yes, fill in all the required fields, which are present below.

Leave all fields empty if the proxy was already configured once and you want to keep it the same.

Enter proxy IP (Optional if configured previously): <IP>

Enter proxy port (Optional if configured previously): <PORT>

Enter proxy username (Optional if configured previously): <PROXY_USERNAME> If configured on Proxy

Enter proxy password (Optional if configured previously): <PROXY_PASSWORD> If configured on Proxy

Enter comma-separated list of no proxy IP/DNS (leave empty if none): <IP>

5.4. Save Configuration

1. Navigate to the SAFE portal from Safe Hooks > Rapid7 InsightVM.
2. If required, enter the Site ID Filter in the Connection Details. Site ID value can be comma-separated. Example: 1,2.
3. Add the auto-sync frequency.
4. Click the Save button.
5. Once the configuration is saved, click the Sync Now button to trigger the on-demand sync outside the scheduled auto sync.
   

6. View results

After a successful sync, the Rapid7 InsightVM assets are automatically imported into SAFE. To view the assets pulled from Rapid7 InsightVM:

1. On the Rapid7 InsightVM configuration page, click the See Updated Assets option available at the top-right of the History table.
   
2. The system redirects you to a filtered assets list of Rapid InsightVM assets.
3. Alternatively, you can navigate to Technology > Assets and filter the asset list for signal source equals security.safe.rapid7.insightvm.
   
4. You will be redirected to the assets details page by clicking an asset from the list. Here, you can view the controls and their status.
5. Clicking a control, you will be redirected to the control details page, where you can see the MITRE ATT&CK mapping.
   
6. The observation tab displays the Observations found by the Rapid7 InsightVM.
   

7. FAQs

1. What to do if the Encryption Key is lost?
If you lost the Encryption Key, remove the previously mounted config path directory on the host machine and reconfigure the on-premise connector. 

2. How to upgrade the connector when a newer version is available from SAFE’s end?
Follow the below steps to upgrade a connector to a newer version:

1. Stop the currently running on-premise Connector using the following command
   docker rm -f safe-rapid7-connector
2. Copy the Docker pull command (which would have been updated with a newer version).
3. After pulling the latest image for the Rapid7 On-Premise Connector, go run the  Docker Start command (i.e., the second command on the Hooks Page).

3. How to use private SSL certificates with an on-prem connector? (with Deep Packet Inspection-ing Firewalls)

In order to utilize private certificates, the customer must ensure that these certificates are accessible within a designated directory on the server or machine where the on-prem connector is being configured, denoted as "<CERTIFICATES_DIRECTORY>."

You will also need to specify the path to the certificate used for accessing the SAFE server from within the container. For example, if the certificate is named "ca-certificates.crt," the path to this certificate file should be "/etc/ssl/certs/ca-certificates.crt," which can be represented as "<CA_CERTIFICATE_FILE_PATH>."

To enable the connector to operate with these certificates, you need to adjust the Docker Start command (2nd command on the Rapid7 configuration page).

Original Command:

docker run -d -v <MOUNT_PATH_IN_HOST_MACHINE>:/app/config --name safe-rapid7-connector safesecurity/rapid7-connector:1.0.1 && docker exec -it safe-rapid7-connector bash initialise.sh

To incorporate support for private certificates, modify the above command as follows:

Updated Command with Support for Private Certificates:

docker run -d -v <MOUNT_PATH_IN_HOST_MACHINE>:/app/config -v <CERTIFICATES_DIRECTORY>:/usr/local/share/ca-certificates -e NODE_EXTRA_CA_CERTS=<CA_CERTIFICATE_FILE_PATH> --name safe-rapid7-connector safesecurity/rapid7-connector:1.0.1 && docker exec -it safe-rapid7-connector bash initialise.sh