WebSocket Beacon Transport#

Added in v0.5. A first-class C2 transport alongside HTTP. Beacons open a long-lived WebSocket to the redirector and exchange newline-delimited JSON frames; the redirector adapts each frame into a Starlette Request, runs the whole filter pipeline over it, and sends the response back as a JSON frame on the same socket.

Long-lived duplex bypasses HTTP-only proxies and blends with real-time app traffic (chat, telemetry, streaming).

Wire format#

Client -> server:

{
  "method": "POST",
  "uri": "/api/v1/telemetry",
  "headers": {
    "user-agent": "Mozilla/5.0 ...",
    "cookie": "__session=..."
  },
  "body_b64": "<base64>"
}

Server -> client:

{
  "status": 200,
  "headers": {"content-type": "application/json"},
  "body_b64": "<base64>"
}

Ping/pong is left to the underlying WebSocket layer; the profile’s sleep and jitter fields do not participate in the wire protocol because the beacon owns its own timing.

Wire it into your config#

The WS transport ships as a listener class. Register it explicitly in Starlette by adding a route (see infraguard/core/app.py for the pattern the HTTP path uses):

from infraguard.listeners.experimental.websocket import BeaconWebSocket

ws = BeaconWebSocket(router)
routes.append(WebSocketRoute("/ws/beacon", ws.handler))

A first-class protocol: websocket listener block in config.yaml is on the roadmap; today the operator adds the route by patching core/app.py.

Why this exists#

  • Deep-packet-inspection proxies that only speak HTTP see one long-lived request and give up.
  • WebSockets are common in modern apps, so a redirector that speaks them blends. Chat, notification, and telemetry endpoints are the right cover.

Related: http3-quic for the QUIC listener that shipped alongside.