Fortinet Document Library

Version:


Table of Contents

Rapid7 InsightVM

1.0.0
Copy Link

About the connector

The Rapid7 InsightVM platform integrates Rapid7’s library of Nexpose vulnerability research, Metasploit exploit knowledge, global attacker behavior, internet-wide scanning data, and threat exposure analytics. InsightVM takes advantage of this powerful analytics platform to automatically collect, monitor, and analyze your network for new and existing risks.

This document provides information about the Rapid7 InsightVM connector, which facilitates automated interactions, with a Rapid7 InsightVM server using FortiSOAR™ playbooks. Add the Rapid7 InsightVM connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving information about assets, sites, scans, and vulnerabilities.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.10.3-161 and later

Compatibility with Rapid7 InsightVM Versions: 6.5.8 and later

 

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

  • You must have the URL of Rapid7 InsightVM to which you will connect and perform the automated operations and credentials to access that server.
  • You must have the user credentials and port number to access the Rapid7 InsightVM REST API.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

 

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Rapid7 InsightVM connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL IP address or Hostname URL of the Rapid7 InsightVM server to which you will connect and perform the automated operations.
Port Port number used to access the Rapid7 InsightVM server.
Username Username that has administrative privileges on the Rapid7 InsightVM server.
Password Password to access the Rapid7 InsightVM server.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

 

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Get Asset(s) Retrieves information about all assets or specific asset(s) (based on the filter criteria you have specified) from Rapid7 InsightVM. get_asset
Investigation
Get Asset Vulnerability Retrieves information about vulnerabilities that are associated with a particular asset from Rapid7 InsightVM, based on the asset ID you have specified. get_asset_vuln
Investigation
Get Vulnerability Retrieves information about all vulnerabilities or a specific vulnerability (based on the vulnerability ID you have specified) from Rapid7 InsightVM. get_vulns
Investigation
Get Site Retrieves information about all sites or a specific site (based on the site ID you have specified) from Rapid7 InsightVM. get_site
Investigation
Get Scan Retrieves information about all scans or a specific scan (based on the scan ID you have specified) from Rapid7 InsightVM. get_scan
Investigation

 

operation: Get Asset(s)

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.

 

