Rapid7 InsightVM — Security Copilot Plugin

Query your Rapid7 InsightVM data directly from Microsoft Security Copilot.
Search assets, hunt vulnerabilities, manage scans — all with natural language.

---

Why this exists

If you've ever had to jump between Security Copilot and the InsightVM console just to look up which assets have critical vulns, or check if a scan is still running — this plugin fixes that. It connects Security Copilot to the InsightVM Cloud Integrations API (v4) so you can do everything from the Copilot prompt bar.

No more tab-switching. Just ask.

---

What you can do

> Search for Windows assets with critical vulnerabilities. Page size 50. Do not truncate.

> Get full details for asset ID a1b2c3d4-default-asset-7912, include unique identifiers.

> List all scan engines with engine ID, name, hostname, status, and last seen time. Do not truncate.

> Start a scan named "Patch Tuesday Check" for asset <id> using engine <id>.

The plugin covers 12 skills across the full InsightVM API:

Skill	What it does	Type
GetHealthStatus	Check API connectivity	read
SearchAssets	Filter assets by OS, hostname, vulns, CVSS, dates	read
GetAsset	Deep-dive into a single asset	read
GetScans	List recent scans	read
GetScan	Get details of a specific scan	read
StartScan	Kick off a new scan	write
StopScan	Stop a running scan	write
GetScanEngines	List registered engines	read
GetScanEngine	Engine details and health	read
UpdateScanEngineConfiguration	Modify engine properties	write
ListSites	List all configured sites	read
SearchVulnerabilities	Search vuln database by CVSS, severity, date	read

---

Quick start

1. Generate an API key at insight.rapid7.com → User Icon → API Keys

2. In Security Copilot, go to Settings → Plugins → Manage Plugins and upload the descriptor:

• Upload rapid7-insightvm-descriptor.yaml
• Paste your API key when prompted

3. Test it:

Check Rapid7 InsightVM API health and return the full response.

You should get back: { "status": "UP" }

That's it. You're connected.

---

Searching assets — the most useful skill

SearchAssets is where you'll spend most of your time. Some examples:

What you want	Prompt
All Windows boxes	Search for Windows assets with critical vulnerabilities. Page size 50. Do not truncate.
Linux + severe	Search for Linux assets with severe vulnerabilities. Page size 50. Do not truncate.
Recently scanned	Search assets with asset filter "last_scan_end > 2026-05-08T00:00:00Z" and vulnerability filter "severity IN ['Critical', 'Severe']". Page size 50. Do not truncate. Show all rows.
Hostname search	Search for assets with hostname containing "web". Page size 50. Do not truncate.
Next page	Same search. Page 1. Page size 50. Do not truncate. Show all rows.

Things to know

• Always use page size 50. Anything higher and Copilot truncates the results. We tested 100, 200, 500 — they all lose rows.
• Always add "Do not truncate." Without it you'll get ~10 rows instead of 50.
• Always use exact dates. last_scan_end > 2026-05-08T00:00:00Z works. "Last 7 days" gives a 400 error.
• IP subnet filters don't work. ip = '10.0.0.0/8' causes a 400. Use hostname or OS filters instead.
• You'll get 3 columns: Host Name, IP Address, OS Description. That's a Copilot rendering limit, not an API limit.

Pagination

Results come back in pages. Use page size 50 — it's the only reliable option.

Search for assets with critical vulnerabilities. Page size 50. Do not truncate. Show all rows.

Need more? Page through:

Same search. Page 1. Page size 50. Do not truncate. Show all rows.

4 pages × 50 = 200 assets. Export each page to Excel.

Check total results anytime:

How many total results did the API return? Show metadata.totalResources.

---

Scan engines — get the IDs

If you want to start scans, you need engine IDs. You must explicitly request them:

List all scan engines with engine ID, name, hostname, status, and last seen time. Page size 50. Do not truncate.

Without "engine ID" in the prompt, Copilot skips that column.

---

Scans — what to expect

The scan list only gives you Scan ID, Status, and Start Time. No finish time, no engine ID, no scan name — Copilot says "not present in the data."

To get the full picture, query a specific scan:

Get full details for scan ID <scan-id>. Include details.

That's where you'll find the finish time.

---

Configuration

The plugin is set to the EU region (eu.api.insight.rapid7.com). If you need a different region, edit the servers section in the OpenAPI spec:

servers:
  - url: https://eu.api.insight.rapid7.com/vm    # active
# - url: https://us.api.insight.rapid7.com/vm    # US East 1
# - url: https://us2.api.insight.rapid7.com/vm   # US East 2
# - url: https://us3.api.insight.rapid7.com/vm   # US West 2
# - url: https://ca.api.insight.rapid7.com/vm    # Canada
# - url: https://au.api.insight.rapid7.com/vm    # Australia
# - url: https://ap.api.insight.rapid7.com/vm    # Japan / APAC
# - url: https://aps2.api.insight.rapid7.com/vm  # India
# - url: https://me1.api.insight.rapid7.com/vm   # Middle East

---

Repo structure

├── rapid7-insightvm-descriptor.yaml          # plugin descriptor (upload this to Copilot)
├── rapid7-insightvm-openapi.yaml             # OpenAPI spec (host this publicly)
├── Rapid7_InsightVM_Plugin_Confluence_Documentation.md   # full documentation
└── LICENSE

---

Documentation

The full docs are in Rapid7_InsightVM_Plugin_Confluence_Documentation.md and cover:

• All 12 skills with tested prompts and actual output columns
• Complete filter syntax reference (what works, what doesn't)
• Pagination guide with real test data (page size 50 = only reliable option)
• 6 SOC workflows with verified prompts
• Prompt cookbook — copy-paste reference table
• Known limitations and troubleshooting (15 issues)
• FAQ

---

Filter reference (cheat sheet)

Asset filters

os.family = 'Windows'
host_name CONTAINS 'web'
last_scan_end > 2026-05-08T00:00:00Z
cvss_score >= 9
vulnerability.risk > 0.0

⚠️ IP subnet filters (ip = '10.0.0.0/8') cause 400 errors. Use hostname or OS filters.

Vulnerability filters

severity IN ['Critical', 'Severe']
cvss_score >= 9
modified > 2026-01-01T00:00:00Z
denial_of_service = true

Operators

= != > >= < <= IN CONTAINS && ||

---

What doesn't work

Stuff we tested that failed — saving you the troubleshooting:

What	Why
scanned in the last 7 days	API needs ISO 8601 dates, not relative
ip = '10.0.0.0/8'	CIDR subnet filter → 400 error
Page size > 50	Copilot truncates the table
Requesting 5+ columns	Copilot shows 3 max
Engine ID in scan list	"Not present" — use GetScan instead
Date filter on vuln search	Doesn't change result ordering

---

Contributing

Found a bug? Want to add a skill? PRs are welcome.

1. Fork the repo
2. Create your branch (git checkout -b fix/something)
3. Commit and push
4. Open a PR

If you're not sure about something, open an issue first.

---

License

MIT — use it however you want.

---

If this saved you some time, consider giving it a ⭐