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, bytes in, bytes out)
  • 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.key

grpc 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.