Parameter Description
Apply Filter Criteria Logical operator to be applied to searching assets based on the filter criteria. The following options are available: Any or All.
If you select Any then results are displayed if any of the filter criteria that you have specified is met and if you select All then results are displayed only if all the filter criteria that you have specified is met.
IP Address Operator Logical operator to be applied to searching asset based on the IP address value. The following options are available: Is, Is Not, In Range, Not In Range, Like, or Not Like.
IP Address Value If you specify the IP Address Operator, then you must specify the IP address based on which you want to search for asset(s).
If you have selected the In Range or Not In Range operator then specify the from (lower) value of the IP address that is part of the IP address range you want to use to search the asset(s).
IP Address Value Only applicable if you have selected the In Range or Not In Range operator.
If you have selected the In Range or Not In Range operator then specify the to (higher) value of the IP address that is part of the IP address range you want to use to search the asset(s).
Asset Name Operator Logical operator to be applied to searching asset based on the name of the asset.
The following options are available: Is, Is Not, Starts With, Ends With, Contains, Not Contains, Is Empty, Is Not Empty, Like, or Not Like.
Asset Name Value If you specify the Asset Name Operator, then you must specify the name of the asset based on which you want to search for asset(s).
OS Operator Logical operator to be applied to searching asset based on the OS.
The following options are available: Contains, Not Contains, Is Empty, or Is Not Empty
OS Value If you specify the OS Operator, then you must specify the OS based on which you want to search for asset(s).
Site ID Operator Logical operator to be applied to searching asset based on the ID of the site. The following options are available: In, or Not In.
Site ID Value If you specify the Site ID Operator, then you must specify the ID of the site based on which you want to search for asset(s).
Open Port Number Operator Logical operator to be applied to searching asset based on the open port number. The following options are available: Is, Is Not, or In Range.
Open Port Number Value If you specify the Open Port Number Operator, then you must specify the open port number based on which you want to search for asset(s).
If you have selected the In Range operator then specify the from (lower) value of the open port number that is part of the open port number range you want to use to search the asset(s).
Open Port Number Value Only applicable if you have selected the In Range operator.
If you have selected the In Range operator then specify the to (higher) value of the open port number that is part of the open port number range you want to use to search the asset(s).
User-Added Custom Tag Operator Logical operator to be applied to searching asset based on a user-added custom tag. The following options are available: Is, Is Not, Starts With, Ends With, Contains, Not Contains, Is Applied, or Is Not Applied.
User-Added Custom Tag Value If you specify the User-Added Custom Tag Operator, then you must specify the value of the user-added custom tag based on which you want to search for asset(s).
Vulnerability Category Operator Logical operator to be applied to searching asset based on a vulnerability category.
The following options are available: Is, Is Not, Starts With, Ends With, Contains, or Not Contains.
Vulnerability Category Value If you specify the Vulnerability Category Operator, then you must specify the value of the vulnerability category based on which you want to search for asset(s).
Vulnerability Title Operator Logical operator to be applied to searching asset based on a vulnerability title.
The following options are available: Is, Is Not, Starts With, Ends With, Contains, or Not Contains.
Vulnerability Title Value If you specify the Vulnerability Title Operator, then you must specify the value of the vulnerability title based on which you want to search for asset(s).
CVE ID Operator Logical operator to be applied to searching asset based on the CVE ID.
The following options are available: IS, Is Not, Contains, or Not Contains.
CVE ID Value If you specify the CVE ID Operator, then you must specify the value of the CVE ID based on which you want to search for asset(s).
User-Added Tag(Location) Operator Logical operator to be applied to searching asset based on a user-added location tag.
The following options are available: IS, Is Not, Starts With, Ends With, Contains, Not Contains, Is Applied, or Is Not Applied.
User-Added Tag(Location) Value If you specify the User-Added Tag(Location) Operator, then you must specify the value of the user-added location tag based on which you want to search for asset(s).
User-Added Criticality Level Operator Logical operator to be applied to searching asset based on a user-added criticality level.
The following options are available: Very High, High, Medium, Low, Very Low.
User-Added Criticality Level Value If you specify the User-Added Criticality Level Operator, then you must specify the value of the user-added criticality level based on which you want to search for asset(s).
User-Added Tag(Owners) Operator Logical operator to be applied to searching asset based on a user-added owners tag.
The following options are available: Is, Is Not, Starts With, Ends With, Contains, Not Contains, Is Applied, or Is Not Applied
User-Added Tag(Owners) Value If you specify the User-Added Tag(Owners) Operator, then you must specify the value of the user-added owners tag based on which you want to search for asset(s).
Page Number Page number from which you want to retrieve records.
Records Per Page Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains details of all the assets or specific asset(s) (based on the filter criteria you have specified) from Rapid7 InsightVM.

Following image displays a sample output:
 

Sample output of the Get Asset(s) operation

 

operation: Get Asset Vulnerability

Input parameters

 

Parameter Description
Asset ID ID of an asset whose associated vulnerabilities information you want to retrieve from Rapid7 InsightVM.
Detailed Reports (Optional) Select this option if you require detailed reports.
By default, this option is set to True.
Page Number (Optional) Page number from which you want to retrieve records.
Records Per Page (Optional) Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains information about the vulnerabilities associated with a specific asset retrieved from Rapid7 InsightVM, based on the asset ID you have specified.

Following image displays a sample output:
 

Sample output of the Get Asset Vulnerability operation

 

operation: Get Vulnerability

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.
 

Input parameters

 

Parameter Description
Vulnerability ID ID of a vulnerability whose information you want to retrieve from Rapid7 InsightVM.
Page Number Page number from which you want to retrieve records.
Records Per Page Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains details of all the vulnerabilities or a specific vulnerability (based on the vulnerability ID you have specified) from Rapid7 InsightVM.

Following image displays a sample output:
 

Sample output of the Get Vulnerability operation
 

operation: Get Site

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.

Input parameters

 

Parameter Description
Site ID ID of a site whose information you want to retrieve from Rapid7 InsightVM.
Page Number Page number from which you want to retrieve records.
Records Per Page Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains details of all the sites or a specific site (based on the site ID you have specified) from Rapid7 InsightVM.

Following image displays a sample output:
 

Sample output of the Get Site operation

 

operation: Get Scan

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.

Input parameters

 

Parameter Description
Scan ID ID of a site whose information you want to retrieve from Rapid7 InsightVM.
Report Active Scan Only Select this option if you want to include only active scan reports.
By default, this option is set to False.
Page Number Page number from which you want to retrieve records.
Records Per Page Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains details of all the scans or a specific scan (based on the scan ID you have specified) from Rapid7 InsightVM.

Following image displays a sample output:
 

Sample output of the Get Scan operation

 

Included playbooks

