---
title: InsightVM
---
<!-- licenses: community, platform -->

runZero integrates with ((Rapid7 InsightVM)) by importing data from the [InsightVM API](https://help.rapid7.com/insightvm/en-us/api/index.html).

Both Rapid7 InsightVM Cloud and on-premises ((InsightVM)) are supported. For on-premises use you will need to use the InsightVM connector [as a scan probe](#step-2-choose-how-to-configure-the-rapid7-integration) from a runZero Explorer which has network access to the InsightVM deployment.

The Insight Platform API is distinct from the InsightVM API, and is not supported.

## Getting started with InsightVM{#insightvm-getting-started}

To set up the InsightVM integration, you'll need to:

1. Create or obtain user credentials to use with the InsightVM API. 
2. Add the InsightVM API username, password, and API URL in runZero.
3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector).
4. Activate the InsightVM integration to pull your data into runZero. 

## Requirements {#insightvm-requirements}

Before you can set up the InsightVM integration:

* Obtain credentials for an InsightVM user with administrator access to the InsightVM portal. 
* Scan your InsightVM with a runZero Explorer if you want to use trusted authentication (optional).

### Step 1: Add the InsightVM credentials to runZero

1. [Create a new credential](https://console.runzero.com/credentials/new) via the runZero [Credentials page](https://console.runzero.com/credentials). 
2. Provide a name for the credentials, like `InsightVM`.
3. Choose **InsightVM Username & Password** from the list of credential types.
4. Provide the following information:
    * **InsightVM username** - The username you want to use to connect to the InsightVM API. This account requires the [`User` role](https://docs.rapid7.com/insightvm/managing-users-and-authentication/#user) or greater permissions in InsightVM.
    * **InsightVM password** - The password for your InsightVM username.
    * **InsightVM API URL** - The URL of your InsightVM API instance. By default, the InsightVM API uses port 3780. The expected format is `https://ip:3780` or `https://domain.tld:3780`. RunZero automatically appends `api/3/sites?size=500` to this URL.
    * **InsightVM insecure** - Set this to `Yes` if you want to attempt authentication without a verified thumbprint.
    * **InsightVM thumbprints** (optional) - A set of `IP=SHA256:B64HASH` or `domain.tld=SHA256:B64HASH` pairs to trust for authentication. 
      * You will need to scan your InsightVM instance with runZero in order to obtain the TLS thumbprint. The [TLS fingerprints service attribute report](https://console.runzero.com/reports/analysis/sattr?f=tls.fp.sha256&sf=protocol&sfv=http%09tls&t=Service%20Attribute%20Report%20[tls.fp.sha256]) lists all previously seen fingerprints.
      * If _InsightVM insecure_ is set to _No_ and no thumbprints are provided:
        * With a self-signed certificate, the connection will fail because the certificate chain cannot be verified. 
        * With a valid certificate from a public CA, the connection can work without thumbprints.
5. If you want all other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per-organization basis. 
6. Save the credential. 

You're now ready to set up and activate the connection to bring in data from InsightVM. 

## Step 2: Choose how to configure the Rapid7 integration
The Rapid7 InsightVM integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync. Scan probes will be the right option for most users. Setting up a connector will only work for if you're self-hosting runZero or your InsightVM instance is publicly accessible.

## Step 3: Sync your InsightVM data
After you add your InsightVM credential, you'll need to activate the integration to sync your data.

### Step 3a: Configure the InsightVM scan probe
You can run the InsightVM integration as a scan probe so that the runZero Explorer will pull your vulnerability data into the runZero Console. 

In a new or existing scan configuration:
* Ensure that the _INSIGHTVM_ option is set to _Yes_ in the _Probes and SNMP_ tab and change any of the default options if needed. 
* Set the correct InsightVM credential to _Yes_ in the _Credentials_ tab.
* Optionally, set the [severity and risk levels](docs/rapid7.md/#rapid7-scoring) for ingested vulnerability scan results.
* Enter a Site Name Filter to filter results based on the InsightVM site using regular expressions (optional).

### Step 3b: Configure the InsightVM connector
A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new InsightVM-only assets are created.

1. Activate a [connection to InsightVM](https://console.runzero.com/ingest/insightvm). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks). 
2. Choose the credentials you added earlier. If you don't see the credentials listed, make sure the credentials have access to the organization you are currently in. 
3. Set the [severity and risk levels](docs/rapid7.md/#rapid7-scoring) you want to import (optional).
4. Input a Site Name Filter to filter your results by specific sites (optional). This input uses regular expressions and supports the [re2 syntax](https://github.com/google/re2/wiki/Syntax).
5. Set the **Fingerprint only** toggle to _Yes_ if you want vulnerability records to be ingested for fingerprint analysis but not stored in your runZero vulnerability inventory (optional).
6. Enter a name for the task, like `InsightVM sync` (optional). 
7. Choose the Explorer to perform this connector task from (optional).
8. Choose the site you want to add your assets to. All newly discovered assets will be stored in this site.
9. Enter a description for the task (optional).
10. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero.
11. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set. 
12. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur.

## Step 4: View InsightVM assets and vulnerabilities

After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your InsightVM assets. These assets will have a Rapid7 icon listed in the **Source** column.

The InsightVM integration gathers details about vulnerabilities detected in addition to enriching asset inventory data. Go to Inventory > [Vulnerabilities](https://console.runzero.com/inventory/vulnerabilities) to view the vulnerability data provided by InsightVM.

To filter by Rapid7 assets, consider running the following queries:

* [View all Rapid7 assets](https://console.runzero.com/inventory?search=source%3ARapid7): 
     ```
     source:Rapid7
    ```
Click into each asset to see its individual attributes. runZero will show you the attributes gathered from the Rapid7 scan data.

## Troubleshooting {#insightvm-troubleshooting}
If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting.

### Why is the Rapid7 InsightVM integration unable to connect?
1. Are you getting any data from the Rapid7 InsightVM integration?
    * Make sure to query the inventory rather than look at the task details to review all the data available from this integration.
    * In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console.
2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly.
3. If the Rapid7 InsightVM integration is unable to connect be sure to check the task log for errors. Some common errors include:
    * 500 - server error, unable to connect to the endpoint
    * 404 - hitting an unknown endpoint on the server
    * 403 - not authorized, likely a credential issue

### How can I get a TLS thumbprint for the InsightVM credential?
Here is a set of example commands that would calculate your TLS thumbprint, where <IP address> is the IP address of your InsightVM instance:
```bash
$ (echo|openssl s_client -connect <IP address>:3780 -showcerts 2>/dev/null) | openssl x509 -inform PEM -outform DER |  openssl dgst -sha256 -binary | base64
```
An example value returned by this set of commands would look something like this: `X1NWttnkIQprK6zSre/VweKpbRlj7Dt4M6hNfUacytE=`
Use the following entry for the corresponding TLS thumbprint:
192.168.0.3:3780=SHA256:X1NWttnkIQprK6zSre/VweKpbRlj7Dt4M6hNfUacytE=