Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "sudo-proxy",
"version": "1.2.1",
"version": "1.2.2",
"description": "Run privileged commands locally or over SSH, with a human keypress approving each one",
"author": {
"name": "Tarides"
Expand Down
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "sudo-proxy"
version = "1.2.1"
version = "1.2.2"
edition = "2021"
license = "MIT"
description = "Privileged command execution proxy with human approval via pkexec or sudo"
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,10 @@ key ID `A6F84B53410B83FB`) before installing; a missing or bad signature
aborts the install. Prefer `cargo install` if you'd rather build from
source.

The daemon must run in a terminal window that no other process can type into:
outside tmux/screen, on Wayland. It refuses to start otherwise; see
[Where to run the daemon](docs/usage.md#where-to-run-the-daemon).

Point your MCP client at the server — add to the project's `.mcp.json` or
`~/.claude/claude_desktop_config.json`:

Expand Down
81 changes: 81 additions & 0 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,87 @@ resolved path that `env` receives. Regressions: unit tests in `executor`, and
`resolves_line_names_the_binary_that_runs` in `tests/pty_e2e.rs`, which follows
the issue's repro.

## v1.2.2 — 2026-11-21 (security release)

A patch release on top of v1.2.1 with one security fix and one backported
fix, and nothing else (main's 1.3 work is not included):

- **GHSA-cpmp-67wf-gwmx** (high): the daemon refuses to start in a terminal
that other same-UID processes can type into (tmux/screen, kitty/WezTerm/
Konsole remote control, X11, …), unless started with
`--allow-injectable-tty`. Unprivileged children no longer share its
controlling terminal.
- **#62** (backport of #80): the `Resolves:` line names the binary that
actually runs.

**Upgrade note:** if you start the daemon inside tmux/screen or on X11, it now
refuses with an explanation; move it to a terminal of its own on Wayland, or
pass `--allow-injectable-tty`. With `--host`, upgrade the remote first if you
use the override, since a 1.2.1 remote rejects the forwarded flag.

### Refuse approval terminals other processes can type into (GHSA-cpmp-67wf-gwmx)

The daemon approves a request by reading one key from its terminal, and it
cannot tell a key the human typed from one injected by another process running
as the same user. The usual requester, an AI agent, also has a same-UID shell.
In tmux or screen (`send-keys`, `stuff`), in a terminal with remote control
(kitty, WezTerm, Konsole's D-Bus `sendText`), or in any X11 session
(`xdotool key y`), it could send a privileged request and answer `y` to its own
prompt, or `a` to grant itself the session.

- The daemon now checks its terminal at startup (`src/ttyguard.rs`). If it
finds one of these, it prints each reason and refuses to start. Covered:
multiplexer `TERM` or `$TMUX`/`$STY`/`$ZELLIJ`; kitty, WezTerm, Konsole,
VS Code and Emacs terminals; X11 without Wayland. `--allow-injectable-tty`
starts it anyway, with a warning line in every prompt. There is deliberately
no `hosts.json` equivalent: an agent can write that file and restart the
daemon through MCP. `--pkexec` skips the check, since privileged approval
then happens in polkit's dialog.
- With `--host`, the local terminal is checked before ssh starts, and the
override is forwarded to the remote daemon. A remote older than 1.2.2
rejects the flag and exits, which fails closed.
- Unprivileged children now run in their own session, with no controlling
terminal, so a command (or a background job it leaves) cannot `TIOCSTI`
keystrokes into a later prompt. A kernel that still allows `TIOCSTI` is
reported as a warning.
- `sudo-proxy-mcp` removes the launcher's own terminal variables (`TMUX`,
`KITTY_*`, …) from the window it spawns, so a fresh window is not refused for
the agent's tmux. If the daemon refuses, the window stays open until Enter,
and the `start_server` error explains what to do.
- Docs: threat-model B3 row and attack-tree leaf 3.5 with residuals,
assurance-case assumption A1, security/usage/install/README.

Residuals: an XWayland terminal inside a Wayland session, emulators the check
does not know, and X11 synthetic input into the polkit dialog under `--pkexec`.
The structural fix is to run the agent as a separate Unix user.

### The `Resolves:` line names the binary that actually runs (#62, backport of #80)

The prompt resolved `argv[0]` on the daemon's own PATH, but the executor
spawned the bare name with a cleared environment, so the child searched the
default login PATH (sudo searched its `secure_path`, pkexec's `sh -c` the login
PATH). A daemon started from a dev shell (Nix, virtualenv, `~/.local/bin`)
could show one file and run another, or show a file and then fail with ENOENT.

`executor::resolve_command` now resolves argv[0] on the child's PATH, and a
name containing `/` against the child's working directory `/`. The TUI and GUI
prompts display that result, and every spawn path uses it: directly (keeping
the requested `argv[0]`), as the program after `sudo` / `pkexec`, and in the
multi-stage pkexec `sh -c` string. A name that does not resolve is refused with
`command not found: <name>` instead of being looked up a second time; in a
pipeline, before any stage is spawned. The GUI dialog now also shows
`(not found in PATH)`. As in 1.2.1, the TUI shows the `Resolves:` line for the
first stage and a warning for later stages that do not resolve.

Behaviour change: a privileged command found only on sudo's `secure_path` (e.g.
`/snap/bin`) but not on the default login PATH is now refused, where it
previously ran under a mismatched prompt.

This re-applies the fix from main (#80) to the 1.2 pipeline executor; the code
differs because 1.2 predates structured plans. Regressions: unit tests in
`executor` and `exec_direct_spawns_resolved_path_keeping_argv0` in
`tests/exec.rs`.

## v1.2.1 — 2026-11-18 (security release)

A patch release on top of v1.2.0 with two security fixes and nothing else:
Expand Down
2 changes: 1 addition & 1 deletion docs/assurance-case.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ asserted, evidence not yet produced).
|------|------|-----------|
| **C1** | Context | The Target of Evaluation is the `sudo-proxy` daemon, the `sudo-proxy-mcp` server, and the `--host` SSH-tunnel path. Out of scope: the AI model, the operator's judgement when reading the prompt. |
| **C2** | Context | Adversaries: **A1** prompt-injected MCP caller; **A2** same-UID local process (direct socket); **A3** network MITM / malicious remote. (See [security-audit.md](security-audit.md#threat-model).) |
| **A1** | Assumption | `/dev/tty` is trusted: what the daemon writes is what the human sees, and the keypress read is the human's. |
| **A1** | Assumption | `/dev/tty` is trusted: what the daemon writes is what the human sees, and the keypress read is the human's. The second half is false on a terminal other same-UID processes can type into (GHSA-cpmp-67wf-gwmx). So the daemon refuses the terminals it can recognise as such unless started with `--allow-injectable-tty`, and its unprivileged children have no controlling terminal. Residuals: [threat-model.md](threat-model.md#coverage-and-residuals) 3.5. |
| **A2** | Assumption | `sudo` (and `pkexec`) correctly enforce escalation and `env_reset`; the kernel enforces socket permissions and `SO_PEERCRED`. |
| **A3** | Assumption | The host is effectively single-user *or* the operator accepts that any same-UID process is already inside the trust boundary for non-privileged actions (finding F2). |
| **A4** | Assumption | For the SSH path, remote hosts are in `known_hosts` before first use (or `StrictHostKeyChecking=accept-new` is configured) — this gives payload confidentiality and lets the daemon reach the genuine remote; **and** the daemon authenticates to the remote by key (the remote's `authorized_keys`), which gives command authenticity at the remote. The ProVerif model ([`proofs/proverif/`](../proofs/proverif/)) makes both halves explicit and shows which guarantee rests on which. |
Expand Down
4 changes: 4 additions & 0 deletions docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,10 @@ sudo pkexec-cache --create

Then configure your MCP client — see [MCP server](mcp.md).

The daemon refuses to start in a terminal other processes can type into (tmux,
screen, X11, kitty/WezTerm remote control, …). Run it in a terminal window of
its own on Wayland; see [Where to run the daemon](usage.md#where-to-run-the-daemon).

## Building locally

```bash
Expand Down
27 changes: 25 additions & 2 deletions docs/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,31 @@ the user during TUI approval.

**Execution isolation:** child processes run with cwd `/`, umask 0077, and
stdout/stderr piped — they do not inherit the socket file descriptor. stdin is
null except for sudo mode, which inherits the terminal so sudo can prompt for a
password.
null. Privileged children (sudo, pkexec) stay in the daemon's session so sudo
can open the terminal for its password prompt. Unprivileged children run in a
session of their own, with **no controlling terminal**, so they cannot inject
keystrokes into the approval prompt with `TIOCSTI` (GHSA-cpmp-67wf-gwmx).

**Approval terminal (GHSA-cpmp-67wf-gwmx):** the prompt cannot tell a key the
human typed from one another process running as the same user injected, and
an AI requester typically has a same-UID shell. So the daemon refuses to start
in a terminal that accepts synthetic input from other processes:

- tmux, GNU screen, zellij (`TERM`, `$TMUX`, `$STY`, `$ZELLIJ`);
- kitty, WezTerm, Konsole (remote control), VS Code's integrated terminal,
Emacs terminals;
- any terminal in an X11 session (XTEST, e.g. `xdotool key y`).

It prints each reason and exits. Run it in a terminal window of its own, on
Wayland (GNOME Terminal, foot, Alacritty, …). `sudo-proxy --allow-injectable-tty`
starts it anyway, and every prompt then carries a warning line. The override
has no `hosts.json` equivalent because an agent can write that file:
whoever starts the daemon decides. A kernel that still allows `TIOCSTI`
(`dev.tty.legacy_tiocsti`, or no such sysctl before 6.2) is reported as a
warning. Detection is best effort; see the residuals in
[threat-model.md](threat-model.md#coverage-and-residuals). The strongest
setup is to run the agent as a **separate Unix user**, or in a sandbox without
access to your display or your multiplexer's socket.

**TUI hardening:** the Y/N prompt reads a single keypress in non-canonical
terminal mode (no Enter required) and times out after 60 seconds (default deny).
Expand Down
5 changes: 5 additions & 0 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ cargo build --release
./target/release/sudo-proxy -v --socket /tmp/sp-test.sock
```

Terminal A must be a window of its own, outside tmux/screen and on Wayland:
the daemon refuses a terminal other processes can type into
(GHSA-cpmp-67wf-gwmx). To test inside tmux anyway, add
`--allow-injectable-tty`; every prompt then shows a warning line.

**Terminal B — send requests** with the freshly built client:

```bash
Expand Down
21 changes: 19 additions & 2 deletions docs/threat-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ invariant at a given boundary are omitted.
| Tampering | A huge argument pushes the real command and `[y/N]` off-screen. | Displayed command length bounded with a hidden-bytes marker. | G4.3 / F3 |
| DoS | Operator never answers, leaving the gate open. | 60 s timeout, default **deny**. | G5.2 |
| Elevation | Social-engineer the human into approving. | Covered by G4; residual printable-range look-alikes accepted. | G4.4 (residual) |
| Spoofing | A same-UID process **types the answer itself**: synthetic keystrokes into the approval terminal (`tmux send-keys`, `screen -X stuff`, kitty/wezterm remote control, Konsole D-Bus, X11 XTEST, `TIOCSTI`). The typical requester (an agent) has a same-UID shell, so A1 reaches this as A2. | The daemon refuses to start in a terminal that accepts such input (`ttyguard`: multiplexer `TERM`/`$TMUX`/`$STY`/`$ZELLIJ`, remote-control emulators, VS Code, Emacs, X11 without Wayland) unless started with `--allow-injectable-tty`, which puts a warning line in every prompt. There is deliberately no `hosts.json` equivalent, since an agent can write that file and restart the daemon through MCP. Unprivileged children run in their own session, with no controlling terminal, so they cannot `TIOCSTI` into the prompt. Legacy `TIOCSTI` is reported at startup. `sudo-proxy-mcp` scrubs the launcher's terminal variables from the window it spawns. | A1 (assumption, now checked) / GHSA-cpmp-67wf-gwmx |

### B4 — daemon → exec → root (A1)

Expand Down Expand Up @@ -136,8 +137,12 @@ A A root command runs that the human did NOT approve
│ │ [resolved path + "-> target" shown → G4.2 · blocked]
│ ├─ 3.3 Push the real command / [y/N] off-screen with a huge arg
│ │ [length bound + hidden-bytes marker → G4.3 / F3 · blocked]
│ └─ 3.4 Printable-range Unicode look-alike / NBSP in reason
│ [cannot hide the real command → G4.4 · residual (accepted)]
│ ├─ 3.4 Printable-range Unicode look-alike / NBSP in reason
│ │ [cannot hide the real command → G4.4 · residual (accepted)]
│ └─ 3.5 Answer the prompt without the human: inject `y` into the TTY
│ [startup refusal of injectable terminals; children without a
│ controlling tty → A1 / GHSA-cpmp-67wf-gwmx
│ · blocked for detected terminals (residual: undetected ones)]
│
└─ 4 Execute around the gate entirely (defeat G5 / G6)
├─ 4.1 Direct same-UID socket client bypassing MCP validate_host
Expand Down Expand Up @@ -167,6 +172,18 @@ is unaccounted for. The residuals — already on record and accepted — are:
- **loopback self-routing (F5, closed).** `is_local_host` normalizes self/loopback
targets; residual undetected aliases are covered by the C10 composition (every
remote daemon still gates unattended exec). See finding F5.
- **3.5 — keystroke injection into the approval terminal
(GHSA-cpmp-67wf-gwmx).** Detection reads environment variables and one sysctl,
so it is best effort. It does not see an XWayland terminal (e.g. `xterm`)
inside a Wayland session, an emulator with remote control it does not know,
or a process that shares the daemon's controlling terminal on a kernel that
still allows `TIOCSTI`. Nor does it cover `--pkexec`, whose polkit dialog has
X11's own synthetic-input exposure, or a daemon the operator started with
`--allow-injectable-tty`. An agent can always start a daemon of its own in a
terminal it controls; that daemon's `sudo` then has no cached credential for
the new terminal and asks for the password. The structural fix is to run the
agent as a separate Unix user, or in a sandbox without access to the display
or the multiplexer's socket.
- **3.4 — look-alike `reason` (F1 residual).** Printable Unicode can mislead but
cannot conceal the real command line, which is printed separately.
- **4.2 — SSH first-contact MITM (assumption A4).** The ssh invocation sets no
Expand Down
21 changes: 21 additions & 0 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,10 @@ sudo-proxy --no-shell
# Custom socket path
sudo-proxy --socket /tmp/my-proxy.sock

# Start even in a terminal other processes can type into (tmux, X11, …).
# Every prompt then shows a warning; see "Where to run the daemon" below.
sudo-proxy --allow-injectable-tty

# Send a request (debug client)
sudo-request id
sudo-request --reason "install web server" apt install nginx
Expand Down Expand Up @@ -114,6 +118,23 @@ sudo-request --no-privilege --plan-file ./scratch/plan.json
To drive a new feature end-to-end through the real daemon and human gate before
merging, see [testing.md](testing.md).

## Where to run the daemon

The approval prompt trusts the keypress it reads. Since 1.2.2 the daemon
refuses to start in a terminal that other processes running as you can type
into: tmux/screen/zellij panes, kitty/WezTerm/Konsole (remote control), VS
Code's or Emacs' terminal, and any terminal in an X11 session. It prints why
and exits (GHSA-cpmp-67wf-gwmx). Run it in a terminal window of its own on
Wayland. If the MCP server's `start_server` fails for this reason, start
`sudo-proxy` (or `sudo-proxy --host HOST`) yourself in such a terminal;
`start_server` then finds it running. To accept the risk, start it yourself
with `--allow-injectable-tty`. There is no `hosts.json` setting for this.

With `--host`, the check runs on the local terminal, where the remote prompt
is answered. The remote daemon checks too, and receives
`--allow-injectable-tty` when you passed it locally. A remote older than 1.2.2
rejects that flag, so upgrade remotes first.

## Remote hosts over SSH

`sudo-proxy --host HOST` resolves the remote UID (cached in
Expand Down
2 changes: 1 addition & 1 deletion packaging/mcpb/manifest.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"manifest_version": "0.3",
"name": "sudo-proxy",
"version": "1.2.1",
"version": "1.2.2",
"description": "Privileged command execution proxy with human approval via pkexec or sudo",
"author": {
"name": "Tarides"
Expand Down
8 changes: 4 additions & 4 deletions server.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"name": "io.github.tarides/sudo-proxy",
"title": "sudo-proxy",
"description": "Privileged command execution proxy with human approval via pkexec or sudo",
"version": "1.2.1",
"version": "1.2.2",
"repository": {
"url": "https://github.com/tarides/sudo-proxy",
"source": "github"
Expand All @@ -13,15 +13,15 @@
"registryType": "cargo",
"registryBaseUrl": "https://crates.io",
"identifier": "sudo-proxy",
"version": "1.2.1",
"version": "1.2.2",
"transport": {
"type": "stdio"
}
},
{
"registryType": "mcpb",
"identifier": "https://github.com/tarides/sudo-proxy/releases/download/v1.2.1/sudo-proxy-mcp-v1.2.1-x86_64-linux.mcpb",
"version": "1.2.1",
"identifier": "https://github.com/tarides/sudo-proxy/releases/download/v1.2.2/sudo-proxy-mcp-v1.2.2-x86_64-linux.mcpb",
"version": "1.2.2",
"fileSha256": "SHA256-INJECTED-BY-PUBLISH-WORKFLOW",
"transport": {
"type": "stdio"
Expand Down
Loading
Loading