Skip to content

ADR-0077: The runner alias is admin-only on the status API ​

Context and Problem Statement ​

A run records which backend served it (RunnerStateResponse.runner). The runner's alias is an operator-chosen name (local, gpu-box, k8s-prod-eu, an external domain) that can double as infrastructure topology: an ssh host, a Kubernetes pool, a tenant or environment marker (CWE-200). The status APIs are readable by any principal who can see the run, so emitting the raw alias to every such caller disclosed operator-chosen naming to read-granted non-admins. The generic backend kind (local / ssh / kubernetes / external / unknown) carries no operator naming.

Decision Drivers ​

  • §12: principals are a trust boundary; an information disclosure across one is a defect whatever its severity.
  • A read-granted non-admin legitimately needs to know what kind of backend served a run (the console's Runner card renders it), but has no need to know which configured runner it was.
  • ADR-0047 rule 3: fail closed; ADR-0047 rule 8: prove the denial path with a test.

Considered Options ​

  • Gate the whole status response on admin — overkill: non-admins need the run fields.
  • Withhold the alias in the serializer unconditionally — loses the admin view, which has a legitimate use for it.
  • Pseudonymize or hash the alias — stable pseudonyms still leak equality and correlation, and add a mapping surface for no reader need.
  • Gate by grant instead of role — a READ grant on an agent is exactly what makes the run visible; granting the alias with it re-opens the disclosure.

Decision Outcome ​

Chosen option: "the raw alias is emitted only to an admin (or when authentication is disabled); every other viewer gets the generic backend type instead" — an aliasVisible flag resolved once per request in the route handler (authorizer.isAdmin(principal)), passed down to the serializer, failing closed (aliasVisible = false by default, so a forgotten call site withholds the alias rather than leaking it).

The same classification governs future fields on RunnerStateResponse:

  • alias — operator-named backend metadata → admin-only.
  • type — generic backend kind → emitted to every viewer.
  • pod fields (podName, podPhase, timestamps, startupFailure) — carrier metadata, no operator naming → emitted to every viewer.

GET /api/v1/health applies the same gate with the same per-request admin check: a non-admin gets alias: null (with type) for every configured runner, and runnerAlias: null for each pod in the sweep snapshot. The one exception is the built-in local row, which always carries the alias local: Homer assigns that name, not the operator, so it names no host, tenant or environment.

GET /api/v1/runners stays admin-only (it exists for operators and lists every configured alias), so kind there is the admin-side twin of the status response's type (amended 2026-11-13: a read grant on * reads it with every alias, instance name and alias filter withheld — see the amendment below and ADR-0111).

Consequences ​

  • Good: a non-admin viewer of a run can no longer enumerate runner aliases (ssh hosts, tenant names, pools).
  • Good: the console Runner card degrades to the backend kind with a matching label instead of an empty card.
  • Bad: a non-admin operator debugging a misrouted run cannot tell which of several same-kind runners served it; they ask an admin.
  • Bad: a non-admin inspecting a sweep can no longer see which runner owned a deleted pod; they ask an admin.

Pros and Cons of the Options ​

Pseudonymize or hash the alias ​

  • Good: keeps a per-run stable label non-admins can group by.
  • Bad: equality still correlates runs across views; a low-entropy name space (few runners) makes the raw value guessable.
  • Bad: a mapping layer for a reader need that type already satisfies.

Gate by grant instead of role ​

  • Good: consistent with the process-visibility union rule (ADR-0037).
  • Bad: a READ grant on an agent is what makes the run visible in the first place, so the alias would ship to exactly the non-admins the finding is about.

Amendment (2026-11-13): the server-wide runner read admits a read grant on * ​

GET /api/v1/runners and /api/v1/runners/queue are no longer admin-only: a caller holding a read grant on the literal * pattern reads them with alias, instanceId and name blanked (and a queue group's alias filter null, the value it already carries when unset), while the built-in local row keeps its alias and the generic fields (kind, tags, concurrency, counts, ages) stay. That is this ADR's own classification applied to the server-wide view: operator-chosen naming stays admin-only, the generic kind goes to every reader. GET /api/v1/maintenance admits the same grant; POST stays admin-only, and its denial keeps the bare 404 of ADR-0092. Per-run runner.alias on /status and /status/all is unchanged — still admin-only. The widening, the withheld fields and the rejected alternatives (any read grant, a dedicated grant action, keeping the endpoints closed) are decided in ADR-0111.

More Information ​

Implemented in the same change that added runner.type to the status API. See ADR-0037 (grants model), ADR-0047 (security by design and threat model).

Released under the Apache License 2.0. Documentation for 1.43.0.