Rapid7

---
name: rapid7
description: "Expert agent for Rapid7 InsightVM. Covers console and distributed scan engine architecture, Insight Agent, Active Risk scoring, Remediation Hub, asset groups, SQL-like query for assets, dashboards, Metasploit integration, and InsightConnect SOAR automation. WHEN: \"Rapid7\", \"InsightVM\", \"Nexpose\", \"Insight Agent\", \"Active Risk\", \"Remediation Hub\", \"scan engine\", \"InsightConnect\", \"Rapid7 dashboard\"."
license: MIT
---

# Rapid7 InsightVM

This skill covers Rapid7 InsightVM (formerly Nexpose) and the Rapid7 Insight Platform. It has deep expertise in console architecture, distributed scan engine deployment, Insight Agent, Active Risk Score, Remediation Hub workflows, asset queries, dashboards, and integration with Metasploit and InsightConnect.

## How to Approach Tasks

When you receive a request:

1. **Classify** the request:
   - **Architecture / deployment** -- Load `references/architecture.md`
   - **Scanning / scan engine** -- Load `references/architecture.md` for engine details
   - **Risk scoring / prioritization** -- Apply Active Risk scoring guidance below
   - **Remediation Hub** -- Apply remediation workflow guidance
   - **Dashboards / reporting** -- Apply reporting guidance
   - **API / automation** -- Apply API guidance

2. **Identify deployment context** -- On-premises console, InsightVM Cloud (SaaS-managed console), or hybrid? Console version matters for feature availability.

3. **Load context** -- Read relevant reference file for deep knowledge.

4. **Analyze** -- Apply InsightVM-specific reasoning. Active Risk Score, remediation projects, and asset tagging are the core operational levers.

5. **Recommend** -- Provide actionable guidance with console navigation paths or API endpoint references.

## Product Overview

| Component | Description |
|---|---|
| **InsightVM Console** | Management and reporting server (on-premises or cloud-hosted) |
| **Scan Engine** | Network scanner deployed in target segments |
| **Insight Agent** | Lightweight endpoint agent (continuous assessment) |
| **InsightVM Cloud** | Rapid7-hosted console (SaaS management plane) |
| **Metasploit** | Integration for exploitability validation |
| **InsightConnect** | SOAR platform for automated remediation workflows |

**InsightVM vs. Nexpose:** Nexpose is the legacy on-premises product. InsightVM is the modern successor with cloud connectivity, Insight Agent, dashboards, and Active Risk Score. Current deployments should use InsightVM.

**Licensing:** Per-asset licensing. Each unique IP that appears in a scan counts against your license. Consult Rapid7 for license type (perpetual with maintenance vs. subscription).

## Core Concepts

### Active Risk Score

Active Risk Score is Rapid7's proprietary risk metric that combines multiple data sources to reflect real-world risk.

**Active Risk components:**
- **CVSS score** -- Technical severity baseline
- **CVSS temporal metrics** -- Exploit maturity (PoC available? Weaponized?)
- **Exploit data** -- Real-world exploit availability (Metasploit modules, ExploitDB)
- **EPSS** -- Exploitation probability (FIRST EPSS model)
- **Malware data** -- Is this CVE being used by active malware campaigns?
- **Asset context** -- Asset criticality tier (defined in InsightVM)

**Scoring:**
- Range: 0-1000 (higher = more risk)
- Factors weight: exploit availability + malware association increase score significantly
- EPSS integration: High EPSS CVEs with available exploits score highest
- Asset criticality multiplier: Same vuln scores higher on Tier 1 vs. Tier 4 assets

**Active Risk vs. CVSS:**

| Scenario | CVSS | Active Risk |
|---|---|---|
| CVE-2021-44228 (Log4Shell) on public server | 10.0 | Very High (active exploitation, Metasploit module) |
| CVE with CVSS 9.8, no public exploit, no malware | 9.8 | Medium (high severity but no active exploitation) |
| CVE with CVSS 5.0, active ransomware campaign | 5.0 | High (low base but real-world active exploitation) |

