|
| 1 | +# LiveKit protocol threat model |
| 2 | + |
| 3 | +`github.com/livekit/protocol` is a Go library shared by the LiveKit server, the |
| 4 | +Go server SDK, and LiveKit's media services. It holds the protobuf definitions |
| 5 | +and generated code, plus the Go helpers that interpret untrusted input on their |
| 6 | +behalf: access-token and webhook verification, SDP and RTP helpers, data-track |
| 7 | +packet parsing, and decode budgets for protobuf and JSON. |
| 8 | + |
| 9 | +## Scope and trust boundaries |
| 10 | + |
| 11 | +Audit the hand-written Go on `main`. Prioritise: |
| 12 | + |
| 13 | +- `auth/`: access-token minting, parsing, and verification, and grant |
| 14 | + semantics (`ClaimGrants`, `VideoGrant`, `SIPGrant`, agent and inference |
| 15 | + grants). |
| 16 | +- `webhook/`: `Receive` / `ReceiveWebhookEvent` (signature and body-hash |
| 17 | + verification) and the outbound notifier. |
| 18 | +- `utils/jwtutil/`, `utils/decodebudget/`: JWT helpers and resource limits for |
| 19 | + decoding untrusted protobuf and JSON. |
| 20 | +- `datatrack/`, `sdp/`, `utils/rtputil/`, `codecs/`: parsers for packets and |
| 21 | + SDP that arrive from clients. |
| 22 | +- `sip/`: SIP token building, phone-number normalisation, and trunk and |
| 23 | + dispatch-rule matching. |
| 24 | +- `utils/` helpers that redact secrets or handle IDs. |
| 25 | + |
| 26 | +Out of scope: generated code (`*.pb.go`, `*.twirp.go`, `*.psrpc.go`), the |
| 27 | +`.proto` files themselves, the JS packages under `packages/`, and build tooling |
| 28 | +under `magefile.go` and `tools/`. Report a bug in a generated file only when |
| 29 | +the generator template or the `.proto` definition causes it. |
| 30 | + |
| 31 | +Untrusted input: access tokens and webhook requests from the network, SDP, |
| 32 | +RTP/RTCP, and data-track packets from clients, and any protobuf or JSON a |
| 33 | +client can send that these packages decode. |
| 34 | + |
| 35 | +Trusted: API secrets, the caller's configuration, and values the embedding |
| 36 | +application passes in after it has authenticated them. |
| 37 | + |
| 38 | +LiveKit server (`livekit/livekit`) is enrolled separately. Report bugs in how |
| 39 | +the server uses these packages there; report bugs in the packages here. |
| 40 | + |
| 41 | +## Security properties |
| 42 | + |
| 43 | +- **Token verification:** a token must verify only with its issuer's secret, |
| 44 | + only with HS256, and only inside its validity window. Parsing an unverified |
| 45 | + token must never be treated as verification. Grants must deserialize exactly |
| 46 | + as signed; a token must not gain a grant, room, or identity it was not issued. |
| 47 | +- **Webhook verification:** an event must be accepted only when its token |
| 48 | + verifies and the body's SHA-256 matches the signed hash. |
| 49 | +- **Parsing:** SDP, RTP extensions, data-track packets, and decode-budget |
| 50 | + inputs must not panic, loop, or allocate without bound on malformed input. |
| 51 | +- **Decode budgets:** the budget must bound the memory and CPU of decoding the |
| 52 | + message it is applied to. |
| 53 | +- **Secrets:** API secrets must not appear in logs, errors, or redacted output. |
| 54 | + |
| 55 | +## Severity guidance |
| 56 | + |
| 57 | +- **Critical:** forging a token or webhook that verifies without the secret. |
| 58 | +- **High:** accepting an expired, wrong-algorithm, or wrong-issuer token; |
| 59 | + grant escalation through parsing; a panic reachable from untrusted network |
| 60 | + input that crashes the embedding process. |
| 61 | +- **Medium:** unbounded resource use from one untrusted input; a decode budget |
| 62 | + that undercounts by a large factor; secret leakage into logs. |
| 63 | +- **Low / not a finding:** misuse that needs the API secret or caller |
| 64 | + configuration; issues only in generated code; outbound webhook delivery |
| 65 | + behaviour (retries, ordering) without a security impact. |
| 66 | + |
| 67 | +## Testing |
| 68 | + |
| 69 | +The checkout is at `/src`. Go dependencies are cached. `GOPROXY=off` and |
| 70 | +`GOSUMDB=off` prevent downloads. No external services are needed. |
| 71 | + |
| 72 | +```sh |
| 73 | +cd /src |
| 74 | +go test -count=1 ./... |
| 75 | +go test -race -count=1 ./auth/... ./webhook/... ./datatrack/... ./sdp/... |
| 76 | +go test -run '^$' -fuzz FuzzPacketUnmarshal -fuzztime 60s ./datatrack |
| 77 | +go test -run '^$' -fuzz FuzzSDPFragmentUnmarshal -fuzztime 60s ./sdp |
| 78 | +``` |
| 79 | + |
| 80 | +## Reports |
| 81 | + |
| 82 | +State the attacker's required access (none, any valid token, or a specific |
| 83 | +grant), the entry point, and the demonstrated impact. Provide a minimal |
| 84 | +reproducer, preferably a Go test in the affected package. |
0 commit comments