Rapid7 InsightVM

Rapid7 InsightVM provides data collection, visibility, analytics, and automation to establish a shared point of view between security, IT operations, and DevOps teams. InsightVM brings together Rapid7’s library of vulnerability research knowledge from Nexpose, exploit knowledge from Metasploit, global attacker behavior, internet-wide scanning data, exposure analytics, and real-time reporting.

The cloud platform delivers one-click access to Rapid7’s vulnerability management, application testing, orchestration and automation, incident detection and response, phishing analysis and simulation, and log management solutions. Rapid7 InsightVM offers a range of features to streamline vulnerability management processes and enhance overall security posture.  With Rapid7 InsightVM, organizations can identify, prioritize, and mitigate security risks across their entire attack surface.

The Rapid7 InsightVM Integration with the Archer IT Security Vulnerabilities Program use case enables clients to leverage the discovered devices and catalog those network devices with the vulnerability library. Clients can then identify which assets require remediation based on the business priority of that asset.

Release history

Last updated: April 2024

Overview of Rapid7 InsightVM

Benefits

The Rapid7 Insight VM integration enables organizations to:

• Catalog network devices on a corporate network.

• Discover network device vulnerabilities using Insight VM scanning.

• Supplement the Vulnerability Library with Rapid7 Vulnerability Definitions.

Prerequisites (ODA and system requirements)

Components	Prerequisites
Archer Solution Area(s)	IT & Security Risk Management
Archer Use Case(s)	Archer IT Security Vulnerabilities Program, Archer Enterprise Catalog
Archer Applications	Devices, Vulnerability Library, Vulnerability Scan Results
Uses Custom Application	No
Requires On-Demand License	No
Archer Requirements	Archer 2024.03 and later
Partner/Vendor Requirements	Valid Rapid7 license is required
Operating System	Windows Server 2012 R2
Supported Archer Environments	On-Premises Archer SaaS

Compatible Use Cases and Applications

Related Applications

Application	Use Case	Primary Purpose(s) of the Relationship
Devices	Enterprise Catalog	The Devices application serves as a central repository of knowledge about your business-critical devices and their business criticality. It allows organizations to manage devices (i.e. servers, desktops, network devices, etc.) and their relationships, to ensure they are being protected according to management expectations.
Vulnerability Library	IT Security Vulnerabilities Program	The Vulnerability Library application represents a catalog of vulnerability data collected from Rapid7. The Vulnerability Library also provides a method for generating exception requests, identifying mitigating strategies, and denoting affected ports.
Vulnerability Scan Results	IT Security Vulnerabilities Program	The Vulnerability Scan Results application stores the issues that result from every new record that is created from the vulnerability scanner such as Device Name, IP, owner, department, description, notes, recommendations and much more.

Impacted Use Case(s)

Archer Use Case(s)
Enterprise Catalog
IT Security Vulnerabilities Program

Additional resources

Please refer to the Rapid7 help documentation mentioned below for additional information: https://help.rapid7.com/insightvm/en-us/api/index.html

Rapid7 InsightVM Integration components

Architecture diagram

          

Prerequisites

This offering requires a Rapid7 report in ‘XML Report 2.0’ format to be created in Rapid7 InsightVM security console. For details, please refer Creating a Report in Rapid7 section.

Components

This offering consists of the following components:

1. C# console application: The console application interacts with Rapid7 InsightVM Security Console API for access to the latest instance of the Rapid7 report. The console application must be placed on a server with access to the Rapid7 InsightVM Security Console APIs.

2. FTP location: The console application saves the API reponse in XML format to the FTP location which has basic authentication.

3. Archer FTP data feeds: The data feeds access the reports on the FTP location and ingests the relevant data into the following applications: Devices, Vulnerability Library and Vulnearbility Scan Results.

   When the scan results have not been updated within the default value of 60 days, an additional data feed can be implemented to set the status of Vulnerability Scan Results to ‘Verified’. The data feed is provided but is optional.

The installation package consists of two components:

• Rapid7 C-Sharp console applications in .zip format

• Rapid7 InsightVM Integration 2024.03 Installation Package.

Installing Rapid7 InsightVM integration

Security considerations

The information in this publication is provided “as is”. Archer makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Client is solely responsible for ensuring that the installation of the application is performed in a secure manner. Archer recommends clients perform a full security evaluation prior to implementation.

