gRPC Beacon Transport#
Completed in v0.5.1. Sibling of the WebSocket beacon
transport that speaks gRPC
stream/stream instead of raw WebSocket frames. Useful when the
implant already links grpc for legitimate reasons and wants to blend
with real gRPC traffic on the same host.
Wire contract#
- Service:
infraguard.beacon.v1.BeaconService - RPC:
Session(bidirectional stream,bytesin,bytesout) - Full method path:
/infraguard.beacon.v1.BeaconService/Session
Each request byte string is a JSON object with the same shape the WebSocket transport uses:
{
"method": "POST",
"uri": "/api/v1/telemetry",
"headers": {
"user-agent": "Mozilla/5.0 ...",
"cookie": "__session=..."
},
"body_b64": "<base64>"
}Each response byte string is:
{
"status": 200,
"headers": {"content-type": "application/json"},
"body_b64": "<base64>"
}If a frame is malformed the server responds with the same envelope,
status: 400, and an extra error field describing why.
There is no .proto in the repo. The server registers the servicer
with a pass-through byte serializer via
grpc.stream_stream_rpc_method_handler, so operators do not have to
run grpc_tools.protoc and the wheel dependency footprint stays at
just grpcio.
Enable in config.yaml#
listeners:
- protocol: grpc
bind: 0.0.0.0
port: 9443
options:
# Optional. When both cert and key resolve to readable files, the
# server uses ``add_secure_port``; otherwise it falls back to
# insecure (dev only) with a loud warning in the logs.
cert: /app/certs/tls.crt
key: /app/certs/tls.keygrpc is now a valid entry in listeners[*].protocol. The listener
runs alongside the HTTP listener in the same asyncio loop under the
proxy’s ListenerManager.
Install the dependency#
grpcio is an optional extra:
pip install "infraguard[grpc-listener]"
# or, for everything:
pip install "infraguard[all]"If grpcio is missing at start-up the listener logs a warning and
skips itself rather than crashing the proxy.
Client example#
Any gRPC client that lets you declare a stream/stream RPC with bytes
payloads will work. In Python:
import asyncio, base64, json
import grpc
async def main():
channel = grpc.aio.secure_channel(
"cdn.example.com:9443",
grpc.ssl_channel_credentials(),
)
stub = channel.unary_stream # not used; we invoke the RPC directly
call = channel.stream_stream(
"/infraguard.beacon.v1.BeaconService/Session",
request_serializer=lambda b: b,
response_deserializer=lambda b: b,
)
stream = call()
async def sender():
await stream.write(json.dumps({
"method": "POST",
"uri": "/api/v1/telemetry",
"headers": {"user-agent": "Mozilla/5.0"},
"body_b64": base64.b64encode(b'{"ok":1}').decode(),
}).encode())
await stream.done_writing()
await sender()
async for raw in stream:
print(json.loads(raw))
asyncio.run(main())grpcurl also works with -import-path + a stub .proto (or with
-use-reflection once you enable grpc-reflection on the server).
Why gRPC#
- HTTP/2 stream multiplexing means several beacons can share one TCP connection to the redirector without connection storms.
- Modern apps use gRPC for internal API calls; a redirector that
speaks it blends into
envoy,dapr, and other service-mesh fixtures already on the wire. - Binary framing and HPACK header compression cut telemetry size compared to newline-delimited JSON over WebSocket.
Filter pipeline coverage#
Every frame flows through DomainRouter.handle, so the full IP + bot
- header + profile filter stack runs on gRPC traffic just like HTTP. JA3/JA4 fingerprinting works out of the box because the connection still terminates TLS in Python.
Related#
- WebSocket beacon
- HTTP/3 QUIC listener
- Advanced listeners (DNS, MQTT, TCP tunnel)