Skip to content

Commit 22ac997

Browse files
talltechytalltechy
authored
Merge pull request #103 from talltechy/copilot/review-core-api-files
Add comprehensive API review documentation with Context7 verification
2 parents ad874ec + 07c66be commit 22ac997

10 files changed

+876
-0
lines changed

‎docs/API_ENDPOINT_REFERENCE.md‎

Lines changed: 366 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,366 @@
1+
# InsightVM API v3 Endpoint Reference
2+
3+
## Quick Reference Guide
4+
5+
This document provides a quick reference for all InsightVM API v3 endpoints used in the insightvm-python library, verified against the official Rapid7 API documentation.
6+
7+
**Last Updated:** 2025-10-13
8+
**API Version:** 3
9+
**Base URL Format:** `{base_url}/api/3/{endpoint}`
10+
11+
---
12+
13+
## Endpoint Naming Convention
14+
15+
⚠️ **IMPORTANT:** InsightVM API v3 uses **underscores** (_) not hyphens (-) for multi-word endpoint names.
16+
17+
✅ **Correct:** `/api/3/scan_engines`
18+
❌ **Incorrect:** `/api/3/scan-engines`
19+
20+
---
21+
22+
## Core Endpoints
23+
24+
### Assets
25+
```
26+
GET /api/3/assets - List all assets
27+
GET /api/3/assets/{id} - Get specific asset
28+
POST /api/3/assets/search - Search assets with criteria
29+
GET /api/3/assets/{id}/vulnerabilities - Get asset vulnerabilities
30+
GET /api/3/assets/{id}/software - Get installed software
31+
GET /api/3/assets/{id}/tags - Get asset tags
32+
PUT /api/3/assets/{id}/tags/{tagId} - Add tag to asset
33+
DELETE /api/3/assets/{id}/tags/{tagId} - Remove tag from asset
34+
```
35+
36+
**Module:** `src/rapid7/api/assets.py`
37+
**Client Access:** `client.assets`
38+
39+
---
40+
41+
### Asset Groups
42+
```
43+
GET /api/3/asset_groups - List all asset groups
44+
POST /api/3/asset_groups - Create asset group
45+
GET /api/3/asset_groups/{id} - Get specific group
46+
PUT /api/3/asset_groups/{id} - Update asset group
47+
DELETE /api/3/asset_groups/{id} - Delete asset group
48+
GET /api/3/asset_groups/{id}/assets - Get assets in group
49+
PUT /api/3/asset_groups/{id}/assets/{assetId} - Add asset to group
50+
DELETE /api/3/asset_groups/{id}/assets/{assetId} - Remove asset from group
51+
```
52+
53+
**Module:** `src/rapid7/api/asset_groups.py`
54+
**Client Access:** `client.asset_groups`
55+
56+
---
57+
58+
### Sites
59+
```
60+
GET /api/3/sites - List all sites
61+
POST /api/3/sites - Create site
62+
GET /api/3/sites/{id} - Get specific site
63+
PUT /api/3/sites/{id} - Update site
64+
DELETE /api/3/sites/{id} - Delete site
65+
GET /api/3/sites/{id}/assets - Get site assets
66+
GET /api/3/sites/{id}/scan_engine - Get site scan engine
67+
PUT /api/3/sites/{id}/scan_engine - Set site scan engine
68+
GET /api/3/sites/{id}/scan_template - Get site scan template
69+
PUT /api/3/sites/{id}/scan_template - Set site scan template
70+
POST /api/3/sites/{id}/scans - Start site scan
71+
GET /api/3/sites/{id}/scans - List site scans
72+
```
73+
74+
**Module:** `src/rapid7/api/sites.py`
75+
**Client Access:** `client.sites`
76+
77+
---
78+
79+
### Scans
80+
```
81+
GET /api/3/scans - List all scans
82+
GET /api/3/scans/{id} - Get specific scan
83+
POST /api/3/scans/{id}/stop - Stop scan
84+
POST /api/3/scans/{id}/pause - Pause scan
85+
POST /api/3/scans/{id}/resume - Resume scan
86+
POST /api/3/sites/{id}/scans - Start site scan
87+
```
88+
89+
**Module:** `src/rapid7/api/scans.py`
90+
**Client Access:** `client.scans`
91+
92+
---
93+
94+
### Scan Engines
95+
```
96+
GET /api/3/scan_engines - List all scan engines
97+
POST /api/3/scan_engines - Create scan engine
98+
GET /api/3/scan_engines/{id} - Get specific engine
99+
PUT /api/3/scan_engines/{id} - Update scan engine
100+
DELETE /api/3/scan_engines/{id} - Delete scan engine
101+
GET /api/3/scan_engines/{id}/sites - Get engine sites
102+
GET /api/3/scan_engines/{id}/scans - Get engine scans
103+
GET /api/3/scan_engines/shared_secret - Get shared secret
104+
POST /api/3/scan_engines/shared_secret - Create shared secret
105+
DELETE /api/3/scan_engines/shared_secret - Revoke shared secret
106+
```
107+
108+
**Module:** `src/rapid7/api/scan_engines.py`
109+
**Client Access:** `client.scan_engines`
110+
111+
---
112+
113+
### Scan Engine Pools
114+
```
115+
GET /api/3/scan_engine_pools - List all engine pools
116+
POST /api/3/scan_engine_pools - Create engine pool
117+
GET /api/3/scan_engine_pools/{id} - Get specific pool
118+
PUT /api/3/scan_engine_pools/{id} - Update engine pool
119+
DELETE /api/3/scan_engine_pools/{id} - Delete engine pool
120+
GET /api/3/scan_engine_pools/{id}/engines - Get pool engines
121+
PUT /api/3/scan_engine_pools/{id}/engines - Set pool engines
122+
PUT /api/3/scan_engine_pools/{id}/engines/{engineId} - Add engine to pool
123+
DELETE /api/3/scan_engine_pools/{id}/engines/{engineId} - Remove engine from pool
124+
```
125+
126+
**Module:** `src/rapid7/api/scan_engines.py`
127+
**Client Access:** `client.scan_engines` (pool methods)
128+
129+
---
130+
131+
### Scan Templates
132+
```
133+
GET /api/3/scan_templates - List all templates
134+
GET /api/3/scan_templates/{id} - Get specific template
135+
```
136+
137+
**Module:** `src/rapid7/api/scan_templates.py`
138+
**Client Access:** `client.scan_templates`
139+
140+
---
141+
142+
### Reports
143+
```
144+
GET /api/3/reports - List all reports
145+
POST /api/3/reports - Create report
146+
GET /api/3/reports/{id} - Get specific report
147+
PUT /api/3/reports/{id} - Update report
148+
DELETE /api/3/reports/{id} - Delete report
149+
POST /api/3/reports/{id}/generate - Generate report
150+
GET /api/3/reports/{id}/history - Get report history
151+
GET /api/3/reports/{id}/history/{instance}/output - Download report
152+
```
153+
154+
**Module:** `src/rapid7/api/reports.py`
155+
**Client Access:** `client.reports`
156+
157+
---
158+
159+
### Vulnerabilities
160+
```
161+
GET /api/3/vulnerabilities - List all vulnerabilities
162+
GET /api/3/vulnerabilities/{id} - Get specific vulnerability
163+
GET /api/3/vulnerabilities/{id}/affected_assets - Get affected assets
164+
GET /api/3/vulnerabilities/{id}/exploits - Get exploits
165+
GET /api/3/vulnerabilities/{id}/malware_kits - Get malware kits
166+
GET /api/3/vulnerabilities/{id}/references - Get references
167+
GET /api/3/vulnerabilities/{id}/solutions - Get solutions
168+
```
169+
170+
**Module:** `src/rapid7/api/vulnerabilities.py`
171+
**Client Access:** `client.vulnerabilities`
172+
173+
---
174+
175+
### Vulnerability Exceptions
176+
```
177+
GET /api/3/vulnerability_exceptions - List all exceptions
178+
POST /api/3/vulnerability_exceptions - Create exception
179+
GET /api/3/vulnerability_exceptions/{id} - Get specific exception
180+
DELETE /api/3/vulnerability_exceptions/{id} - Delete exception
181+
POST /api/3/vulnerability_exceptions/{id}/approve - Approve exception
182+
POST /api/3/vulnerability_exceptions/{id}/reject - Reject exception
183+
```
184+
185+
**Module:** `src/rapid7/api/vulnerability_exceptions.py`
186+
**Client Access:** `client.vulnerability_exceptions`
187+
188+
---
189+
190+
### Solutions
191+
```
192+
GET /api/3/solutions - List all solutions
193+
GET /api/3/solutions/{id} - Get specific solution
194+
```
195+
196+
**Module:** `src/rapid7/api/solutions.py`
197+
**Client Access:** `client.solutions`
198+
199+
---
200+
201+
### Sonar Queries
202+
```
203+
GET /api/3/sonar_queries - List all queries
204+
POST /api/3/sonar_queries - Create query
205+
GET /api/3/sonar_queries/{id} - Get specific query
206+
PUT /api/3/sonar_queries/{id} - Update query
207+
DELETE /api/3/sonar_queries/{id} - Delete query
208+
```
209+
210+
**Module:** `src/rapid7/api/sonar_queries.py`
211+
**Client Access:** `client.sonar_queries`
212+
213+
---
214+
215+
### Users
216+
```
217+
GET /api/3/users - List all users
218+
POST /api/3/users - Create user
219+
GET /api/3/users/{id} - Get specific user
220+
PUT /api/3/users/{id} - Update user
221+
DELETE /api/3/users/{id} - Delete user
222+
```
223+
224+
**Module:** `src/rapid7/api/users.py`
225+
**Client Access:** `client.users`
226+
227+
---
228+
229+
## Common Query Parameters
230+
231+
### Pagination
232+
```python
233+
page: int = 0 # Zero-based page index
234+
size: int = 500 # Number of results per page (max 500)
235+
```
236+
237+
### Sorting
238+
```python
239+
sort: List[str] # Sort criteria: ["property,ASC|DESC"]
240+
# Example: ["name,ASC", "id,DESC"]
241+
```
242+
243+
### Filtering
244+
```python
245+
filters: Dict[str, Any] # Filter parameters (endpoint-specific)
246+
```
247+
248+
---
249+
250+
## Response Structure
251+
252+
All paginated endpoints return responses in this structure:
253+
254+
```json
255+
{
256+
"page": {
257+
"number": 0,
258+
"size": 500,
259+
"totalPages": 10,
260+
"totalResources": 4523
261+
},
262+
"resources": [
263+
{
264+
"id": 123,
265+
"...": "resource data"
266+
}
267+
],
268+
"links": [
269+
{
270+
"href": "https://console:3780/api/3/...",
271+
"rel": "self"
272+
}
273+
]
274+
}
275+
```
276+
277+
---
278+
279+
## Authentication
280+
281+
All endpoints require HTTP Basic Authentication:
282+
283+
```python
284+
from rapid7 import InsightVMClient
285+
286+
# Credentials from environment variables
287+
client = InsightVMClient()
288+
289+
# Or explicit credentials
290+
client = InsightVMClient(
291+
username="admin",
292+
password="password",
293+
base_url="https://console.example.com:3780"
294+
)
295+
```
296+
297+
Required environment variables:
298+
- `INSIGHTVM_API_USERNAME`
299+
- `INSIGHTVM_API_PASSWORD`
300+
- `INSIGHTVM_BASE_URL`
301+
302+
---
303+
304+
## Usage Examples
305+
306+
### List Assets
307+
```python
308+
from rapid7 import InsightVMClient
309+
310+
client = InsightVMClient()
311+
assets = client.assets.list(page=0, size=100)
312+
313+
for asset in assets['resources']:
314+
print(f"{asset['id']}: {asset['ip']}")
315+
```
316+
317+
### Start Site Scan
318+
```python
319+
scan = client.scans.start_site_scan(
320+
site_id=123,
321+
scan_name="Security Audit",
322+
scan_template_id="full-audit-without-web-spider"
323+
)
324+
print(f"Scan started: {scan['id']}")
325+
```
326+
327+
### Generate Report
328+
```python
329+
# Start generation
330+
instance_id = client.reports.generate(report_id=42)
331+
332+
# Wait for completion
333+
instance = client.reports.wait_for_completion(42, instance_id)
334+
335+
# Download report
336+
content = client.reports.download(42, instance_id)
337+
with open('report.pdf', 'wb') as f:
338+
f.write(content)
339+
```
340+
341+
---
342+
343+
## References
344+
345+
- **Official API Documentation:** https://docs.rapid7.com/insightvm/restful-api/
346+
- **API Specification:** https://help.rapid7.com/insightvm/en-us/api/index.html
347+
- **Context7 Documentation:** https://github.com/riza/rapid7-insightvm-api-docs
348+
- **Library Documentation:** [docs/API_REFERENCE.md](./API_REFERENCE.md)
349+
350+
---
351+
352+
## Notes
353+
354+
1. All endpoints use the `/api/3/` prefix (API version 3)
355+
2. Multi-word endpoints use underscores: `scan_engines`, `asset_groups`
356+
3. Maximum page size is 500 for pagination
357+
4. SSL verification can be disabled for self-signed certificates
358+
5. All timestamps are in ISO 8601 format
359+
6. HTTP status codes follow REST conventions (200, 201, 204, 400, 401, 403, 404, 500)
360+
361+
---
362+
363+
**For detailed implementation examples and API usage, see:**
364+
- [API_REFERENCE.md](./API_REFERENCE.md) - Complete API documentation
365+
- [EXAMPLES.md](./EXAMPLES.md) - Practical code examples
366+
- [API_REVIEW_FINDINGS.md](./API_REVIEW_FINDINGS.md) - Implementation review

0 commit comments

Comments
 (0)