Ordered; the first item is the current/next task. One item per session — capture unrelated ideas at the end, don't chase them mid-session. Items below continue the assurance ladder defined in docs/formalisation-roadmap.md; each names its rung.
Issue #68. The checks in
docs/testing.md (real daemon, real TUI prompt, keypress by
hand) and the tests/manual/ui/*.json display checks are verified only by eye;
the integration suite stops at ScriptedPrompter. A proof of concept drove the
real daemon under script(1) with keys fed through a FIFO, and a fake sudo on
PATH covered the privileged path. Plan:
Plan, revised after a code review (full notes in the issue comment):
- PR 1 — harness + 3 scenarios.
tests/common/pty.rs, hand-rolled onlibc(no new dependency):openpty, thensetsid+TIOCSCTTYinpre_execaroundCARGO_BIN_EXE_sudo-proxy. The pty is the controlling terminal only; stdin and stdout are null and stderr goes to a log file. Helpers:expect,answer(waits for raw mode, then types),shim_log.- Key race: before sending a key, poll
tcgetattr(master)untilICANONis cleared. SeeingExecute?is not enough:TCSAFLUSHatsrc/tui.rs:1106runs after the question is flushed and discards early input. - Environment:
env_clear()+ allowlist. NoDISPLAY/WAYLAND_DISPLAY; a tempXDG_CONFIG_HOME/HOME;NO_COLOR/bell/blink set per scenario. - Fake
sudo: a committed script intests/shims/, first onPATH. Assert on the argv after--and on the-uprefix. - Scenarios: approve, deny, privileged approve.
- Cleanup:
Dropsends SIGTERM and waits. - Gating:
#![cfg(target_os = "linux")]. - Docs: rewrite the last paragraph of
docs/testing.md.
- Key race: before sending a key, poll
- PR 2 — goldens for
tests/manual/ui/*.json(NO_COLORand colour, bell/blink off, escapes visible,\r\nnormalised,Time:/Resolves:masked,UPDATE_GOLDEN=1), plus a check thatrun-as rootis bright red. - PR 3 — remaining scenarios:
a, with and without--unattended-eligible;--no-shell, asserted by ordering rather than "no prompt seen";- timeout:
#[ignore]it, or add a shorten-only, capped prompt-timeout env. The env would be a knob on the human gate, so decide it explicitly.
- Extras: stray input before the prompt is flushed; termios is restored; two prompts on one tty are shown one at a time; the foreground handoff doesn't hang; SIGTERM removes the socket; control/bidi characters never reach the tty.
Dropped: the pkexec shim. The pkexec path clears the env and sets a fixed
PATH, so a shim is never found, and that path has no TUI. Separate: a CI job
with real sudo -n. Stays manual: how colours, bell and blink look in a real
terminal, real sudo passwords, the pkexec dialog, the remote SSH tunnel.
The next work, pulled to the front. These surfaced while building and live-testing the structured-plan prompt rework this session; detailed write-ups remain in the sections further down, linked here. Tackle in roughly this order:
- Close the
exec sh -cloophole (highest payoff).validate_treeshould treat anExec/pipe-stage whoseargv[0]resolves to a shell (sh/bash/dash/zsh/…) with-cexactly like aShellnode — same opaque flag at the prompt, same strict-mode fate. Today a plainexec sh -c '…'smuggles a shell onto the path without the opaque marker, quietly defeating the "makeShellavoidable" goal. See "Make the shell escape hatch avoidable" below. - Strict policy mode that rejects the shell hatch.
protocol.rsalready promises "a strict policy mode rejects it," but none exists. Add a per-daemonpolicy.no_shell/--no-shellthat rejects anyShellnode (and, with #1, anyexec sh -c) before prompting. Same section. - Shell-tail ops:
detachand read-file. Adetachop (backgrounding + structured pid, replacingnohup … & echo $!— campaign observation O1; the only gap that still forced thesystemhatch live) and a read-file op (replacing$(cat /proc/…)). See "Structured plan: remaining shell-tail gaps" and lever 3 of the shell-hatch section. sudo-request --printexit code (O2). With--printthe client exits0even on an errorResponse(it prints the result); without--printan error exits1. Make--printpropagate a non-zero exit onStatus::Error/Denied/Timeout(or document the discrepancy). Found during the test campaign; had no backlog home until now.- Treat whole-command
privilegedas sugar for an ambientrun-as root. It already is semantically (compile_planseeds ambient root from the flag, ≡ arun-as rootwrapping the whole plan). Steer callers toward per-stagerun-asso pipes stay unprivileged and dodge the sudo-credential-in-pipe caveat (the blunt flag escalates every leaf, including pipe stages → the caveat bites). Consider deprecating the flag once the plan path is primary; keep it meanwhile for flat-pipelinewire-compat. (Raised in discussion this session; not previously recorded.) - Soften the sudo-credential-in-pipe caveat + partial-
runretry hazard. See "Partial-runretry hazard and the sudo-credential-in-pipe caveat" for the mitigation menu (auth-probe before stateful stages, surface the partial boundary so callers resume rather than replay, advisory non-idempotency flag). envhides the real program fromResolves:. A step written asenv VAR=… opam exec … dune …resolves onlyenv;opam/dune, the programs that actually run, never appear in the resolve block. It arises becausesetenvonly accepts allowlisted names (TSAN_OPTIONS,OCAMLRUNPARAM, … are rejected), so callers fall back toenv(corpus cases 06, 22). Fix options: resolve the program afterenv'sVAR=…/ option arguments (like a wrapper-aware resolver, and flag an unresolvable one), or allow non-allowlisted names insetenvfor non-root subtrees so theenvwrapper is unnecessary. Found live-testing case 22.--pkexecwith a multi-stepprivileged: trueplan. Each escalated step raises its own pkexec dialog, which shows only that step (and, since steps run aspkexec env -C <dir> -- argv, names/usr/bin/envas the program). With thepkexec-cachepolkit rule, steps after the first run with no dialog at all. Options: reject multi-leaf plans in--pkexecmode, or show the whole plan in the TUI and use pkexec only to authenticate. Plans that escalate only viarun-asalready take the TUI prompt (PR #59 review fix). Found in the PR #59 review.
The replay-protection residual surfaced during PR #35 by the Extended Rung 4
ReplayWindow TLA+ model (its NoFutureReplay invariant exhibits a concrete
trace). parse_age (server.rs:146) clamps a future-dated timestamp to age 0
with no upper bound, so a request dated beyond REPLAY_RETENTION into the
future passes the freshness gate indefinitely while its id ages out of
SeenIds — making it replayable every retention window regardless of how large
retention is. The 60s↔120s window relationship does not help here. Low severity
(needs the request onto the channel — SSH pinning guards that — and privileged
commands still gate the first run on a keypress), but for auto-approved
unprivileged commands it is a real repeatable replay.
The fix. In check_freshness / parse_age, reject timestamps more than a
small clock-skew allowance into the future instead of clamping to age 0.
Re-climb the ladder to the same level (Rung 4). The fix touches code that several already-discharged rungs cover, so re-establish each so assurance returns to where PR #35 left it — do not leave the proofs trailing the code:
- Rung 1 (CI): the existing gate should stay green; add a regression test for the rejected far-future timestamp.
- Rung 2 (property): extend the freshness property in
src/prop.rsso it asserts a sufficiently-future timestamp is rejected, not silently fresh. - Rung 3 (Kani): re-drive the
ymd_hms_to_epochmonotonicity/totality proofs against the new gate (the bounded-future rejection must stay panic-free over the full domain). - Rung 4 (TLA+): flip the
ReplayWindowmodel'sNoFutureReplayfrom a surfaced-gap witness to a held invariant, and re-check the sibling models are unaffected.
Done = the code rejects far-future timestamps and every rung above is re-discharged against the fixed code (negative controls re-run where they exist).
Creusot / Verus / Prusti contracts on validate_request, the dispatch path, and
the env-allowlist enforcement, proved against the Rung 2 properties. Scope to the
smallest trusted core, not the whole tree.
Invariant G4.5: the prompt's Steps: block and Command: line parse, as shell,
to the same tree, and that tree means what the executor runs. Today the evidence
is Rung 2 only (golden layouts, a bash parse-tree comparison, a differential run
against sh). The rung-by-rung plan is in
docs/formalisation-roadmap.md;
none of it was tracked here until now:
- Rung 2 gap. The differential run covers only privilege-free, side-effect-free
plans. Extend it to
run-as(for example,run-asthe current user so no escalation is needed) and to file redirections andwith-stdin-from(inside a temp dir). - Failed-
cddivergence (G4.5 residual,docs/assurance-case.md). When achdirfails, the executor aborts the whole plan. A shell running the pastedCommand:line skips only that scope's body and goes on with any;-sequenced steps after it. Either make the two agree (render so that a failedcdstops everything, or make the executor fail only the scope) or accept it and say why in the assurance case. - Rung 1. A review-checklist item: changes to
src/tui.rsrendering, the plan ops, or the executor's composition semantics must keep the G4.5 properties green. Add a lint or Semgrep rule against rendering aPlananywhere but through the shared layout. - Rung 3. A Kani harness over bounded plans proving the layout is total and
that rendering then re-parsing (with an in-crate parser for the shell subset
the renderer emits) gives back the plan's structure. This removes
bashas the oracle for the syntax half. - Rung 5. A deductive proof (Creusot / Verus) that the renderer and the executor both refine one shell-semantics model of that subset. Extends the Rung 5 item above, which covers only validation, dispatch and the env allowlist.
The remaining Rung 0 / paper step: a Common Criteria Security Target (TOE,
threats, assumptions, SFRs, SARs) consolidating security.md / security-audit.md
/ threat-model.md / assurance-case.md into the standard ST structure.
tests/concurrency.rs:burst_connections_above_cap_get_busy_response fails ~2/3
locally — the setup assertion ("in_flight reached ≥4") is timing-flaky, not the
security assertion. Stabilize so the in-flight cap stays covered by CI.
When confirm_unprivileged=false, display_banner is printed under a try_lock
and may be dropped under TTY contention, so silent execution can be invisible.
Make the banner reliable and state the residual risk plainly at the a-key
prompt and in the README.
deny.toml and the cargo audit step ignore RUSTSEC-2026-0189 (DNS rebinding
in rmcp's Streamable HTTP server transport) because sudo-proxy enables only
rmcp's transport-io feature and serves over stdio, so the vulnerable code is
not compiled in. If an HTTP/streamable-http transport is ever added, drop the
ignore and require a patched rmcp instead. Captured follow-up, not active work.
deny.toml and the cargo audit step ignore RUSTSEC-2026-0543 (chrono
unmaintained). rmcp depends on chrono unconditionally, using it for model
timestamps and for timeout-error formatting, and it enables schemars'
chrono04 feature. Upstream tracks the fix in
modelcontextprotocol/rust-sdk#1469:
either a move to jiff/time or an optional chrono feature. When an rmcp
release lands either change:
- upgrade
rmcp, and turn off itschronofeature if it is made optional; - check that
cargo tree -i chrono --all-featurescomes back empty; - remove the ignore from both
deny.tomland.github/workflows/ci.yml.
Patching rmcp locally, or writing the MCP layer ourselves, costs more than it
gains while the advisory is only an unmaintained notice. Reconsider if a
chrono vulnerability advisory is published. Rung: supply chain. Captured
follow-up, not active work.
Optional discoverability step, added after the plugin packaging landed (PR #53).
The decentralized flow (/plugin marketplace add tarides/sudo-proxy →
/plugin install sudo-proxy@tarides) already works with no registration; this
would additionally list sudo-proxy in Anthropic's curated community marketplace.
Submit via the in-app form (claude.ai admin directory, or the Console plugin
submission page). Expect extra security scrutiny because the plugin executes
sudo — link the threat model, security audit, and the "no auto-approve"
non-features from the plugin README so reviewers find them. Captured follow-up,
not active work.
Today there is no durable record of requests. The daemon writes audit lines
only to its own stderr — the per-command line ([id] [priv] [client] <pipeline>,
server.rs:640) solely under --verbose, and the unconditional [unattended]
line (server.rs:687) only while a session a-grant is active. Both land in the
terminal window's scrollback and vanish with it; nothing is written to disk, the
systemd journal, or any audit facility. For a tool whose whole purpose is gating
privileged execution, the absence of a tamper-evident, admin-controlled trail is
a gap.
The fix. Emit a structured audit record for every request — approved, denied,
timed out, unattended — to the system logger (syslog/journald via libc
openlog/syslog, or the systemd journal API under a feature flag), not a
self-managed file. System-level is the point: records then inherit the host's
journald rotation, retention, access control, and optional forwarding/sealing,
and survive the terminal window closing. Record at least: request id, host,
privileged flag, client version, the pipeline (argv), decision, and the
decision path (prompted / unattended-grant / pkexec). Keep stderr lines as-is
for live visibility. Decide the default (log-to-syslog on by default vs opt-in
via a flag) and document the privacy/retention implications in the README.
Captured follow-up, not active work.
The plan model shipped in PR #59 (see the changelog). These shell features still
have no structured op, so they still need the system escape hatch:
- Backgrounding / detach with pid return (
nohup … & echo $!, campaign observation O1). Plan steps run synchronously. Add launch-and-detach that returns the pid as a structured field, not a shell$!. - Runtime substitution (
$(cat /proc/…),$!,$?). Promote the common cases to first-class ops (a read-file op for$(cat …); the launcher already knows the background pid) and leave the rest to the explicitsystemhatch.
Reject unresolvable steps. With every step resolved and rendered, an "opaque
blob" is no longer a string pattern to deny: it is any step the daemon cannot
resolve. Such steps are already flagged at the prompt; a policy mode should
reject them, making no-opaque-blob a special case enforced in the daemon for
every client rather than by a regex in one user's hook. See the strict-mode lever
in the next section.
The design goal. The Plan type's raison d'être is to make its Shell
constructor (the opaque escape hatch, formerly System) unnecessary: every
structured op exists so a given shell feature need not be expressed by shelling
out. The real invariant is no shell on the privileged path; Shell is the
one node that breaks displayed-equals-executed — it resolves only the shell
binary, so its inner commands are invisible at the prompt. The goal is therefore
not to delete Shell (the shell tail — runtime $(…), $!, globbing,
word-splitting, profile functions — is open-ended) but to shrink-and-flag:
drive real usage into structured ops, and keep every remaining shell use loud,
countable, and policy-rejectable. Read each Shell node as measurable debt — a
prompt to ask "what op would have avoided this?" That loop already produced alt
(for ||) and seq (for ;). See
docs/architecture.md ("Security model vs. agent
harnesses") for the framing.
Remaining levers (rough payoff order):
- Close the
exec sh -cloophole (highest payoff). The goal is quietly defeated today not byShellbut by its dishonest sibling: a plainExecleaf (or pipe stage)["sh","-c","<script>"]puts a full shell on the path without the opaque flag — it renders as a tameexecstage with/usr/bin/shresolved while a whole script hides in one argv element. (Seen in the live campaign: C1/C2 usedsh -c "…;…"leaves to sequence what the type couldn't yet express.) Fix: havevalidate_treerecognize anExec/pipe-stage whoseargv[0]is a shell (sh/bash/dash/zsh/…) with a-cand treat it exactly like aShellnode — same opaque flag at the prompt, same strict-mode fate. Without this, every other lever is bypassable. - Implement the documented strict policy mode.
protocol.rsalready promises "a strict policy mode rejects it," but no such mode exists. Add a per-daemon policy (hosts.jsonpolicy.no_shelland/or a--no-shellflag) that rejects anyShellnode — and, with lever 1, anyexec sh -c— before prompting: "structured or nothing" for operators who want it. Folds into the reject-unresolvable-stages idea in the remaining-gaps section above. - Catalogue the shell tail as first-class op proposals. The two most common
forces in the log.1 trail that still require the hatch: a
detachop (backgrounding + a structured pid return, replacingnohup … & echo $!) and a read-file op (replacing$(cat /proc/…)). See "Structured plan: remaining shell-tail gaps" above. Each retired force converts an opaque stage into reviewable ones.
Captured follow-up, not active work.
Why. no-opaque-blob is currently a Claude Code PreToolUse hook (matcher
mcp__sudo-proxy__execute) living in one user's ~/.claude/hooks/. It blocks
echo … | base64 -d | bash-style payloads an approver cannot review. But it sits
on the untrusted end of the airlock: it protects only that one client, only
that one machine, and only the MCP path — another MCP client, a fresh install
without the hook, or a direct socket caller all bypass it. sudo-proxy's trusted
components are the daemon and the human at the TTY, so a reviewability guarantee
can only be enforced daemon-side; a client hook can't provide it.
Interim fix (small, lands before the full structured-plan work). Have the
daemon detect the obvious opaque shape in an incoming argv/pipeline — a
decode step (base64 -d, xxd -r, openssl enc -d, …) piped into an
interpreter (bash/sh/python/perl/eval) — and either hard-reject it or
mark it loudly at the approval prompt. This holds the floor for all clients and
the direct-socket path, not just this user's hook. Keep the hook as an optional
outer layer: it gives the agent a faster pre-round-trip rejection and is the
natural home for stricter-than-baseline, site-specific policy.
Residual / handoff. This interim check is still a denylist — a hostile client can obfuscate around any pattern. It is a stopgap, not the answer: the sound, allowlist-shaped enforcement is reject-unresolvable-stages in the structured plan model (now landed; see "Structured plan: remaining shell-tail gaps"), which this item should be folded into. The daemon failing open must never be the difference between safe and unsafe; the hook failing open (misconfig, different client) likewise must not — the daemon is the backstop. Captured follow-up, not active work.
Surfaced while reviewing the structured-plan executor (the plan model above, first increment landed). Two interacting behaviours deserve a safer story than "the caller must know."
The retry hazard. A run (≈ &&) runs its steps in order and stops at the
first non-accepted failure (executor.rs, run_seq → SeqNode::Run). When a later
step fails, the earlier steps' side effects are already committed. The
response marks which stages ran (per-stage exit codes; a skipped stage carries
the -1 not-run sentinel), but nothing stops a caller from resubmitting the
same plan — which replays the already-committed early steps. For
non-idempotent effects (mkdir, append-redirects, counters, git commit) that
double-applies or errors on the second pass. This is the classic
partial-failure/retry footgun of any set -e script; the plan model makes the
partial state visible but does not prevent the replay.
The sudo-credential compounding. The most likely "later step fails" cause is
a privileged stage with no cached sudo credential. A single privileged stage
runs with setpgid + the foreground-tty guard and can prompt; a privileged
stage inside a pipe runs with setsid (detached, no controlling tty) and
cannot prompt — it relies on a cached credential. Whether a leading
sudo true-style prime carries into a setsid pipe child depends on the host's
sudoers timestamp_type (global → yes; the common tty default → likely
not). So a pipe whose privileged stage is neither NOPASSWD nor already-cached
fails fast with "no tty present," and credential-priming is not a reliable fix
inside a pipe.
Mitigations available today (caller-side): order privileged stages first;
make early stages idempotent (mkdir -p, truncate not append); rely on
NOPASSWD / cached creds; prefer a single privileged stage over sudo-inside-a-
pipe; and use the per-stage exit-code array to resubmit only the not-run stages
rather than replaying the whole plan.
Potential improvements to weigh (none a full fix — idempotency stays the
caller's responsibility): (1) surface the partial-execution boundary
prominently in the response/prompt so a caller resumes rather than replays;
(2) an optional executor-inserted auth-probe for privileged plans that fails
fast before any stateful stage, documenting the timestamp_type caveat;
(3) advisory flagging of obviously-non-idempotent leading stages. Captured
follow-up, not active work.
An option to weigh, not a commitment. The first plan increment (PR #59) keeps the
daemon running as the user and escalates each step through sudo [-u user] -- argv (or pkexec). The other design runs the daemon as root and switches
user for each step itself (setuid/setgid/initgroups before exec), with no
sudo binary involved.
- Gains: no sudo-credential-in-pipe caveat (pipe stages need no cached
credential); no
sudo/pkexecargv or env handling in the trusted path; the run-as user for each step is set directly by the executor. - Costs: the daemon becomes a root process, so the socket and client
authentication and the whole daemon join the privileged TCB. The deployment
changes (system service instead of a user process) and so does the threat
model (
threat-model.md, boundaries B1–B6). The step-by-step approval prompt becomes the only gate, with nosudopassword behind it.
This needs its own gate: an updated threat model and assurance case before any
code. (The original structured-plan design, now in the changelog, said "setuid
to a run-as user". That describes this option, not what shipped.)
Long-horizon: prove the daemon's logic refines an abstract approval spec, with
trust assumptions (/dev/tty, sudo, kernel, SSH) stated explicitly as the
boundary of the proof. Value even unrealised: forces a complete enumeration of
what is trusted-by-assumption.