# Rapid7 insightvm

Connecting Rapid7 InsightVM gives SureCloud read access to your InsightVM console's asset inventory, vulnerability findings, scan site configuration, and remediation project status. SureCloud collects open vulnerability findings by severity and CVE, verifies that all critical asset groups have active scan coverage through correctly configured sites and scan templates, tracks remediation project progress to surface findings that have been assigned for remediation but not yet resolved, and monitors asset risk scores over time. This provides continuous evidence that your vulnerability management programme is scanning the full asset estate and driving findings to resolution.

{% hint style="info" %}
SureCloud connects to Rapid7 InsightVM using Basic Authentication with a dedicated service account. InsightVM's REST API uses HTTP Basic Auth with the console account username and password. For cloud-hosted InsightVM (Insight Platform), an API key can be used instead.
{% endhint %}

## Authentication and setup

{% tabs %}
{% tab title="InsightVM Console (on-premises)" %}
{% stepper %}
{% step %}

#### Create a dedicated service account in InsightVM

In the InsightVM Security Console, navigate to **Administration → Users → Create User** and configure:

* **Login**: `surecloud-ccm`
* **Role**: **Global Viewer** — provides read-only access to all sites, assets, and vulnerabilities

Do not assign site-specific roles — Global Viewer ensures SureCloud can read data across all sites without requiring per-site role grants.
{% endstep %}

{% step %}

#### Confirm the console API is accessible

The InsightVM REST API is hosted on the Security Console at port `3780` by default:

`https://{console-hostname}:3780/api/3`

Confirm port 3780 is reachable from SureCloud's outbound IP ranges. If your console uses a non-default port, substitute accordingly.
{% endstep %}

{% step %}

#### Enter credentials in SureCloud

In SureCloud, navigate to **Integrations → Rapid7 InsightVM → Connect** and provide:

* **Console URL** (e.g. `https://insightvm.yourcompany.com:3780`)
* **Username**: `surecloud-ccm`
* **Password**

Click **Test Connection**, then **Save**.

{% hint style="warning" %}
If the service account password is rotated in InsightVM, update it in **SureCloud → Integrations → Rapid7 InsightVM → Edit Connection** immediately to avoid a data collection gap.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Insight Platform (cloud)" %}
{% stepper %}
{% step %}

#### Generate an Insight Platform API key

Log in to the [Insight Platform](https://insight.rapid7.com/) and navigate to **API Keys → New User Key**.

* **Name**: `SureCloud CCM`

Copy the key value immediately.
{% endstep %}

{% step %}

#### Enter credentials in SureCloud

In SureCloud, navigate to **Integrations → Rapid7 InsightVM → Connect (Cloud)** and provide:

* **Insight Platform region** (US, EU, CA, AU, AP — visible in your platform URL)
* **API key**

Click **Test Connection**, then **Save**.

{% hint style="warning" %}
Insight Platform API keys do not expire automatically. Rotate this key every 90 days and update it in **SureCloud → Integrations → Rapid7 InsightVM → Edit Connection**.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

## Endpoints

| API Call                                 | Use Case                                                                         |
| ---------------------------------------- | -------------------------------------------------------------------------------- |
| `GET /api/3/assets`                      | Enumerate all assets with risk score, last scan date, and OS information         |
| `GET /api/3/assets/{id}`                 | Read full asset record including installed software, services, and user accounts |
| `GET /api/3/assets/{id}/vulnerabilities` | Read vulnerability findings per asset with severity, CVSS score, and CVE         |
| `GET /api/3/vulnerabilities`             | Enumerate the vulnerability definitions present in the environment               |
| `GET /api/3/sites`                       | List all scan sites and their scan template and credential configuration         |
| `GET /api/3/sites/{id}/scans`            | Read scan history for each site including last completed scan time and status    |
| `GET /api/3/scans`                       | List all scans across all sites with their completion status and asset coverage  |
| `GET /api/3/reports`                     | Enumerate generated reports; verify scheduled vulnerability reports are running  |
| `GET /api/3/users`                       | Enumerate console users and their role and site assignments                      |
| `GET /api/3/tags`                        | List asset tags used for grouping and scoping                                    |

## Pagination

The InsightVM REST API uses page-based pagination via `page` and `size` query parameters. The response `page` object contains `totalPages` and `number` fields. SureCloud increments the `page` parameter until `number` equals `totalPages - 1`.

```json
{
  "page": {
    "totalResources": 12483,
    "totalPages": 125,
    "pageSize": 100,
    "number": 0
  },
  "resources": [
    {
      "id": 100423,
      "ip": "10.0.1.42",
      "hostName": "db-prod-01.yourcompany.com",
      "riskScore": 847.3,
      "vulnerabilities": { "critical": 2, "severe": 11, "moderate": 34 }
    }
  ]
}
```

SureCloud requests up to 500 resources per page using `size=500`.

## Required permissions

The **Global Viewer** role is required for full data collection across all sites and assets. Site-scoped roles restrict SureCloud to only the assets within the assigned sites, producing an incomplete view.

For Insight Platform API keys, the key inherits the permissions of the user account that generated it. Ensure the account holds the **Viewer** role across all sites.

## Polling frequency

| Data type                        | Collection interval |
| -------------------------------- | ------------------- |
| Asset inventory and risk scores  | 24 hours            |
| Vulnerability findings           | 24 hours            |
| Scan site configuration          | 24 hours            |
| Scan history and last-run status | 24 hours            |
| Console user inventory           | 24 hours            |

## Troubleshooting

<details>

<summary>Test Connection fails with "Connection refused" on port 3780</summary>

Port 3780 is the default InsightVM Security Console API port and must be reachable from SureCloud's outbound IP ranges. This is a firewall or network access issue rather than a credential problem.

Confirm port 3780 is open on the host running the InsightVM Security Console and is accessible from SureCloud. Test connectivity with: `curl -k https://insightvm.yourcompany.com:3780/api/3` — a valid response includes a JSON object with an API version field.

</details>

<details>

<summary>Assets from some sites are not appearing</summary>

If the service account has a site-scoped role rather than Global Viewer, only assets within the assigned sites will be returned. Navigate to **InsightVM → Administration → Users → \[surecloud-ccm] → Roles** and confirm the account has the **Global Viewer** role, not a site-specific role.

</details>

<details>

<summary>Vulnerability findings are present but CVE identifiers are missing for some</summary>

Not all InsightVM vulnerability checks map to a CVE. Configuration compliance checks, missing patches for non-CVE advisories, and informational findings do not have CVE references. SureCloud reports CVE data where available and omits the field for findings without a CVE.

If CVEs are expected but missing for specific findings, check the vulnerability definition in **InsightVM → Vulnerabilities → \[Finding]** — if no CVE is listed in the definition, none will appear in SureCloud.

</details>

<details>

<summary>Scan history shows no recent scans for some sites</summary>

Sites must have an active scan schedule or have been manually triggered to produce scan records. A site with no scan history indicates the site has been configured but no scans have been initiated.

In **InsightVM → Sites → \[Site] → Scan Schedule**, confirm a schedule is configured and active. Alternatively, initiate a manual scan to verify connectivity and asset discovery.

</details>

<a href="https://help.rapid7.com/insightvm/en-us/api/index.html" class="button secondary">Rapid7 InsightVM API reference</a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/rapid7-insightvm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.