The Sample - Rapid7-InsightVM - 1.0.0 playbook collection comes bundled with the Rapid7 InsightVM connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Rapid7 InsightVM connector.

  • Get Asset
  • Get Asset vulnerability
  • Get Scan
  • Get Site
  • Get Vulnerability

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.

 

About the connector

The Rapid7 InsightVM platform integrates Rapid7’s library of Nexpose vulnerability research, Metasploit exploit knowledge, global attacker behavior, internet-wide scanning data, and threat exposure analytics. InsightVM takes advantage of this powerful analytics platform to automatically collect, monitor, and analyze your network for new and existing risks.

This document provides information about the Rapid7 InsightVM connector, which facilitates automated interactions, with a Rapid7 InsightVM server using FortiSOAR™ playbooks. Add the Rapid7 InsightVM connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving information about assets, sites, scans, and vulnerabilities.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.10.3-161 and later

Compatibility with Rapid7 InsightVM Versions: 6.5.8 and later

 

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

 

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Rapid7 InsightVM connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL IP address or Hostname URL of the Rapid7 InsightVM server to which you will connect and perform the automated operations.
Port Port number used to access the Rapid7 InsightVM server.
Username Username that has administrative privileges on the Rapid7 InsightVM server.
Password Password to access the Rapid7 InsightVM server.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

 

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Get Asset(s) Retrieves information about all assets or specific asset(s) (based on the filter criteria you have specified) from Rapid7 InsightVM. get_asset
Investigation
Get Asset Vulnerability Retrieves information about vulnerabilities that are associated with a particular asset from Rapid7 InsightVM, based on the asset ID you have specified. get_asset_vuln
Investigation
Get Vulnerability Retrieves information about all vulnerabilities or a specific vulnerability (based on the vulnerability ID you have specified) from Rapid7 InsightVM. get_vulns
Investigation
Get Site Retrieves information about all sites or a specific site (based on the site ID you have specified) from Rapid7 InsightVM. get_site
Investigation
Get Scan Retrieves information about all scans or a specific scan (based on the scan ID you have specified) from Rapid7 InsightVM. get_scan
Investigation

 

operation: Get Asset(s)

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.

 

Parameter Description
Apply Filter Criteria Logical operator to be applied to searching assets based on the filter criteria. The following options are available: Any or All.
If you select Any then results are displayed if any of the filter criteria that you have specified is met and if you select All then results are displayed only if all the filter criteria that you have specified is met.
IP Address Operator Logical operator to be applied to searching asset based on the IP address value. The following options are available: Is, Is Not, In Range, Not In Range, Like, or Not Like.
IP Address Value If you specify the IP Address Operator, then you must specify the IP address based on which you want to search for asset(s).
If you have selected the In Range or Not In Range operator then specify the from (lower) value of the IP address that is part of the IP address range you want to use to search the asset(s).
IP Address Value Only applicable if you have selected the In Range or Not In Range operator.
If you have selected the In Range or Not In Range operator then specify the to (higher) value of the IP address that is part of the IP address range you want to use to search the asset(s).
Asset Name Operator Logical operator to be applied to searching asset based on the name of the asset.
The following options are available: Is, Is Not, Starts With, Ends With, Contains, Not Contains, Is Empty, Is Not Empty, Like, or Not Like.
Asset Name Value If you specify the Asset Name Operator, then you must specify the name of the asset based on which you want to search for asset(s).
OS Operator Logical operator to be applied to searching asset based on the OS.
The following options are available: Contains, Not Contains, Is Empty, or Is Not Empty
OS Value If you specify the OS Operator, then you must specify the OS based on which you want to search for asset(s).
Site ID Operator Logical operator to be applied to searching asset based on the ID of the site. The following options are available: In, or Not In.
Site ID Value If you specify the Site ID Operator, then you must specify the ID of the site based on which you want to search for asset(s).
Open Port Number Operator Logical operator to be applied to searching asset based on the open port number. The following options are available: Is, Is Not, or In Range.
Open Port Number Value If you specify the Open Port Number Operator, then you must specify the open port number based on which you want to search for asset(s).
If you have selected the In Range operator then specify the from (lower) value of the open port number that is part of the open port number range you want to use to search the asset(s).
Open Port Number Value Only applicable if you have selected the In Range operator.
If you have selected the In Range operator then specify the to (higher) value of the open port number that is part of the open port number range you want to use to search the asset(s).
User-Added Custom Tag Operator Logical operator to be applied to searching asset based on a user-added custom tag. The following options are available: Is, Is Not, Starts With, Ends With, Contains, Not Contains, Is Applied, or Is Not Applied.
User-Added Custom Tag Value If you specify the User-Added Custom Tag Operator, then you must specify the value of the user-added custom tag based on which you want to search for asset(s).
Vulnerability Category Operator Logical operator to be applied to searching asset based on a vulnerability category.
The following options are available: Is, Is Not, Starts With, Ends With, Contains, or Not Contains.
Vulnerability Category Value If you specify the Vulnerability Category Operator, then you must specify the value of the vulnerability category based on which you want to search for asset(s).
Vulnerability Title Operator Logical operator to be applied to searching asset based on a vulnerability title.
The following options are available: Is, Is Not, Starts With, Ends With, Contains, or Not Contains.
Vulnerability Title Value If you specify the Vulnerability Title Operator, then you must specify the value of the vulnerability title based on which you want to search for asset(s).
CVE ID Operator Logical operator to be applied to searching asset based on the CVE ID.
The following options are available: IS, Is Not, Contains, or Not Contains.
CVE ID Value If you specify the CVE ID Operator, then you must specify the value of the CVE ID based on which you want to search for asset(s).
User-Added Tag(Location) Operator Logical operator to be applied to searching asset based on a user-added location tag.
The following options are available: IS, Is Not, Starts With, Ends With, Contains, Not Contains, Is Applied, or Is Not Applied.
User-Added Tag(Location) Value If you specify the User-Added Tag(Location) Operator, then you must specify the value of the user-added location tag based on which you want to search for asset(s).
User-Added Criticality Level Operator Logical operator to be applied to searching asset based on a user-added criticality level.
The following options are available: Very High, High, Medium, Low, Very Low.
User-Added Criticality Level Value If you specify the User-Added Criticality Level Operator, then you must specify the value of the user-added criticality level based on which you want to search for asset(s).
User-Added Tag(Owners) Operator Logical operator to be applied to searching asset based on a user-added owners tag.
The following options are available: Is, Is Not, Starts With, Ends With, Contains, Not Contains, Is Applied, or Is Not Applied
User-Added Tag(Owners) Value If you specify the User-Added Tag(Owners) Operator, then you must specify the value of the user-added owners tag based on which you want to search for asset(s).
Page Number Page number from which you want to retrieve records.
Records Per Page Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains details of all the assets or specific asset(s) (based on the filter criteria you have specified) from Rapid7 InsightVM.