Installation overview

Step 1: Prepare for the installation

1. Ensure that your Archer system meets the following requirements:

   • Archer Platform Release 2024.03

2. Obtain the Data Dictionary for the ODA by contacting your Archer Account Representative or calling 1-888-539-EGRC. The Data Dictionary contains the configuration information for the use case.

3. Read and understand "Packaging Data" in the Archer Platform Help.

Step 2: Install the package

Installing a package requires that you import the package file, map the objects in the package to objects in the target instance, and then install the package. For more information, see Installing the Packages.

Step 3: Set up data feeds

You must import and schedule each use case data feed that you want to use. See Setting Up Data Feeds for complete information.

Note: Rapid7 data feeds are packaged in the Rapid7 Insight VM integration installation package. Please use this section in cases where the data feeds need to the imported separately.

Step 4: Test the installation

Test the application according to your company standards and procedures, to ensure that the use case works with your existing processes.

Installing the package

Task 1: Back up your database

There is no undo function for package installation. Packaging is a powerful feature that can make significant changes to an instance. Archer strongly recommends that you back up the instance database before installing a package. This process enables a full restoration if necessary.

An alternate method for undoing a package installation is to create a package of the affected objects in the target instance before installing the new package. This package provides a snapshot of the instance before the new package is installed, which can be used to help undo the changes made by the package installation. You must manually delete new objects created by the package installation.

Task 2: Import the package

1. From the menu bar, click > Application Builder > Install Packages.

2. In the Available Packages section, click Import.

3. Click Add New, then select the package file that you want to import.

4. Click OK.

The Available Packages section displays the package file and is ready for installation.

Task 3: Map objects in the package

Important: This step is required only if you are upgrading to a later version of [ODA name].

1. From the menu bar, click > Application Builder > Install Packages.

2. In the Available Packages section, select the package you want to map.

3. In the Actions column, click for that package.

   The analyzer runs and examines the information in the package. The analyzer automatically matches the system IDs of the objects in the package with the objects in the target instances and identifies objects from the package that are successfully mapped to objects in the target instance, objects that are new or exist but are not mapped, and objects that do not exist (the object is in the target but not in the source).

   Note: This process can take several minutes or more, especially if the package is large, and may time out after 60 minutes. This time-out setting temporarily overrides any IIS time-out settings set to less than 60 minutes.

4. When the analyzer is complete, the Advanced Package Mapping page lists the objects in the package file and corresponding objects in the target instance. The objects are divided into tabs, depending on whether they are found within Applications, Solutions, Access Roles, Groups, Sub- forms, or Questionnaires.

   On each tab of the Advanced Mapping Page, review the icons next to each object to determine which objects you must map manually.

   Icon	Name	Description
   	Awaiting Mapping Review	Indicates that the system could not automatically match the object or children of the object to a corresponding object in the target instance. Objects marked with this icon must be mapped manually through the mapping process. Important: New objects should not be mapped. This icon should remain visible. The mapping process can proceed without mapping all the objects. Note: You can run the mapping process without mapping all the objects. The icon is for informational purposes only.
   	Mapping Completed	Indicates that the object and all child objects are mapped to an object in the target instance. There are no further steps required with these objects in Advanced Package Mapping.
   	Do Not Map	Indicates that the object does not exist in the target instance, or the object was not mapped through the Do Not Map option. These objects will not be mapped through Advanced Package Mapping and must be remedied manually.
   	Undo	Indicates that a mapped object can be unmapped. This icon is displayed in the Actions column of a mapped object or object flagged as Do Not Map.

