Skip to main content

WebSocket API

AuroraSOC provides four WebSocket channels for real-time data streaming to the dashboard.

Architecture​

Connection Manager​

All three channels use the same ConnectionManager class:

class ConnectionManager:
    MAX_CONNECTIONS = 500  # Per channel

    def __init__(self) -> None:
        self.active: dict[str, WebSocket] = {}

    async def connect(self, ws: WebSocket, connection_id: str) -> bool:
        if len(self.active) >= self.MAX_CONNECTIONS:
            await ws.close(code=1013, reason="Max connections reached")
            return False
        await ws.accept()
        self.active[connection_id] = ws
        return True

    async def broadcast(self, data: dict) -> None:
        dead: list[str] = []
        for cid, ws in self.active.items():
            try:
                await ws.send_json(data)
            except Exception:
                dead.append(cid)
        # Auto-cleanup dead connections
        for cid in dead:
            self.active.pop(cid, None)

Why 500 connection limit?​

Each WebSocket holds an open TCP connection. At 500 connections × 4 channels = 2000 max concurrent connections, which is still well within typical Linux ulimit defaults (65536). The limit prevents runaway clients from exhausting server memory.

Channel 1: Real-Time Alerts​

Path: ws://localhost:8000/api/v1/ws/alerts

Authentication: httpOnly cookie (preferred for browser clients) or JWT query token (fallback for non-browser clients)

Permission required: ws:alerts

Connection​

// Browser clients should rely on the secure access_token cookie set by login.
const ws = new WebSocket("ws://localhost:8000/api/v1/ws/alerts");

ws.onmessage = (event) => {
  const alert = JSON.parse(event.data);
  console.log(`[${alert.severity}] ${alert.title}`);
};

Message Format​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Suspicious DNS Query to Known C2 Domain",
  "severity": "high",
  "status": "new",
  "source": "suricata",
  "iocs": [{"type": "domain", "value": "t1.evil.com"}],
  "mitre_techniques": ["T1071.004"],
  "timestamp": "2024-01-15T10:30:00Z"
}

Data Flow​

Channel 2: Agent Reasoning Traces​

Path: ws://localhost:8000/api/v1/ws/agent-thoughts

Authentication: httpOnly cookie (preferred) or JWT query token fallback

Permission required: ws:agent_thoughts

Message Format​

{
  "agent": "threat_hunter",
  "action": "Running YARA scan on endpoint",
  "case_id": "550e8400-e29b-41d4-a716-446655440000",
  "details": {
    "tool": "yara_scan",
    "target": "workstation-042",
    "rules_matched": 2
  },
  "duration_ms": 1250,
  "timestamp": "2024-01-15T10:30:15Z"
}

This channel streams the aurora:audit Redis Stream, providing live visibility into what each AI agent is doing during investigations.

Channel 3: Human Approval Notifications​

Path: ws://localhost:8000/api/v1/ws/approvals

Authentication: httpOnly cookie (preferred) or JWT query token fallback

Permission required: approvals:manage

Message Format​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "action": "Isolate workstation-042 from network",
  "case_id": "550e8400-e29b-41d4-a716-446655440001",
  "risk_level": "high",
  "status": "pending",
  "requested_by": "incident_responder",
  "context": {
    "reason": "Active C2 beacon detected, lateral movement in progress",
    "affected_users": 3,
    "confidence": 0.87
  },
  "requested_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-15T14:30:00Z"
}

Approval Workflow​

Channel 4: Investigation Receipt Updates​

Path: ws://localhost:8000/api/v1/ws/investigation-receipts

Authentication: httpOnly cookie (preferred) or JWT query token fallback

Permission required: cases:read

Message Format​

{
  "event": "investigation_receipt_updated",
  "timestamp": "2026-05-04T14:20:00Z",
  "case_id": "550e8400-e29b-41d4-a716-446655440001",
  "network_attack_id": "550e8400-e29b-41d4-a716-446655440002",
  "receipt": {
    "assignment_id": "assign-123",
    "task_id": "task-123",
    "status": "completed",
    "summary": "DNS tunneling activity remains active from a single workstation"
  },
  "case": { "id": "550e8400-e29b-41d4-a716-446655440001" },
  "network_attack": { "id": "550e8400-e29b-41d4-a716-446655440002" }
}

This channel is emitted directly by the API after _persist_agent_result_effects() commits the updated case timeline, note, and linked network-attack receipt. It lets the cases and network command center surfaces replace their in-memory records without refetching.

Client Usage (Next.js Dashboard)​

The dashboard connects to all three channels on mount:

// lib/api.ts (simplified)
class AuroraApiClient {
  connectAlertWebSocket(): WebSocket | null {
    const ws = new WebSocket(`${this.wsUrl}/api/v1/ws/alerts`);
    
    ws.onopen = () => console.log('Alert stream connected');
    ws.onerror = (e) => console.error('Alert WS error:', e);
    ws.onclose = () => {
      // Auto-reconnect after 3 seconds
      setTimeout(() => this.connectAlertWebSocket(), 3000);
    };
    
    return ws;
  }
}

Error Codes​

WebSocket Close CodeMeaning
1000Normal closure
4001Authentication failed (missing/invalid token or cookie)
1013Max connections reached (500 per channel)
1011Server error