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.