A modern Python client library for Rapid7 InsightVM API. Built with industry-standard patterns, comprehensive type hints, and a clean, intuitive interface.
- Modern Authentication - HTTPBasicAuth integration following industry standards
- Unified Client Interface - Single entry point with organized sub-clients
- Comprehensive Asset Management - Full CRUD operations with auto-pagination
- Asset Group Operations - Create, update, delete, and manage dynamic groups
- Site Management - Complete site lifecycle management and configuration
- Scan Operations - Start, stop, pause, resume, and monitor vulnerability scans
- Report Management - Generate, download, and manage security reports
- Sonar Query Integration - Query and analyze Sonar data
- Type-Safe - Complete type hints throughout the codebase
- Self-Signed Certificate Support - Configurable SSL verification for enterprise environments
- Context Manager Support - Proper resource cleanup
- Well Documented - Comprehensive docstrings and examples
# Clone the repository
git clone https://github.com/talltechy/insightvm-python.git
cd insightvm-python
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txtCreate a .env file in the project root (see .env.example for template).
Do NOT commit real credentials. Use .env.example as a template for local development only, and use your platform's secret manager (GitHub Secrets, AWS Secrets Manager, Azure Key Vault, etc.) for CI and production settings.
Example placeholders (do not commit real values):
# Rapid7 InsightVM API (placeholders - DO NOT COMMIT)
INSIGHTVM_API_USERNAME=<INSIGHTVM_API_USERNAME>
INSIGHTVM_API_PASSWORD=<INSIGHTVM_API_PASSWORD>
INSIGHTVM_BASE_URL=https://your-console:3780
# SSL Configuration (optional)
INSIGHTVM_VERIFY_SSL=false # Set to false only for trusted development/testing environmentsSee .github/copilot-instructions.md for Copilot-specific guidance on generating examples and handling secrets safely.
from rapid7 import InsightVMClient
# Create client (loads credentials from environment)
with InsightVMClient() as client:
# Asset Management
assets = client.assets.list(page=0, size=100)
print(f"Found {len(assets['resources'])} assets")
# Scan Operations
scan_id = client.scans.start_site_scan(
site_id=123,
scan_name="Security Audit"
)
print(f"Started scan: {scan_id}")
# Report Generation
content = client.reports.generate_and_download(
report_id=42,
timeout=3600
)
with open("security_report.pdf.gz", "wb") as f:
f.write(content)
# Asset Group Management
group = client.asset_groups.create_high_risk(
name="Critical Assets",
threshold=25000
)
print(f"Created group: {group['name']}")- API Reference - Complete API documentation
- Usage Examples - Practical code examples
- Migration Guide - Upgrading from v1.0 to v2.0
- Contributing - Development guidelines
- Scans API - Scan management and monitoring
- Reports API - Report generation and download
- Site Management - Site operations and configuration
- UI Improvements - User interface enhancements
insightvm-python/
├── src/rapid7/ # Main package
│ ├── auth.py # Authentication classes
│ ├── client.py # InsightVMClient
│ ├── config.py # Configuration management
│ ├── constants.py # API constants
│ ├── ui.py # User interface utilities
│ └── api/ # API modules
│ ├── base.py # BaseAPI foundation
│ ├── assets.py # Asset operations
│ ├── asset_groups.py # Asset group operations
│ ├── scans.py # Scan management
│ ├── reports.py # Report generation
│ ├── sites.py # Site management
│ └── sonar_queries.py # Sonar integration
├── docs/ # Documentation
│ ├── API_REFERENCE.md
│ ├── SCANS_API.md
│ ├── REPORTS_API.md
│ └── ...
├── requirements.txt # Dependencies
├── .env.example # Configuration template
└── SECURITY.md # Security policy
BaseAPI Inheritance - All API modules inherit from a common base class:
from rapid7.api.base import BaseAPI
class ScansAPI(BaseAPI):
MAX_PAGE_SIZE = 500 # Optimization constant
def list(self, page=0, size=500):
size = min(size, self.MAX_PAGE_SIZE)
return self._request('GET', 'scans', params={'page': page, 'size': size})Unified Client - Single entry point with sub-clients:
client = InsightVMClient()
client.assets.list() # Asset operations
client.asset_groups.list() # Asset group operations
client.scans.list() # Scan operations
client.reports.list() # Report operations
client.sites.list() # Site operations
client.sonar_queries.list() # Sonar operationsfrom rapid7 import InsightVMClient
# Explicit credentials
client = InsightVMClient(
username="admin",
password="password",
base_url="https://console:3780",
verify_ssl=False,
timeout=(10, 90) # (connect, read) timeouts
)# Start a scan for a site
scan_id = client.scans.start_site_scan(
site_id=123,
scan_name="Monthly Security Scan",
scan_template_id="full-audit-without-web-spider"
)
# Monitor scan progress
scan = client.scans.get_scan(scan_id)
print(f"Status: {scan['status']}")
print(f"Progress: {scan.get('tasks', {}).get('pending', 0)} tasks pending")
# Wait for completion
final_scan = client.scans.wait_for_completion(
scan_id,
poll_interval=60,
timeout=7200
)
# Stop a running scan if needed
client.scans.stop_scan(scan_id)# List available report templates
templates = client.reports.get_templates()
for template in templates['resources']:
print(f"{template['id']}: {template['name']}")
# Generate and download a report
content = client.reports.generate_and_download(
report_id=42,
poll_interval=30,
timeout=3600
)
# Save the report (usually GZip compressed)
with open("vulnerability_report.pdf.gz", "wb") as f:
f.write(content)
# Or manage report generation manually
instance_id = client.reports.generate(report_id=42)
client.reports.wait_for_completion(42, instance_id)
report_content = client.reports.download(42, instance_id)# Get all assets (handles pagination automatically)
all_assets = client.assets.get_all(batch_size=500)
print(f"Total assets: {len(all_assets)}")
# Get all scans across all pages
all_scans = client.scans.get_all_scans()
print(f"Total scans: {len(all_scans)}")
# Get all reports
all_reports = client.reports.get_all_reports()
print(f"Total reports: {len(all_reports)}")# Search for high-risk Windows servers
results = client.assets.search({
"filters": [
{"field": "risk-score", "operator": "is-greater-than", "value": 20000},
{"field": "operating-system", "operator": "contains", "value": "Windows Server"}
],
"match": "all"
})
# Filter scans by status
active_scans = client.scans.list(active=True)import requests
try:
client = InsightVMClient()
# Start a scan
scan_id = client.scans.start_site_scan(site_id=123)
# Wait for completion with timeout
result = client.scans.wait_for_completion(
scan_id,
timeout=3600
)
except ValueError as e:
print(f"Configuration error: {e}")
except TimeoutError as e:
print(f"Operation timed out: {e}")
except requests.exceptions.RequestException as e:
print(f"API error: {e}")- No Hardcoded Credentials - All credentials loaded from environment variables
- HTTPS Only - All API communication over secure connections
- SSL Verification - Configurable for self-signed certificates (see SECURITY.md)
- Secret Management - Use
.envfor development, secret management services for production - HTTPBasicAuth - Industry-standard authentication pattern
- Timeout Configuration - Prevent hanging connections
This project enforces a strict secrets policy to avoid accidental credential leaks:
- Never store API keys, passwords, tokens, or private keys in the repository or documentation examples.
- Examples should reference environment variables or secret manager usage (e.g.
os.getenv('INSIGHTVM_API_PASSWORD')) and use placeholders such as<INSIGHTVM_API_PASSWORD>when needed. - For development, use a local
.env(gitignored). For CI and production, use a secret manager (GitHub Secrets, AWS Secrets Manager, Azure Key Vault, etc.). - See
.github/copilot-instructions.mdfor additional guidance used by GitHub Copilot when generating or editing code.
verify_ssl=False, you bypass SSL certificate validation. Only use this in trusted environments with self-signed certificates.
See SECURITY.md for complete security policy and vulnerability reporting.
# Install test dependencies (included in requirements.txt)
pip install -r requirements.txt
# Run all tests
pytest
# Run with coverage report (local)
pytest --cov=src --cov-report=html
# Run specific test files
pytest tests/test_auth.py
pytest tests/test_client.py
pytest tests/test_rapid7/
# Run tests in verbose mode
pytest -v
# Run tests with coverage and open HTML report
pytest --cov=src --cov-report=html && open htmlcov/index.htmlFor testing in an environment matching CI/CD:
# Build and run tests in Docker
./.docker-test.sh
# Or manually:
docker build -f Dockerfile.test -t insightvm-test:local .
docker run --rm insightvm-test:localThis provides a consistent testing environment that matches the GitHub Actions workflow.
This project includes automated test coverage reporting with Codacy integration:
- CI/CD Coverage: Tests run automatically on push and PR to
main/develop - Coverage Reporting: Uploaded to Codacy dashboard in real-time
- Multi-Python Support: Tested across Python 3.8-3.12
- Coverage Format: Cobertura XML for Codacy compatibility
Current Coverage Targets: 30-40% baseline with room for expansion
tests/
├── __init__.py
├── conftest.py # Shared fixtures and utilities
├── test_auth.py # Authentication module tests
├── test_client.py # Client initialization tests
└── test_rapid7/ # Rapid7 API module tests
├── __init__.py
├── test_base.py # Base API functionality
└── test_assets.py # Assets API examples
The v2.0 release has been tested against live InsightVM instances:
- ✅ Authentication with HTTPBasicAuth
- ✅ Asset retrieval and management (1182+ assets tested)
- ✅ Asset group creation and management
- ✅ Scan operations (start, stop, pause, resume)
- ✅ Report generation and download
- ✅ Site management operations
- ✅ Self-signed certificate handling
- ✅ Auto-pagination for large datasets
- Python 3.8+
- requests >= 2.31.0
- python-dotenv >= 1.0.0
- urllib3 >= 2.0.0
Core Refactoring:
- ✅ Replaced manual Base64 encoding with HTTPBasicAuth
- ✅ Unified client interface with sub-clients
- ✅ BaseAPI inheritance pattern for all modules
- ✅ Type hints throughout
- ✅ Context manager support
- ✅ SSL verification configuration
Sprint 3: Core Operations (COMPLETE - 100%):
- ✅ Scans API - Complete scan lifecycle management (Issue #66, PR #84)
- Start, stop, pause, resume scans
- Monitor scan progress and status
- Site-based and adhoc scanning
- Scan history and statistics
- ✅ Reports API - Full report management (Issue #67, PR #84)
- Report configuration CRUD
- Report generation and monitoring
- Download report content
- Template and format discovery
- ✅ Scan Engines API - Engine and pool management (Issue #68, PR #85)
- CRUD operations for scan engines
- Engine pool management
- Health monitoring and load balancing
- Site and scan associations
- ✅ Scan Templates API - Template management (Issue #69, PR #86)
- Template CRUD operations
- Discovery configuration (asset, service, performance)
- Service discovery settings
- Performance optimization helpers
- ✅ Sites API Standardization (Commit f5980df)
- Refactored to follow standardized BaseAPI pattern
- Created
SiteManagementToolsutility class for advanced operations - See SITE_MANAGEMENT.md for migration guide
- ✅ Optimization Patterns
- MAX_PAGE_SIZE constants for efficient pagination
- Enhanced timeout validation
- Type consistency improvements
Previously Supported:
- ✅ Comprehensive asset and asset group operations
- ✅ Sonar query integration
Breaking Changes:
⚠️ Scan Engines API Method Renames (v2.0.x): Three methods renamed to avoid BaseAPI conflictsget(engine_id)→get_engine(engine_id)update(engine_id)→update_engine(engine_id)delete(engine_id)→delete_engine(engine_id)
⚠️ Sites API Standardization: Custom helper methods moved toSiteManagementTools⚠️ See MIGRATION.md for complete upgrade guide from v1.0⚠️ See SITE_MANAGEMENT.md for Sites API migration details
- Initial release with basic functionality
Contributions are welcome! Please read CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch (
git checkout -b feature/issue-XX-description) - Follow the GitHub workflow (issues → branches → PRs)
- Commit with conventional commit format
- Push to the branch (
git push origin feature/issue-XX-description) - Open a Pull Request
Sprint 3: Core Operations ✅ COMPLETE (100%)
- ✅ Issue #66: Scans API Module (COMPLETE - PR #84)
- ✅ Issue #67: Reports API Module (COMPLETE - PR #84)
- ✅ Issue #68: Scan Engines API Module (COMPLETE - PR #85)
- ✅ Issue #69: Scan Templates API Module (COMPLETE - PR #86)
- ✅ Sites API Standardization (COMPLETE - Commit f5980df)
Sprint 4: Vulnerabilities & Remediation (NEXT - High Priority)
- ⏳ Issue #70: Vulnerabilities API Module
- ⏳ Issue #71: Solutions API Module
- ⏳ Issue #72: Vulnerability Exceptions API Module
This project is licensed under the MIT License - see the LICENSE file for details.
- Rapid7 for the InsightVM API
- The Python requests library maintainers
- Contributors to this project
For issues, questions, or contributions, please:
- Open an issue on GitHub
- Check the documentation
- Review the examples
- See SECURITY.md for security concerns
Note: This is v2.0 with breaking changes from v1.0. See MIGRATION.md for upgrade instructions.