Skip to content

api.md

Latest commit

 

History

History
311 lines (216 loc) · 3.93 KB

api.md

File metadata and controls

311 lines (216 loc) · 3.93 KB
Raw

API Reference

NETRA provides a REST API at /api/v1/.

Authentication

Most endpoints require JWT authentication:

# Login to get token
curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "password"}'

# Use token in requests
curl "http://localhost:8000/api/v1/scans" \
  -H "Authorization: Bearer YOUR_TOKEN"

Scans

List Scans

GET /api/v1/scans?page=1&per_page=20&status=completed

Create Scan

POST /api/v1/scans/
Content-Type: application/json

{
  "target_id": "uuid",
  "name": "My Scan",
  "profile": "standard"
}

Get Scan

GET /api/v1/scans/{scan_id}

Update Scan

PATCH /api/v1/scans/{scan_id}
Content-Type: application/json

{
  "status": "paused"
}

Delete Scan

DELETE /api/v1/scans/{scan_id}

Get Scan Phases

GET /api/v1/scans/{scan_id}/phases

Resume Scan

POST /api/v1/scans/{scan_id}/resume

Compare Scans

POST /api/v1/scans/diff
Content-Type: application/json

{
  "scan_a_id": "uuid",
  "scan_b_id": "uuid"
}

Findings

List Findings

GET /api/v1/findings?page=1&per_page=20&severity=high&status=new

Get Finding

GET /api/v1/findings/{finding_id}

Create Finding

POST /api/v1/findings/
Content-Type: application/json

{
  "scan_id": "uuid",
  "title": "SQL Injection",
  "description": "...",
  "severity": "critical",
  "tool_source": "sqlmap"
}

Update Finding

PATCH /api/v1/findings/{finding_id}
Content-Type: application/json

{
  "status": "confirmed"
}

Mark as False Positive

POST /api/v1/findings/{finding_id}/mark-false-positive

Bulk Update

POST /api/v1/findings/bulk-update
Content-Type: application/json

{
  "finding_ids": ["uuid1", "uuid2"],
  "status": "resolved"
}

Reports

Generate Report

POST /api/v1/reports/{scan_id}/generate?report_type=executive

Get Report

GET /api/v1/reports/{report_id}

List Reports for Scan

GET /api/v1/reports/scan/{scan_id}

Delete Report

DELETE /api/v1/reports/{report_id}

Compliance

Get Compliance Score

GET /api/v1/compliance/{scan_id}/score/{framework}

Get Framework Status

GET /api/v1/compliance/{scan_id}/framework/{framework}

Get Gap Analysis

GET /api/v1/compliance/{scan_id}/gap-analysis/{framework}

Map Findings

POST /api/v1/compliance/map
Content-Type: application/json

{
  "scan_id": "uuid",
  "frameworks": ["iso27001", "pci_dss"]
}

Targets

List Targets

GET /api/v1/targets?page=1&per_page=20

Create Target

POST /api/v1/targets/
Content-Type: application/json

{
  "name": "Example.com",
  "target_type": "domain",
  "value": "example.com"
}

Import Targets

POST /api/v1/targets/import
Content-Type: multipart/form-data

file: targets.txt

Agent

Start Agent

POST /api/v1/agent/start?target=example.com&profile=standard

Get Agent Status

GET /api/v1/agent/{session_id}/status

Approve Action

POST /api/v1/agent/{session_id}/approve

Reject Action

POST /api/v1/agent/{session_id}/reject?reason=Out+of+scope

Health

Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "database": "connected"
}

WebSocket

Scan Progress

WS /ws/scans/{scan_id}

Finding Stream

WS /ws/findings

Agent Conversation

WS /ws/agent/{session_id}

Rate Limiting

Default: 100 requests per minute per IP.

Configure with NETRA_API_RATE_LIMIT:

NETRA_API_RATE_LIMIT=200/minute

OpenAPI Documentation

Interactive API docs available at: