WebSocket Protocol¶

Stentor uses WebSocket connections for real-time bidirectional communication between system components. Two independent WebSocket hubs handle different concerns:

• CockpitHub streams events to operator UI clients (beacon updates, task output, console logs)
• RelayHub manages relay agent connections (commands, heartbeats, C2 events)

Both hubs use JSON message framing over standard WebSocket connections (RFC 6455). This page documents the connection procedures, message formats, event types, and recovery mechanisms for each hub.

CockpitHub (Operator WebSocket)¶

CockpitHub is the real-time event stream between the Stentor server and operator browser clients. Every operator UI session opens a WebSocket connection to receive beacon updates, task progress, console output, and system events as they happen.

Connection¶

Endpoint: GET /api/v1/cockpit/ws

CockpitHub supports two authentication methods. Ticket-based auth is the recommended approach -- it avoids exposing long-lived JWTs in WebSocket URLs (which may appear in server logs and proxy caches).

# Step 1: Get a WebSocket ticket (valid for 30 seconds, single-use)
TICKET=$(curl -s -X POST https://stentor.app/api/v1/auth/ws-ticket \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq -r '.ticket')

# Step 2: Connect with the ticket
wscat -c "wss://stentor.app/api/v1/cockpit/ws?ticket=$TICKET"

// JavaScript: Ticket-based WebSocket connection
async function connectCockpit(apiUrl, accessToken) {
  // 1. Fetch a single-use ticket
  const res = await fetch(`${apiUrl}/v1/auth/ws-ticket`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${accessToken}` },
  });
  const { ticket } = await res.json();

  // 2. Connect using the ticket (not the JWT)
  const wsUrl = apiUrl.replace(/^http/, 'ws');
  const ws = new WebSocket(`${wsUrl}/v1/cockpit/ws?ticket=${ticket}`);

  ws.onopen = () => console.log('Connected to CockpitHub');
  ws.onmessage = (e) => {
    const event = JSON.parse(e.data);
    console.log(`[seq=${event.seq}] ${event.type}:`, event.payload);
  };

  return ws;
}

wscat -c "wss://stentor.app/api/v1/cockpit/ws?token=$ACCESS_TOKEN"

Error Responses¶

If authentication fails, the server responds with a JSON error before the WebSocket upgrade:

Message Format¶

All messages from CockpitHub are SequencedEvents -- each event is wrapped with a monotonically increasing sequence number:

{
  "seq": 42,
  "type": "beacon_update",
  "payload": {
    "beacon_id": "a1b2c3d4-...",
    "hostname": "WORKSTATION-01",
    "username": "CORP\\jsmith",
    "status": "active"
  }
}

The seq field enables clients to detect dropped messages. If your client receives seq=40 followed by seq=43, sequences 41 and 42 were dropped (see Drop Recovery).

Event Types¶

CockpitHub broadcasts the following event types to all connected operator clients.

beacon_update¶

A beacon's state has changed (new beacon registered, checkin, or status change).

{
  "seq": 1,
  "type": "beacon_update",
  "payload": {
    "beacon_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "machine_ip": "10.0.0.20",
    "hostname": "WORKSTATION-01",
    "username": "CORP\\jsmith",
    "pid": 4832,
    "last_seen": "2026-02-19T10:00:00Z",
    "status": "active"
  }
}

console_log¶

A log entry for the operator console (command input/output, info messages, errors).

{
  "seq": 2,
  "type": "console_log",
  "payload": {
    "tab_id": "beacon-a1b2c3d4",
    "timestamp": "2026-02-19T10:00:05Z",
    "type": "output",
    "text": "Directory listing of C:\\Users\\jsmith\\Desktop..."
  }
}

task_started¶

A task has been dispatched to a beacon for execution.

{
  "seq": 3,
  "type": "task_started",
  "payload": {
    "task_id": "f1e2d3c4-...",
    "beacon_id": "a1b2c3d4-...",
    "technique": "shell",
    "status": "started"
  }
}

task_completed¶

A task has finished execution on a beacon.

{
  "seq": 4,
  "type": "task_completed",
  "payload": {
    "task_id": "f1e2d3c4-...",
    "beacon_id": "a1b2c3d4-...",
    "technique": "shell",
    "status": "completed",
    "output": "Volume in drive C has no label..."
  }
}

pivot_link¶

A lateral movement link has been established between two machines (rendered as edges in the pivot graph).

{
  "seq": 5,
  "type": "pivot_link",
  "payload": {
    "from": "machine-001",
    "to": "machine-002",
    "type": "pivot",
    "method": "smb"
  }
}

lateral_movement_completed¶

A lateral movement operation has started, completed, or failed (triggers edge animations in the topology view).

{
  "seq": 6,
  "type": "lateral_movement_completed",
  "payload": {
    "task_id": "f1e2d3c4-...",
    "source_beacon_id": "a1b2c3d4-...",
    "source_machine_id": "machine-001",
    "target_ip": "10.10.10.50",
    "method": "psexec",
    "status": "completed"
  }
}

shell_output¶

Real-time output from an interactive shell session (routes to the correct xterm.js terminal tab).

{
  "seq": 7,
  "type": "shell_output",
  "payload": {
    "beacon_id": "a1b2c3d4-...",
    "output": "C:\\Users\\jsmith> ",
    "is_error": false,
    "timestamp": "2026-02-19T10:01:00Z"
  }
}

file_transfer_progress¶

Progress update for an ongoing file upload or download operation.

{
  "seq": 8,
  "type": "file_transfer_progress",
  "payload": {
    "transfer_id": "t1r2a3n4-...",
    "beacon_id": "a1b2c3d4-...",
    "direction": "download",
    "filename": "secrets.docx",
    "progress": 0.65,
    "bytes_done": 6553600,
    "bytes_total": 10085376,
    "status": "in_progress",
    "sha256": ""
  }
}

beacon_highlight_update¶

An operator has changed a beacon's highlight color (visual marker for collaboration).

{
  "seq": 9,
  "type": "beacon_highlight_update",
  "payload": {
    "beacon_id": "a1b2c3d4-...",
    "color": "#ef4444"
  }
}

dialog_request¶

A CNA script is requesting operator input via a dialog prompt (prompt_text, prompt_confirm, prompt_file, dialog_show).

{
  "seq": 10,
  "type": "dialog_request",
  "payload": {
    "dialog_type": "prompt_text",
    "title": "Enter target username",
    "message": "Provide the username for lateral movement:",
    "default_value": "administrator"
  }
}

navigate¶

A CNA script is requesting navigation to a specific page (openBeaconConsole, openPayloadDialog, etc.).

{
  "seq": 11,
  "type": "navigate",
  "payload": {
    "target": "beacon_console",
    "beacon_id": "a1b2c3d4-..."
  }
}

cna_tab¶

A CNA script is creating a custom visualization tab (addTab, showVisualization).

{
  "seq": 12,
  "type": "cna_tab",
  "payload": {
    "tab_id": "custom-viz-1",
    "title": "Attack Graph",
    "content_type": "html",
    "content": "<div>...</div>"
  }
}

siem_alert¶

A SIEM alert forwarded to operator clients for real-time awareness.

{
  "seq": 13,
  "type": "siem_alert",
  "payload": {
    "rule": "Suspicious PowerShell execution",
    "severity": "high",
    "host": "WORKSTATION-01",
    "timestamp": "2026-02-19T10:02:00Z"
  }
}

dropped_messages¶

Sent when the server detects that messages were dropped for this client (see Drop Recovery).

{
  "seq": 50,
  "type": "dropped_messages",
  "payload": {
    "last_sent_seq": 42,
    "current_seq": 50,
    "dropped_count": 8
  }
}

Drop Recovery¶

CockpitHub uses a bounded send buffer (1024 messages per client). When a client's buffer is full (e.g., a slow connection or heavy event volume), the server cannot deliver new events. Instead of silently discarding messages, the server:

1. Sends a dropped_messages event with the gap range (last_sent_seq through current_seq)
2. If even the drop notification cannot be delivered, the client is disconnected

When your client receives a dropped_messages event, the recommended recovery strategy is:

ws.onmessage = (e) => {
  const event = JSON.parse(e.data);

  if (event.type === 'dropped_messages') {
    console.warn(
      `Dropped ${event.payload.dropped_count} messages ` +
      `(seq ${event.payload.last_sent_seq + 1} - ${event.payload.current_seq})`
    );

    // Full data refresh -- re-fetch all mutable state from REST API
    refreshBeacons();
    refreshTasks();
    refreshCredentials();
    return;
  }

  // Normal event processing
  handleEvent(event);
};

Client-to-Server Messages¶

CockpitHub also accepts messages from connected clients. The ReadPump processes incoming JSON messages and routes them by type.

tunnel_local_response¶

Tunnel frames sent back from operator browsers for rportfwd_local (reverse port forward through the operator's network).

{
  "type": "tunnel_local_response",
  "beacon_id": "a1b2c3d4-...",
  "bind_port": 8080,
  "frames": [
    {
      "conn_id": 1,
      "type": 2,
      "data": "<base64>"
    }
  ]
}

RelayHub (Relay WebSocket)¶

RelayHub manages persistent WebSocket connections between the Stentor server and relay agents. Relays are Linux processes (typically running on Kali) that host C2 listeners, process beacon check-ins, and execute payload generation.

Connection¶

Endpoint: GET /ws/relay

Relays authenticate using a shared secret and their registered UUID. Both can be provided via headers (preferred) or query parameters.

wscat -c "wss://stentor.app/ws/relay" \
  -H "X-Relay-ID: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
  -H "X-Relay-Secret: your-shared-secret"

wscat -c "wss://stentor.app/ws/relay?relay_id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&secret=your-shared-secret"

Prerequisites¶

1. Relay must exist in the database -- The server validates the relay UUID against the relays table. If the relay is not registered, the connection returns HTTP 404.
2. Shared secret must match -- The X-Relay-Secret header (or secret query param) must match the server's configured RELAY_SECRET environment variable.

Error Responses¶

INSERT INTO relays (id, name, description, ip_address, status)
VALUES ('aaaaaaaa-...', 'Kali Relay', 'Relay agent', '10.0.0.50', 'online')
ON CONFLICT (id) DO NOTHING;

Message Format¶

All RelayHub messages use the RelayMessage envelope:

{
  "type": "command",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "correlation_id": null,
  "timestamp": "2026-02-19T10:00:00Z",
  "payload": { ... }
}

Message Types¶

command (Backend to Relay)¶

Commands are sent from the server to a relay to initiate actions (start listeners, queue tasks, generate payloads).

{
  "type": "command",
  "id": "cmd-uuid",
  "timestamp": "2026-02-19T10:00:00Z",
  "payload": {
    "command": "start_listener",
    "args": {
      "listener_id": "6ea88162-...",
      "name": "HTTPS Relay",
      "type": "https",
      "bind_address": "0.0.0.0",
      "port": 8443
    }
  }
}

Payload Schema (RelayCommandPayload):

response (Relay to Backend)¶

Responses carry the result of a previously received command. The correlation_id links the response to the original command's id.

{
  "type": "response",
  "id": "resp-uuid",
  "correlation_id": "cmd-uuid",
  "timestamp": "2026-02-19T10:00:01Z",
  "payload": {
    "success": true,
    "error": "",
    "data": { "listener_id": "6ea88162-...", "status": "running" }
  }
}

Payload Schema (RelayResponsePayload):

heartbeat (Bidirectional)¶

Health monitoring messages sent in both directions to maintain the connection and report relay status.

{
  "type": "heartbeat",
  "id": "hb-uuid",
  "timestamp": "2026-02-19T10:00:30Z",
  "payload": {
    "relay_id": "aaaaaaaa-...",
    "status": "idle"
  }
}

Payload Schema (RelayHeartbeatPayload):

event (Relay to Backend)¶

Asynchronous events from the relay to the server (beacon registrations, task completions, phishing activity).

{
  "type": "event",
  "id": "evt-uuid",
  "timestamp": "2026-02-19T10:01:00Z",
  "payload": {
    "event": "beacon_new",
    "data": {
      "beacon_id": "a1b2c3d4-...",
      "hostname": "WORKSTATION-01",
      "username": "jsmith",
      "ip": "10.0.0.20",
      "os": "Windows 10",
      "arch": "x64",
      "pid": 4832
    }
  }
}

Payload Schema (RelayEventPayload):

ack (Relay to Backend)¶

Acknowledgment sent by the relay immediately upon receiving a command, before execution begins. This confirms receipt while the actual result arrives later as a response.

{
  "type": "ack",
  "id": "ack-uuid",
  "timestamp": "2026-02-19T10:00:00Z",
  "payload": {
    "command_id": "cmd-uuid",
    "received": "2026-02-19T10:00:00Z"
  }
}

Payload Schema (RelayAckPayload):

Command Reference¶

Commands sent from the Stentor server to relay agents. Each command is wrapped in a RelayCommandPayload with the command name and arguments.

Listener Management¶

Task Operations¶

Payload Generation¶

Phishing Operations¶

Event Reference¶

Events sent from relay agents to the Stentor server. Each event is wrapped in a RelayEventPayload.

Beacon Lifecycle Events¶

Task Events¶

Listener Lifecycle Events¶

Tunnel Events¶

Guardrail Events¶

Phishing Events¶

CNA Events¶

Synchronous Commands¶

Some operations require waiting for a relay's response before proceeding (e.g., payload generation must return the binary data). The SendCommandSync mechanism implements synchronous request/response over the asynchronous WebSocket channel.

sequenceDiagram
    participant Server as Stentor Server
    participant Relay as Relay Agent

    Server->>Server: Create command with unique ID
    Server->>Server: Register pending request (ID -> response channel)
    Server->>Relay: Send command message
    Relay->>Server: Send ack (command_id)
    Note over Relay: Execute command...
    Relay->>Server: Send response (correlation_id = command ID)
    Server->>Server: Match correlation_id to pending request
    Server->>Server: Deliver response via channel
    Note over Server: Returns data to caller

Timeout handling: If the relay does not respond within the specified timeout (typically 30-60 seconds for payload generation), the request returns an ErrRelayTimeout error. The pending request is cleaned up regardless of outcome.

Correlation matching: The relay includes the original command's id as the correlation_id in its response. The server's handleMessage function checks incoming responses against the pendingRequests map -- if a match is found, the response is delivered to the waiting goroutine and the pending entry is removed.

Connection Lifecycle¶

CockpitHub Lifecycle¶

sequenceDiagram
    participant Client as Operator Browser
    participant API as REST API
    participant Hub as CockpitHub

    Client->>API: POST /v1/auth/login
    API-->>Client: access_token

    Client->>API: POST /v1/auth/ws-ticket
    Note over Client: Authorization: Bearer <token>
    API-->>Client: { ticket: "a3f2..." }

    Client->>Hub: GET /v1/cockpit/ws?ticket=a3f2...
    Hub->>Hub: Validate ticket (single-use, 30s TTL)
    Hub-->>Client: 101 Switching Protocols

    Hub->>Hub: Register client, fire event_join CNA event

    loop Real-time Events
        Hub->>Client: SequencedEvent { seq, type, payload }
    end

    Hub->>Client: Ping (every 54s)
    Client->>Hub: Pong (must respond within 60s)

    alt Client Send Buffer Full
        Hub->>Client: dropped_messages event
        Note over Client: Re-fetch all data from REST API
    end

    alt Disconnection
        Hub->>Hub: Unregister client, fire event_quit CNA event
        Hub->>Hub: Clean up operator tunnel forwards
    end

Reconnection strategy: When the WebSocket connection drops, clients should:

1. Wait briefly (exponential backoff with jitter: initial 1s, max 30s)
2. Request a new ticket via POST /v1/auth/ws-ticket
3. Reconnect with the new ticket
4. Compare the last received seq with the server's current sequence
5. If there is a gap, perform a full data refresh

RelayHub Lifecycle¶

sequenceDiagram
    participant DB as PostgreSQL
    participant Relay as Relay Agent
    participant Hub as RelayHub

    Note over DB: Relay must be registered in relays table

    Relay->>Hub: GET /ws/relay
    Note over Relay: X-Relay-ID + X-Relay-Secret headers
    Hub->>Hub: Validate secret
    Hub->>DB: GetByID(relay_uuid)
    DB-->>Hub: Relay record (or 404)
    Hub-->>Relay: 101 Switching Protocols

    Hub->>DB: UpdateStatus(relay_id, "connected")
    Hub->>Hub: Register client (replaces existing if same ID)

    loop Heartbeat Loop
        Relay->>Hub: heartbeat { relay_id, status: "idle" }
    end

    loop Commands & Events
        Hub->>Relay: command { command: "start_listener", args: {...} }
        Relay->>Hub: ack { command_id: "..." }
        Relay->>Hub: response { correlation_id: "...", success: true }
        Relay->>Hub: event { event: "beacon_new", data: {...} }
    end

    alt Disconnection
        Hub->>Hub: Unregister client
        Hub->>DB: UpdateStatus(relay_id, "disconnected")
    end

Relay reconnection: If the relay process restarts or the WebSocket connection drops:

1. The relay attempts to reconnect with the same UUID and secret
2. If a client with the same ID is already registered, the old connection is replaced
3. The relay status is updated to "connected" in the database
4. Active listeners must be re-started after reconnection (state is not preserved)