diff --git a/docs/observability.md b/docs/observability.md index 13bf6864..5a3fbea0 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -31,6 +31,27 @@ same host as the agents and restarts on failure, and telemetry is not the control plane — degraded telemetry is not degraded operation — but the export no longer survives independently of anything host-side. +### what the agent→collector hop is and isn't + +**It has no application-level auth.** The receiver takes any OTLP that reaches +it; what bounds who can reach it is the firewall — `exposeHostPorts` opens the +port on the bridge interface only. So "unauthenticated to a bridge address" +means *reachable from an agent container*, not *presents a credential*. + +The consequence, stated because it is a choice rather than an oversight: **any +agent can push arbitrary OTLP, and the collector forwards it upstream under the +operator's credential.** It cannot tell a container's genuine Claude Code stats +from anything else shaped like OTLP arriving on that port — including data +smuggled out in resource attributes on an otherwise-legitimate export. + +That is a **different risk from the one the collector fixes**, and strictly +smaller than what preceded it: before, every agent held the upstream credential +itself, so it could do all of the above *and* use the token anywhere else. The +collector removes the token and keeps the pipe. Agents are inside the trust +boundary (`docs/security.md`: capability = accepted risk), so an agent being +able to *send* is an accepted extension of that boundary — but it is not +closed by this design, and nothing here should be read as closing it. + ## Options reference ### `services.hyperhive.otel.enable` — bool, default `false`