> ## Documentation Index
> Fetch the complete documentation index at: https://support.configview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rapid7 setup

ConfigView pulls your Rapid7 InsightVM asset inventory through the **Insight Platform API**, using a platform API key scoped to your Insight region.

You will end up with **2 secrets** in ConfigView (`RAPID7_API_KEY`, `RAPID7_REGION_URL`) when setup is complete.

> **Region matters as much as the key.** Insight platform keys are issued per region and are only valid against that region's host. A perfectly good key pointed at the wrong region returns `401`, exactly like a bad key — so if authentication fails, check the region before you reissue anything.

***

## Step 1: Create the Insight Platform API key

1. Sign in to the [Rapid7 Insight Platform](https://insight.rapid7.com/) as a **Platform Administrator**
2. Open **Settings** → **API Keys**
3. Create an **Organization** key (not a user key — user keys stop working when that user is deactivated)
4. **Name:** `ConfigView`
5. Copy the key when it is shown. You will not be able to see it again.

Note the region you are signed in to — it is in the URL of the Insight console (for example `us`, `eu`, `ca`, `au`, `ap`). You need it in the next step.

***

## Step 2: Add the secrets to ConfigView

1. Go to your ConfigView dashboard: `https://{companyname}.configview.com/admin/integrations/rapid7`
2. Under **Credentials**, enter each value and click the save icon on its row:

| Secret name         | Value                                                       | Example                     |
| ------------------- | ----------------------------------------------------------- | --------------------------- |
| `RAPID7_API_KEY`    | The key from Step 1                                         |                             |
| `RAPID7_REGION_URL` | The bare region host — **no** `https://`, no trailing slash | `us.api.insight.rapid7.com` |

***

## Step 3: Enable the Rapid7 script in ConfigView

1. Go to: `https://{companyname}.configview.com/admin/integrations/rapid7`
2. Click **Connect**. ConfigView creates its tables and schedules every collector at your default run time.
3. The collectors it will start running — stop any you do not want under **Collectors**:
4. Click **Verify now** to confirm the credentials work.

| Script     | Notes                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Assets** | Every asset InsightVM knows about — host, addressing, OS, vulnerability counts by severity, scan recency, and risk score. |

***

## Step 4: Verify

1. Go to: `https://{companyname}.configview.com/admin/integrations/rapid7`
2. Click **Verify now** to confirm the credentials work.

The check reports how many assets are visible, which is the useful signal — a key that authenticates but sees nothing is a permissions problem, not a connectivity one.

If a check fails:

* **`401`** — Either the key is wrong or `RAPID7_REGION_URL` names the wrong region. The health check names the region it tried, so compare that against your Insight console URL first.
* **`404`** — `RAPID7_REGION_URL` is malformed. It should be the bare host (`us.api.insight.rapid7.com`), not a full URL and not a path.
* **Authenticates but 0 assets** — The key's organization has no assets in scope. Check the key was created at organization level rather than for a single user with limited access.

***

## Data Tables

Once the script runs, the table is created in your database. It includes a `run_at` column for historical tracking.

| Table           | Source                                           | Key Columns                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `rapid7_assets` | `POST https://{region}/vm/v4/integration/assets` | rapid7\_id, host\_name, ip, mac, type, os\_name, os\_family, os\_version, os\_vendor, os\_architecture, risk\_score, critical\_vulnerabilities, severe\_vulnerabilities, moderate\_vulnerabilities, total\_vulnerabilities, exploits, malware\_kits, last\_scan\_start, last\_scan\_end, last\_assessed\_for\_vulnerabilities, assessed\_for\_vulnerabilities, assessed\_for\_policies, credential\_assessments, tags, unique\_identifiers, new\_items, remediated |

***

## Things worth knowing

**There is no serial number.** `rapid7_assets` identifies machines by hostname, IP and MAC — not by hardware serial. That matters if you want to reconcile Rapid7 against an MDM inventory like Kandji or Intune, which key on serial. The join has to go through hostname or MAC, and both are less reliable: hostnames get renamed, and a laptop with a dock has several MACs. Plan for a name-to-serial bridge rather than expecting a clean key.

**`assessed_for_vulnerabilities` is the column that decides whether a row means anything.** An asset InsightVM has discovered but never scanned still appears here, with zero vulnerability counts. Counting rows without filtering on that flag will make your coverage look better than it is — the zeros are unscanned, not clean.

**The API is a POST, and it pages.** ConfigView pulls 500 assets per request and follows the index until the response is empty. Nothing to configure; it matters only if you are reading run logs and wondering why one script makes many calls.