Following image displays a sample output:
 

Sample output of the Get Asset(s) operation

 

operation: Get Asset Vulnerability

Input parameters

 

Parameter Description
Asset ID ID of an asset whose associated vulnerabilities information you want to retrieve from Rapid7 InsightVM.
Detailed Reports (Optional) Select this option if you require detailed reports.
By default, this option is set to True.
Page Number (Optional) Page number from which you want to retrieve records.
Records Per Page (Optional) Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains information about the vulnerabilities associated with a specific asset retrieved from Rapid7 InsightVM, based on the asset ID you have specified.

Following image displays a sample output:
 

Sample output of the Get Asset Vulnerability operation

 

operation: Get Vulnerability

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.
 

Input parameters

 

Parameter Description
Vulnerability ID ID of a vulnerability whose information you want to retrieve from Rapid7 InsightVM.
Page Number Page number from which you want to retrieve records.
Records Per Page Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains details of all the vulnerabilities or a specific vulnerability (based on the vulnerability ID you have specified) from Rapid7 InsightVM.

Following image displays a sample output:
 

Sample output of the Get Vulnerability operation
 

operation: Get Site

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.

Input parameters

 

Parameter Description
Site ID ID of a site whose information you want to retrieve from Rapid7 InsightVM.
Page Number Page number from which you want to retrieve records.
Records Per Page Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains details of all the sites or a specific site (based on the site ID you have specified) from Rapid7 InsightVM.

Following image displays a sample output:
 

Sample output of the Get Site operation

 

operation: Get Scan

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.

Input parameters

 

Parameter Description
Scan ID ID of a site whose information you want to retrieve from Rapid7 InsightVM.
Report Active Scan Only Select this option if you want to include only active scan reports.
By default, this option is set to False.
Page Number Page number from which you want to retrieve records.
Records Per Page Maximum number of results that this operation should return. By default, this is set to 10.

 

Output

The JSON output contains details of all the scans or a specific scan (based on the scan ID you have specified) from Rapid7 InsightVM.

Following image displays a sample output:
 

Sample output of the Get Scan operation

 

Included playbooks

The Sample - Rapid7-InsightVM - 1.0.0 playbook collection comes bundled with the Rapid7 InsightVM connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Rapid7 InsightVM connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.