5. For each object that requires remediation, do one of the following:

   • To map each item individually, on the Target column, select the object in the target instance to which you want to map the source object. If an object is new or if you do not want to map an object, select Do Not Map from the drop-down list.

     Important: Ensure that you map all objects to their lowest level. When objects have child or related objects, the parent object provides a drill-down link. You must map child objects before parent objects. For more details, see "Mapping Parent/Child Objects" in the Archer Platform Help.

   • To automatically map all objects in a tab that have different system IDs but the same object name as an object in the target instance, do the following:

     1. In the toolbar, click Auto Map.

     2. Select an option for mapping objects by name.

        Option	Description
        Ignore case	Select this option to match objects with similar names regardless of the case of the characters in the object names.
        Ignore spaces	Select this option to match objects with similar names regardless of whether spaces exist in the object names.

     3. Click OK. The Confirmation dialog box opens with the total number of mappings performed. These mappings have not been committed to the database yet and can be modified in the Advanced Package Mapping page.

     4. Click OK.

        • To set all objects in the tab to Do Not Map, in the toolbar, click Do Not Map.

   To undo the mapping settings for any individual object, in the Actions column, click Undo.

   When all objects are mapped, the icon is displayed in the tab title. The icon is displayed next to the object to indicate that the object will not be mapped.

6. Verify that all other objects are mapped correctly.

7. (Optional) To save your mapping settings so that you can resume working later, see "Importing and Exporting Mapping Settings" in the Archer Platform Help.

8. Once you have reviewed and mapped all objects, click Execute.

9. Select I understand the implications of performing this operation and click OK.

The Advanced Package Mapping process updates the system IDs of the objects in the target instance as defined on the Advanced Package Mapping page. When the mapping is complete, the Import and Install Packages page is displayed.

Important: Advanced Package Mapping modifies the system IDs in the target instance. You will need to update any Data Feeds and Web Service APIs that use these objects, with the new system IDs.

Task 4: Install the package

All objects from the source instance are installed in the target instance unless the object cannot be found or is flagged to not be installed in the target instance. The Log Messages section provides a list of conditions that may cause objects not to be installed. The Package Installation Log section displays a log entry.

1. From the menu bar, click > Application Builder > Install Packages.

2. In the Available Packages section, locate the package file that you want to install, and click Install.

3. In the Selected Components section, click the Lookup button to open the Package Selector window.

   • To select all components, select the top-level checkbox.

   • To install only specific global reports in an already installed application, select the checkbox associated with each report that you want to install.

   Note: Items in the package that do not match an existing item in the target instance are selected by default.

4. Under the Install Method drop-down menu, select an option for each selected component. To use the same Install Method for all selected components, select a method from the top-level drop-down list.

   Note: If you have any existing components that you do not want to modify, select Create New Only. You may have to modify those components after installing the package to use the changes made by the package.

5. To deactivate target fields and data-driven events that are not in the package, in the Post-Install Actions section, select the Deactivate target fields and data-driven events that are not in the package checkbox. To rename the deactivated target fields and data-driven events with a user-defined prefix, select the Apply a prefix to all deactivated objects checkbox, and enter a prefix. This can help you identify any fields or data-driven events that you may want to review for cleanup post-install.

6. Click Install.

7. Click OK.

Task 5: Review the package installation log

1. From the menu bar, click > Application Builder > Install Packages.

2. In the Package Installation Log tab, click the package that you want to view.

3. In the Package Installation Log page, in the Object Details section, click View All Errors.

   Note: To view individual logs, in the Errors column of the log you want to view, click the Failures link or Warnings link. Clicking View All Errors, Failures, or Warnings opens the specific errors on a different page
   

4. Click Export to export the log file.

5. Click Close.
   

Setting up data feeds

Import the data feeds in the following order:

1. Rapid7-1 Vulnerability 2024.03

2. Rapid7-2 Hosts 2024.03

3. Rapid7-3 Vulnerability Scan Results 2024.03

4. Rapid7 Vulnerability Verified Status 2024.03

Task 1: Import a data feed

1. Go to the Manage Data Feeds page.

   1. From the menu bar, click .

   2. Under Integration, click Data Feeds.

2. In the Manage Data Feeds section, click Import.

3. Locate and select the Rapid7-1 Vulnerability 2024.03.dfx5 file for the data feed.

4. From the General tab in the General Information section, in the Status field, select Active.

5. Click the Transport tab. Complete the fields in the Transport Configuration section as follows: In the URL field, type: FTP full qualified URL of the Rapid7 report. In case of Archer SAAS instances, the FTP full qualified URL of the Rapid7 report should be ftp://ftp01/Rapid7/rapid7_vulns_report_latest.xml.

6. In the Username and Password fields, type the username and password of the FTP user that has read access to the Rapid7 report.

7. Verify that key field values are not missing from the data feed setup window.

8. Click Save.

