Skip to content

Security: NextTokens/waybroker

Security

docs/SECURITY.md

waybroker security model

waybroker's job is to make LLM access from a machine governed: every request attributed to a process, gated by operator policy, metered against budgets, and recorded in a log that cannot be silently edited. This document says exactly what that means — and what it does not.

Trust model

  • The daemon is trusted. It holds the sealed keyring and writes the audit chain. Compromise of the daemon (or of the user/host it runs as) is compromise of everything it governs.
  • Clients are untrusted. Identity comes from the OS, not from anything the client sends: SO_PEERCRED (pid/uid/gid) plus /proc/<pid>/exe on Linux; GetNamedPipeClientProcessId plus QueryFullProcessImageName and token-SID comparison on Windows.
  • Providers are semi-trusted. They receive prompt content (that is the point), but only at hosts the operator allow-listed, and never see the keyring beyond their own key.

Enforcement points

  1. Policy gate (policy.conf + policy.d/): default-deny. First matching rule (by exe glob + uid) decides: allow/deny, permitted providers, per-request token clamp, per-UTC-day token budget. No match → default action. Every deny is audited.
  2. Egress gate (per provider config): allowed_hosts is default-deny — a provider whose config lists no hosts cannot open a single connection. Redirect following is disabled in both HTTP layers so a 3xx cannot re-aim traffic at an unvetted host. URLs with userinfo (user@host) are rejected outright.
  3. Key custody: API keys enter through an admin verb, are sealed immediately (AES-256-GCM under a 0600 master key file on POSIX; DPAPI per-user on Windows), are unsealed only inside the dispatch path, and are zeroed after each use. No verb returns a key value. Client processes never see provider credentials — that is the core product guarantee.
  4. Audit chain (audit.log): one JSON line per event — invokes, provider errors, policy/quota denials, every admin verb (allowed or denied), daemon start/stop. Each record embeds the SHA-256 of its predecessor; waybroker audit verify re-walks the chain offline and reports the first edited, deleted, or reordered record. Records carry prompt/response SHA-256 fingerprints, never content — the log proves what happened without becoming a second copy of your data. Appends are fsync'd.

Known limits — read these before relying on it

  • The audit chain is tamper-EVIDENT, not tamper-PROOF. An attacker with write access to the state dir can truncate the whole file or rewrite the chain from any point if they also recompute every subsequent hash. Verification detects casual and partial edits, and any edit made without rewriting the tail. For stronger guarantees, ship audit.log to an append-only remote store; a periodic external anchor of the latest hash makes rewrites detectable too. (In the operating system this design comes from, the chain is kernel-held and processes cannot reach it at all; a userland port cannot reproduce that property.)
  • Executable-path attribution has a pid-reuse race and identifies which binary connected, not what logic is running (an allowed interpreter runs arbitrary scripts). Scope exe globs tightly and prefer uid pinning as the coarse boundary.
  • POSIX master key: master.key (0600) protects keys at rest against other users, not against root or the daemon's own user. On Windows, DPAPI blobs open for any process of the same user.
  • The socket is a boundary too. System-wide installs create the socket root-owned 0600 — grant access deliberately (group, ACL) and let policy do per-process gating behind it.
  • Prompt content leaves the machine to whichever provider policy allows. waybroker governs and records that flow; it does not inspect or redact it (a redaction stage is future work).
  • No external security audit has been performed. The attack surfaces to review first: the frame parser, the JSON extractor, the INI parser, and the peer-credential paths.

Reporting

Report vulnerabilities privately to the maintainer (see README) rather than via public issues.

There aren't any published security advisories