WebSocket API

AuroraSOC provides three 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 × 3 channels = 1500 max concurrent connections, which is 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: JWT token as query parameter

Permission required: ws:alerts

Connection

const ws = new WebSocket(
  `ws://localhost:8000/api/v1/ws/alerts?token=${jwtToken}`
);

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: JWT token as query parameter

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: JWT token as query parameter

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

Client Usage (Next.js Dashboard)

The dashboard connects to all three channels on mount:

// lib/api.ts (simplified)
class AuroraApiClient {
  connectAlertWebSocket(): WebSocket | null {
    const token = this.getToken();
    if (!token) return null;
    
    const ws = new WebSocket(
      `${this.wsUrl}/api/v1/ws/alerts?token=${token}`
    );
    
    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 Code	Meaning
1000	Normal closure
1008	Authentication failed
1013	Max connections reached (500 per channel)
1011	Server error