9. Follow the steps from 1-8 for Rapid7-2 Hosts 2024.03.dfx5 and Rapid7-3 Vulnerability Scan Results 2024.03.dfx5 data feed files.

10. For Rapid7 Vulnerability Verified Status 2024.03.dfx5 , Click the Transport tab, Complete the fields in the Transport Configuration section as follows: In the URL field, type: YourServerName/VirtualDirectoryName/ws/search.asmx.

11. In the Username and Password fields, type the username and password of a Platform user that has API access and access to all the records on the Platform instance (from which the data feed is coming).

12. In the Instance field, type the name of the Platform instance from which the data feed is coming (this is the instance name as you enter it on the Login window).

13. The following are the mappings of the source and target fields of the data feeds.

Rapid7-1 Vulnerability 2024.03

Key Field:

Vulnerability Library: DFMKey

Vulnerability Reference Lists: URL

Source Field	Target Field
Id	ID
Title	Title
Source	Source
Severity	Rapid7 Severity Severity
PciSeverity	Rapid7 PCI Severity
CvssScore	Rapid7 CVSS v3 Base Score
CvssVector	Rapid7 CVSS v3 Vector
Published	Rapid7 Published Date
Added	Rapid7 Added Date
Modified	Rapid7 Modified Date
RiskScore	Rapid7 Risk Score
DFMKey	DFMKey
Description	Description
Vulnerability_Reference_List/ reference	Vulnerability Reference Lists/URL
Tags/tag	Rapid7 Tags
Solution	Solution

Rapid7-2 Hosts 2024.03

Key Field:

Devices: Device Unique Key

Note: The Rapid7 Hosts 2024.03 data feed has been provided with two DFM key values- DFMKey_DNS and DFMKey_IP with DFMKey_DNS being the default mapped value. 

Change the mapping of the DFM key field based on the following considerations:

1. DFMKey_IP – Use this field mapping in cases where the requirement is to create Device records for all IP addresses or there is no consistent DNS name resolution for Rapid7.

2. DFMKey_DNS- Use this field mapping in case the Device application is already populated with values or there are multi-home servers in the network and Device records are not needed to be created for all IPs’.

Source Field	Target Field
Address	External IPv4 Address
Source	Last Updated By
Device-Name	Device Name
Other-Device-Name	Rapid7 Other Devices
Status	Device Status
Rapid-Status	Rapid7 Type
Hardware-Address	MAC Address
Device-Id	Rapid7 Device ID
Site-Name	Rapid7 Site Name
Site-Importance	Rapid7 Site Importance
Scan-Template	Rapid7 Scan Template
Risk-Score	Rapid7 Risk Score
DFMKey_DNS	DFMKey Rapid7 Device Unique Key
DFMKey_IP
OS_Technologies/ OS_Technology/Item	Operating System Technologies
Application_Technologies /Application_Technology/Item	Application Technologies

Rapid7-3 Vulnerability Scan Results 2024.03

Key Field:

Vulnerability Scan Results: DFMKey

Vulnerability Library Details: ID

Impacted Device: Rapid7 Device ID

Source Field	Target Field
Id	Vulnerability Library Details/ID Title
Key
Scan-Id
First-Found-Date	First Found Date
Last-Found-Date	Last Found Date
Pci-Compliance-Status
Results	Results
Endpoint-Protocol	Protocol
Endpoint-Port	Port Number
Endpoint-Status
Address	IPv4
Source	Source
Device-Name	Hostname
Other-Device-Names
Status	Rapid7 Vulnerability Status
Hardware-Address	MAC address
Device-Id	Impacted Device/Rapid7 Device ID
Site-Name
Site-Importance
Scan-Template
Risk-Score	Score
OS_Technologies/OS_Technology/ Item	CPE Operating System Technology
DFMKey	DFMKey

Rapid7 Vulnerability Verified Status 2024.03

Key Field:

Vulnerability Scan Results: DFMKey

Source Field	Target Field
DFMKey	DFMKey
Status	Rapid7 Retrieved Scan Status Rapid7 Latest Data Feed Performing Updates

Task 2: Schedule a data feed

A data feed must be active and valid to successfully run. A successful data feed run processes all input data, completes all expected record updates, and does not report any failures in the Run Details Report.

Validating a data feed

