sica-fondt/knowledge/cyber-skills/skills/implementing-rapid7-insightvm-for-scanning/references/api-reference.md

API Reference: Rapid7 InsightVM Vulnerability Scanning

Libraries Used

Library	Purpose
requests	HTTP client for InsightVM REST API v3
json	Parse scan results and vulnerability data
base64	Encode Basic Auth credentials
os	Read INSIGHTVM_URL, INSIGHTVM_USER, INSIGHTVM_PASS

Installation

pip install requests

Authentication

InsightVM API v3 uses HTTP Basic Authentication:

import requests
import os
from requests.auth import HTTPBasicAuth

INSIGHTVM_URL = os.environ.get("INSIGHTVM_URL", "https://insightvm.example.com:3780")
auth = HTTPBasicAuth(
    os.environ["INSIGHTVM_USER"],
    os.environ["INSIGHTVM_PASS"],
)

REST API v3 Endpoints

Method	Endpoint	Description
GET	/api/3/sites	List all scan sites
GET	/api/3/sites/{id}	Get site details
POST	/api/3/sites	Create a new site
GET	/api/3/sites/{id}/assets	List assets in a site
POST	/api/3/sites/{id}/scans	Launch a scan on a site
GET	/api/3/scans	List all scans
GET	/api/3/scans/{id}	Get scan status and details
GET	/api/3/assets	List all assets
GET	/api/3/assets/{id}	Get asset details
GET	/api/3/assets/{id}/vulnerabilities	Get vulnerabilities for asset
GET	/api/3/vulnerabilities	List all known vulnerabilities
GET	/api/3/vulnerabilities/{id}	Get vulnerability details
GET	/api/3/vulnerability_checks	List vulnerability checks
GET	/api/3/scan_engines	List scan engines
GET	/api/3/reports	List generated reports
POST	/api/3/reports	Create a report configuration
POST	/api/3/reports/{id}/generate	Generate a report
GET	/api/3/tags	List all tags
GET	/api/3/policies	List compliance policies

Core Operations

List Sites

resp = requests.get(
    f"{INSIGHTVM_URL}/api/3/sites",
    auth=auth,
    params={"page": 0, "size": 100},
    timeout=30,
    verify=True,
)
for site in resp.json().get("resources", []):
    print(f"Site: {site['name']} (ID: {site['id']}) — {site.get('description', '')}")

Launch a Scan

resp = requests.post(
    f"{INSIGHTVM_URL}/api/3/sites/{site_id}/scans",
    auth=auth,
    json={"engineId": engine_id},
    timeout=30,
    verify=True,
)
scan_id = resp.json()["id"]

Poll Scan Status

import time

while True:
    resp = requests.get(
        f"{INSIGHTVM_URL}/api/3/scans/{scan_id}",
        auth=auth,
        timeout=30,
        verify=True,
    )
    status = resp.json()["status"]
    if status in ("finished", "stopped", "error"):
        break
    time.sleep(30)

Get Asset Vulnerabilities

resp = requests.get(
    f"{INSIGHTVM_URL}/api/3/assets/{asset_id}/vulnerabilities",
    auth=auth,
    params={"page": 0, "size": 500},
    timeout=60,
    verify=True,
)
vulns = resp.json().get("resources", [])
for v in vulns:
    print(f"  {v['id']} — CVSS: {v.get('cvssV3Score', 'N/A')} — {v.get('status')}")

Get Vulnerability Details

resp = requests.get(
    f"{INSIGHTVM_URL}/api/3/vulnerabilities/{vuln_id}",
    auth=auth,
    timeout=30,
    verify=True,
)
vuln = resp.json()
# Fields: title, description, cvss, severity, publishedDate, references, exploits

Generate a Report

report_config = {
    "name": "Monthly Vuln Report",
    "format": "pdf",
    "scope": {"sites": [site_id]},
    "template": "audit-report",
}
resp = requests.post(
    f"{INSIGHTVM_URL}/api/3/reports",
    auth=auth,
    json=report_config,
    timeout=30,
    verify=True,
)
report_id = resp.json()["id"]

# Generate the report
requests.post(
    f"{INSIGHTVM_URL}/api/3/reports/{report_id}/generate",
    auth=auth,
    timeout=30,
    verify=True,
)

Pagination

All list endpoints support cursor-based pagination:

def paginate(endpoint, auth, params=None):
    params = params or {}
    params.setdefault("size", 500)
    page = 0
    while True:
        params["page"] = page
        resp = requests.get(endpoint, auth=auth, params=params, timeout=60, verify=True)
        data = resp.json()
        yield from data.get("resources", [])
        if page >= data.get("page", {}).get("totalPages", 1) - 1:
            break
        page += 1

Output Format

{
  "id": 12345,
  "status": "finished",
  "vulnerabilities": {
    "critical": 3,
    "severe": 12,
    "moderate": 45,
    "total": 60
  },
  "assets": 128,
  "startTime": "2025-01-15T08:00:00Z",
  "endTime": "2025-01-15T09:45:00Z",
  "engineName": "Local Scan Engine"
}