**Practical use:** Sort assets by Active Risk Score descending for prioritized remediation backlog. Ignore CVSS-only sorting -- it overweights theoretical severity.

### Asset Groups and Tags

**Asset Groups (dynamic):**
- Filter assets by IP range, OS, hostname, vulnerability status, tags
- Dynamic: Automatically includes/excludes assets as criteria match
- Used for: scan targeting, reporting scope, remediation project assignment

**Asset Tags (custom):**
- Apply business context to assets
- Tag types: Owner, Location, Department, Custom
- Example tags: `Critical-Asset`, `PCI-Scope`, `Internet-Facing`, `Production`
- Criticality levels: Very High, High, Medium, Low, Very Low

**Tag-based risk weighting:**
- "Very High" criticality tag multiplies Active Risk Score
- "Internet-Facing" tag increases priority in dashboards
- Tags used to scope compliance reports and remediation projects

### SQL-Like Asset Query

InsightVM provides a powerful SQL-like query language for asset and vulnerability search.

**Query interface:** Reports > Asset/Vulnerability Query

**Asset query examples:**
```sql
-- Find Windows servers missing critical patches
SELECT * FROM assets a
WHERE a.os_name LIKE '%Windows Server%'
AND a.id IN (SELECT asset_id FROM asset_vulnerabilities 
             WHERE cvss_score >= 9.0)

-- Assets not scanned in 30 days
SELECT * FROM assets 
WHERE last_scan_date < now() - interval '30 days'

-- Internet-facing assets with high-severity vulns
SELECT * FROM assets a
JOIN asset_tags at ON a.id = at.asset_id
JOIN tags t ON at.tag_id = t.id
WHERE t.name = 'Internet-Facing'
AND a.id IN (SELECT asset_id FROM asset_vulnerabilities 
             WHERE cvss_score >= 7.0)
```

**Vulnerability query examples:**
```sql
-- High EPSS vulnerabilities on production assets
SELECT v.title, v.cvss_score, v.epss_probability, a.ip_address, a.host_name
FROM vulnerabilities v
JOIN asset_vulnerabilities av ON v.id = av.vulnerability_id
JOIN assets a ON av.asset_id = a.id
JOIN asset_tags at ON a.id = at.asset_id
JOIN tags t ON at.tag_id = t.id
WHERE v.epss_probability > 0.1
AND t.name = 'Production'
ORDER BY v.epss_probability DESC

-- CISA KEV entries
SELECT * FROM vulnerabilities
WHERE is_known_exploited = true
AND status = 'AFFECTED'

-- Overdue critical vulns (open > 7 days)
SELECT v.title, a.host_name, av.first_found_date, a.risk_score
FROM vulnerabilities v
JOIN asset_vulnerabilities av ON v.id = av.vulnerability_id
JOIN assets a ON av.asset_id = a.id
WHERE av.status = 'affected'
AND v.cvss_score >= 9.0
AND av.first_found_date < now() - interval '7 days'
ORDER BY v.cvss_score DESC
```

## Scanning

### Scan Configuration

**Scan Templates:**
- Basic Discovery -- host enumeration, no vuln scan
- Discovery Scan -- network discovery, port scanning
- Exhaustive -- all checks, comprehensive (slow)
- Full Audit Without Web Spider -- comprehensive, no web crawling
- Microsoft Hotfix -- focused patch detection for Windows
- CIS Policy Compliance -- CIS benchmark checks
- PCI Audit -- PCI DSS compliance scan

**Critical scan settings:**
- **Credential Sets** -- Required for authenticated scanning
- **Scan Template** -- Policy defining which checks to run
- **Site** -- Asset collection (IP ranges, hostnames, asset groups)
- **Scan Engine** -- Which scanner to use
- **Schedule** -- Frequency and timing

### Sites

Sites are the primary organizational unit for scan targeting.

**Site components:**
- Asset scope (IP ranges, hostnames, asset groups)
- Credential set assignment
- Scan template
- Scan engine assignment
- Schedule

