Backend REST API & Socket.IO Event Contract

The VulnerGuard core API service (vg-core-api) exposes a RESTful JSON API and a real-time Socket.IO telemetry server under https://vulnerguard.com/api/* and https://vulnerguard.com/socket.io/*.

---

1. Authentication & Organization Endpoints

All protected endpoints require an Authorization: Bearer <jwt_token> header.

Method	Endpoint	Auth	Description
POST	/api/auth/register	Public	Register a new user, provision their default Org, and return a JWT token.
POST	/api/auth/login	Public	Authenticate with username/email and password; returns JWT token + user/org profile.
POST	/api/auth/demo	Public	Instant sandbox session login (when sandbox mode is enabled).
GET	/api/auth/me	Bearer JWT	Return current authenticated user profile, role, and active organization.
GET	/api/org/current	Bearer JWT	Return active organization details, plan tier (free/pro/enterprise), feature flags, and current monthly usage (OrgUsageMonthly).

---

2. Scanning & Vulnerability Endpoints

Method	Endpoint	Auth	Description
POST	/api/scan	Bearer JWT	Launch a multi-tool security scan. Creates a Scan row, increments OrgUsageMonthly.scans_count, and starts a SecurityAgent background thread.
GET	/api/scans	Bearer JWT	List all scans belonging to the user's organization (ordered newest first).
GET	/api/scan/<scan_id>	Bearer JWT	Retrieve live or completed scan status, progress percentage, summary, findings list, and agent logs.
POST	/api/scan/<scan_id>/approve	Bearer JWT	Approve ({"approved": true}) or skip ({"approved": false}) a gated high-risk tool step.
GET	/api/scan/<scan_id>/report	Bearer JWT	Generate and download scan report (?format=html or ?format=pdf).
GET	/api/vulnerabilities	Bearer JWT	Query normalized vulnerabilities across scans with severity filtering.
GET	/api/analytics/summary	Bearer JWT	Return aggregate KPIs (total scans, severity distribution, top discovering tools) for the Command Center.

Example: Launching a Full-Spectrum Scan (POST /api/scan)

curl -X POST https://vulnerguard.com/api/scan \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://target.example.com",
    "scan_type": "comprehensive",
    "tools": ["nmap", "subfinder", "katana", "testssl", "nuclei", "ffuf", "zap"]
  }'

Response (200 OK):

{
  "scan_id": "scan_example_01",
  "status": "started",
  "target": "https://target.example.com",
  "tools": ["nmap", "subfinder", "katana", "testssl", "nuclei", "ffuf", "zap"]
}

---

3. Direct Tool Execution & Access Request Endpoints

Method	Endpoint	Auth	Description
GET	/api/tools/status	Bearer JWT	Inspect real-time readiness (Ready / Offline), category, risk level, and approval policy for all 14 containerized security engines.
POST	/api/tools/execute	Bearer JWT	Execute a single security tool synchronously with custom params and return structured output.
POST	/api/tool-access/request	Bearer JWT	Submit a Just-In-Time (JIT) access request for a restricted tool (sqlmap, metasploit, beef, set).
GET	/api/tool-access/requests	Bearer JWT	List the current user's pending and decided JIT tool access requests.

---

4. SOC Broker Endpoints (/api/soc/*)

Method	Endpoint	Auth	Description
GET	/api/soc/overview	Bearer JWT	Aggregate health, alert counts, case counts, analyzer counts, and threat intel stats from TheHive, Cortex, MISP, and Shuffle.
POST	/api/soc/thehive/alert	Bearer JWT	Create a new alert in TheHive from a scan finding or manual triage.
POST	/api/soc/thehive/case	Bearer JWT	Open a new incident response case in TheHive.
GET	/api/soc/cortex/analyzers	Bearer JWT	List configured observable analyzers in Cortex.
POST	/api/soc/cortex/run	Bearer JWT	Run a Cortex analyzer against an observable (ip, domain, url, hash).
GET	/api/soc/misp/events	Bearer JWT	Fetch recent threat intelligence events and IOCs from MISP.
POST	/api/soc/shuffle/webhook	Bearer JWT	Trigger a Shuffle SOAR automation webhook or workflow.

---

5. Real-Time Socket.IO Event Contract

Clients connect to wss://vulnerguard.com/socket.io/ and join a scan-specific room:

Client → Server Events

• join ({"room": "<scan_id>"}): Joins the client socket to the scan room.
  • Automatic Log Buffer Replay: Immediately upon joining, the server replays every buffered log entry in agent.log_buffer (scan_update) plus current progress (scan_progress), guaranteeing zero missed output if the browser connects after fast reconnaissance tools have already started or finished.
• leave ({"room": "<scan_id>"}): Leaves the scan room.

Server → Client Events

• scan_update:

  {
    "scan_id": "scan_example_01",
    "status": "running",
    "progress": 65,
    "log": "[2026-11-03T23:20:09] Running nuclei on https://target.example.com..."
  }

• scan_progress: Emits {"scan_id": "...", "progress": 80, "current_step": {...}}.
• approval_required: Emits when a high-risk tool requires operator sign-off before execution.
• scan_completed: Emits the final results object (vulnerabilities, summary, ai_analysis, steps) when the scan finishes.