The Data Feed Manager validates the information when a data feed is scheduled. If any information is invalid, the data feed displays an error message. You can save the data feed and correct the errors later, but the data feed does not process until you make corrections.

Running a data feed

You can set up data feeds to run automatically at regular intervals. This reduces the time and effort required to import data from an external file.

You can initiate data feeds at various times and configure them to run in regular increments for an indefinite period of time.

You can run the data feed immediately.

To prevent excess server load, schedule data feeds on a staggered basis. You can schedule a maximum of 10 data feeds to run at a time. If more than 10 data feeds are scheduled, each remaining data feed runs as the previous one completes.

Setting up a reference data feed

A reference feed allows you to specify another feed. This indicates to the Data Feed Service that this feed will start running as soon as the referenced feed completes successfully.

1. Go to the Run Configuration tab > Schedule section.

2. Do one of the following to schedule your data feed.

   • Run on Schedule. You can configure your data feed to run on a defined schedule.

   • Run After. The Data Feed Services starts the current data feed after the referenced data feed completes successfully.

   • Run Now.

3. To save the data feed, click Save or Save and Close.

Configuring the Rapid7 C# Console application

Task 1: Creating a report in Rapid7

1. Login to Rapid7 InsightVM Security Console.

2. Click Report

3. Click Create a Report.

4. Select Export and select the report type as XML Export 2.0.

5. Select the scope of the report by selecting Assets, Groups or tags.

6. Select the Frequency as Run a recurring report on a schedule and select the time and frequency based on the requirements.

7. Click Save the report.

8. Navigate to the Reports home screen.

9. Click the Report Name.

10. The report will open in a new tab with the URL with the following format: ‘domain_name/report_ID/report_instance_id/report.xml. The prefixed zeroes should be ignored while selecting the report Id. For example, if the report URL is ‘<domain_name>/reports/00000002/000000A6/report.xml’, then the report ID is 2.

11. The Rapid7 Report endpoint format is ‘<domain_name>/api/<report_ID>/reports/1/history/latest/output’. The following is the URL for accessing report with Report ID 22. <domain_name>/api/3/reports/22/history/latest/output.The Rapid7 APIs provide basic authentication and valid Username and password are required for accessing the APIs.

Task 2: Unzip the Rapid7 Console package

1. Unzip the Rapid7 Console.zip file.

2. The unzipped folder should have the following contents:

   1. Rapid7.exe

   2. Rapid7.exe.config

3. Place the contents in the package in a location that has access to Rapid7 API.

4. The following table describes the options present in the Rapid7.exe.config file.

   Note: The Rapid7 console application requires the following access:

• Access to fetch Rapid7 API response

• CRUD access to the FTP server where API report must be created. For security reasons, basic authentication must be enabled in the FTP server.

Field	Description
UserName	Specifies the Rapid7 username for API access
Password	Specifies the Rapid7 password for API access
Domain	Specifies the Rapid7 domain. e.g. if Rapid7 is running at local host, then the value should be ‘https://localhost:3780’.
FTP_Domain	Specifies the domain of the FTP server where the Rapid7 report should be placed. e.g. XX.XXX.XX.XX In case of Archer SAAS instances, provide the SAAS FTP location. Note: Only provide the domain without ‘ftp://’ prefix.
FTP_UserName	Specifies the FTP server Username.
FTP_Password	Specified the FTP server password.
File_Archival	This key has two values- True or False with the default value being False. The key values provide the following functionality: True- The utility will create an archive of all the older reports in rapid7_vulns_yyyyMMddTHHmmss.xml format and create a latest report ‘rapid7_vulns_report_latest.xml’. False- The utility will delete the existing/older report and create the latest report ‘rapid7_vulns_report_latest.xml’.
Certificate_Verification	Specifies whether the utility should verify the Server certificates. Valid values are True/False.
SSL_Enabled	Specifies whether SSL is enabled in the FTP server. Valid values are True/False
Logger	Enables logging

Task 3: Task creation in Window Scheduler

1. Create a Task in Window Scheduler to execute the application daily at a desired time.

   Note: The Rapid7.exe.config file will be encrypted after the first execution of the console application.

Certification environment

Date tested: May 2024

Product Name	Version Information	Operating System
Archer	2024.03	Virtual Appliance