**Site design best practices:**
- Separate sites by network segment (aligns with scan engine placement)
- Separate sites by criticality (Tier 1 gets more frequent scans)
- Don't mix scan engines across WAN links in a single site (performance)
- Tag assets as they're added to sites for reporting

### Insight Agent (Rapid7)

Lightweight agent for continuous assessment of endpoints.

**Agent capabilities:**
- Continuous vulnerability assessment (not point-in-time)
- Works for remote workers, cloud VMs, assets behind NAT
- No network scan required -- local assessment
- Reports to InsightVM console via Insight platform cloud

**Agent vs. network scan:**
- Agent: Always-on, remote-friendly, no credentials to manage
- Network scan: Also sees network-level vulnerabilities, more comprehensive for servers

**Agent deployment:**
- Windows: MSI installer (SCCM, GPO, Intune)
- Linux: RPM/DEB/tgz installer
- macOS: PKG installer
- Cloud: Terraform, cloud-init, AWS SSM, Azure Arc

**Agent data flow:**
```
Endpoint Agent --> Insight Platform Cloud --> InsightVM Console
                   (cloud.insight.rapid7.com)
```

## Remediation Hub

Remediation Hub is the project-based remediation management feature in InsightVM.

### Creating Remediation Projects

**Project types:**
- **Asset-based:** Target a specific set of assets
- **Tag-based:** Target all assets with specific tags
- **Vulnerability-based:** Target specific CVEs or vulnerability categories

**Project workflow:**
1. Create project (name, description, owner, due date)
2. Define scope: assets + vulnerabilities (query-based)
3. Set goal (SLA: resolve all Critical/High by date X)
4. Assign to remediation team
5. Track progress (% closed, remaining risk reduction)
6. Verify: Re-scan assets in scope to confirm fixes
7. Close project when goal met

### Remediation Hub + ITSM Integration

**ServiceNow integration:**
- Rapid7 InsightVM app for ServiceNow
- Findings sync to ServiceNow Vulnerability Response
- Bi-directional: Status changes in ServiceNow update InsightVM

**Jira integration:**
- InsightConnect Jira connection or native Jira integration
- Create Jira issues per vulnerability or per asset+vuln
- Assign to dev/IT teams by project
- Sprint tracking for developer security workflows

**InsightConnect (SOAR) workflows:**
- Auto-create Jira/ServiceNow ticket when Critical vuln detected
- Slack notification to asset owner when KEV entry found
- Auto-close ticket when rescan verifies remediation
- Escalation workflow: ticket not resolved in 7 days -> notify manager

## Dashboards and Reporting

### Built-in Dashboard Cards

InsightVM ships with pre-built dashboard cards:

| Card | Description |
|---|---|
| Active Risk by Severity | Breakdown of risk by Critical/High/Medium/Low |
| Asset Risk Trend | Risk score over time (are we improving?) |
| Top Remediated Vulnerabilities | Positive reinforcement of remediation activity |
| Vulnerabilities by Age | How old are our open findings? |
| Assets with Known Exploited Vulnerabilities | KEV exposure dashboard |
| Remediation Projects Progress | Remediation Hub project status |
| EPSS Distribution | Open findings ranked by EPSS probability |

### Custom Dashboard Cards

Build custom cards using the SQL query engine:

```sql
-- Card: Critical vulns on internet-facing assets
SELECT COUNT(DISTINCT av.vulnerability_id) as vuln_count,
       COUNT(DISTINCT av.asset_id) as asset_count
FROM asset_vulnerabilities av
JOIN assets a ON av.asset_id = a.id
JOIN asset_tags at ON a.id = at.asset_id
JOIN tags t ON at.tag_id = t.id
JOIN vulnerabilities v ON av.vulnerability_id = v.id
WHERE t.name = 'Internet-Facing'
AND v.cvss_score >= 9.0
AND av.status = 'affected'
```

### Reports

**Built-in report templates:**
- Executive Overview -- High-level posture summary
- Vulnerability Report -- Detailed findings list
- Remediation Plan -- Prioritized fix list by asset
- Baseline Comparison -- Compare scans over time
- PCI Compliance -- PCI DSS audit report
- CIS Benchmark -- Configuration compliance report

**Scheduled reporting:**
- Schedule any report on recurrence (daily, weekly, monthly)
- Deliver to email or SFTP
- Formats: PDF, CSV, HTML, XML

## Metasploit Integration

InsightVM integrates with Rapid7 Metasploit Pro for exploitability validation.

**Integration capabilities:**
- View which InsightVM findings have Metasploit exploit modules
- Launch Metasploit campaigns from InsightVM console
- "Confirmed Risk" -- vulns that have been actively exploited in test (validates scanning findings are real)
- NeXpose results import into Metasploit Pro for targeted exploitation

**Penetration testing workflow:**
1. Run InsightVM scan to identify vulnerabilities
2. Export targets with Metasploit modules to Metasploit Pro
3. Launch exploitation campaign against scope
4. Confirmed exploits elevate asset risk in InsightVM
5. Report: "These 12 Critical vulns are confirmed exploitable in our environment"

**Note:** Metasploit integration is for authorized penetration testing. Always ensure proper authorization before exploitation testing.

## InsightVM API

**Base URL:** `https://CONSOLE_HOSTNAME:3780/api/3/`

**Authentication:** HTTP Basic (username:password) or API key

**Key endpoints:**
```
GET  /api/3/assets                    # Asset list with filters
GET  /api/3/assets/{id}               # Asset details
GET  /api/3/assets/{id}/vulnerabilities  # Asset vulnerabilities
GET  /api/3/vulnerabilities           # Vulnerability library
GET  /api/3/sites                     # Site list
POST /api/3/sites/{id}/scans          # Launch scan
GET  /api/3/scans                     # Scan history
GET  /api/3/reports                   # Report list
POST /api/3/reports                   # Create/run report
GET  /api/3/tags                      # Tag list
POST /api/3/tags                      # Create tag
```

**Python example -- export critical findings:**
```python
import requests

BASE_URL = "https://insightvm.company.com:3780/api/3"
AUTH = ("apiuser", "password")

# Get critical vulns
response = requests.get(
    f"{BASE_URL}/vulnerabilities",
    auth=AUTH,
    params={"severity": "critical", "page": 0, "size": 100},
    verify=True
)
vulns = response.json()["resources"]

for vuln in vulns:
    print(f"{vuln['id']}: {vuln['title']} "
          f"CVSS={vuln.get('cvssV3', {}).get('score', 'N/A')}")
```

## Troubleshooting

**Issue: Scan failing to complete**
- Check scan engine connectivity to targets (firewall rules)
- Review scan engine logs: `$RAPID7_HOME/logs/nsc.log`
- Reduce concurrent scan threads in scan template if targets are fragile
- Check disk space on scan engine and console (scans need temp space)

**Issue: Low vulnerability count (missing detections)**
- Verify credentials: Check scan template for credential set assignment
- Test auth: Plugin ID equivalent is "Credential Verification" in scan results
- Check Windows firewall allows WMI/SMB from scanner IP
- Verify scan template has relevant plugins enabled

**Issue: Agent not reporting**
- Check agent connectivity to `cloud.insight.rapid7.com` port 443
- Verify agent service running: `Get-Service ir_agent` (Windows)
- Review agent log: `C:\Program Files\Rapid7\Insight Agent\components\insight_agent\logs\`
- Re-register agent if key expired: delete token file and restart service

**Issue: Console performance / slow UI**
- InsightVM console is resource-hungry; recommend 8 vCPU, 32GB+ RAM for large environments
- Check PostgreSQL health (console uses embedded PostgreSQL)
- Archive old scan data: Administration > Maintenance > Data Cleanup
- Scale: use distributed scan engines to reduce load on console

## Reference Files

Load these when you need deep knowledge for a specific area:

- `references/architecture.md` -- Console architecture, distributed scan engines, Insight Agent internals, Active Risk Score computation, InsightConnect SOAR integration patterns.