ssh-mcp 2.10.0 → 2.12.0

package/README.md

@@ -154,7 +154,7 @@ claude mcp add --transport stdio ssh-mcp -- ssh-mcp
 | `read-command` | Execute allowlisted read-only commands (`ls`, `cat`, `grep`, ...) | ✅ | — |
 | `run-command` | Execute arbitrary commands (destructive/privileged need approval, unless `approvalPolicy = "auto"`) | — | — |
 | `privileged-command` | Execute with sudo (needs approval, unless `approvalPolicy = "auto"`) | — | ✅ |
-| `sftp-upload` | Upload a file via SFTP | — | ✅ |
+| `sftp-upload` | Upload a file via SFTP (replaces the destination unconditionally) | — | ✅ |
 | `sftp-download` | Download a file via SFTP | ✅ | — |
 | `sftp-list` | List a remote directory, bounded in entries and bytes | ✅ | — |
 | `sftp-upload-file` | Stream a local file to the remote host, never through model context | — | ✅ |
@@ -168,6 +168,24 @@ the text is an argument on the way out and a response on the way back. That is
 what you want for a config snippet and exactly what you do not want for a 200 MB
 tarball or anything binary.
 
+The two also differ on what they do to an existing destination, and the approved
+string now says which is which. `sftp-upload` replaces unconditionally and spells
+`--overwrite` every time, because that is what it always does; `sftp-upload-file`
+refuses unless you pass `overwrite: true`, and only then carries the flag. Since
+`sftp-upload` takes its content as an argument rather than naming a local file,
+its string also carries `--bytes=<n> --sha256=<32 hex>` — without that, two
+uploads to the same path are the same string, which means one approval covers
+both and an auditor cannot tell which set of bytes landed. The digest is 128
+bits rather than a short prefix because that claim has to hold against a caller
+who picks both payloads, not only against an accidental repeat.
+
+The path comes last in that string on purpose. `[policy].denylist` patterns are
+matched against the whole approved string, so a rule anchored on the path —
+`authorized_keys$`, the natural way to write "nothing may write here" — keeps
+working. A rule anchored on the *whole* string (`^sftp:upload /root/.*$`) does
+not: it was coupled to a format that is ours to change, and this release changes
+it. Anchor on the path segment instead.
+
 `sftp-upload-file` and `sftp-download-file` stream between the remote host and
 local disk instead. Neither the bytes nor a base64 encoding of them ever reaches
 the model — the response is a byte count and two paths.
@@ -298,6 +316,7 @@ role = "operator"                   # viewer | operator | admin
 readOnly = false
 approvalPolicy = "ask-all"
 cert = false                        # SSH CA cert auth — auto-detects keyRef-cert.pub
+announceAgent = true                # Send AI_AGENT=ssh-mcp to this host (see below); clear it for a host you do not control
 sessionMaxPerConnection = 3         # per-profile override
 sessionIdleTimeoutMs = 300000       # stricter for prod
 commandQuotaPerDay = 200            # per-profile override
@@ -322,6 +341,43 @@ and tier names: every one you write under `[policy.roleBindings]` has to be
 reachable by some profile, and every profile's role and tier has to resolve to
 real bindings. Both directions are checked at startup.
 
+### Host-side identification
+
+Every command this server runs announces itself to the host as the environment
+variable `AI_AGENT=ssh-mcp`, so an operator can tell an agent's session from a
+person's from anything on the host that reads the session environment — a
+`/etc/profile` snippet or a `ForceCommand` wrapper, for instance. It covers all
+three channels a command can run on: one-shot commands, background sessions and
+interactive sessions. SFTP transfers do not carry it, because the SSH library
+this server uses offers no way to send an environment request on a subsystem
+channel.
+
+**The variable only lands in the session if the host opts in** with
+`AcceptEnv AI_AGENT` in `sshd_config`. Without that line sshd ignores it and the
+session environment is unchanged — measured against Dropbear, which has no
+`AcceptEnv` mechanism at all, and against Windows OpenSSH on a default
+configuration: the command runs, the exit code is unchanged, the variable is
+simply absent.
+
+**The request is nevertheless sent to every host, opted in or not.** `AcceptEnv`
+is the server's policy about what it stores; it is not a gate on what this client
+transmits. A host that has not opted in — including one that is hostile — can
+still see on the wire that an agent rather than a person is driving the session.
+That is why `announceAgent = false` exists on the profile: set it for any host you
+do not control and nothing is sent to it. It is on by default, because the
+operators who benefit are the ones running the hosts you do control.
+
+No version is sent, deliberately. A version would narrow a hostile host to one
+specific build; the tool's name alone does not. (The SSH transport already
+discloses the *library* version in its identification string, which is one
+library's version across every program that uses it.)
+
+Treat the variable as a courtesy label, not an attestation. Any SSH client can
+set it and any agent can omit it, so it is useful for attributing sessions you
+already trust and must not be used as an authorization or intrusion-detection
+input. Authoritative attribution belongs to the key or principal that
+authenticated.
+
 ### ProxyJump (Bastion)
 
 Reach internal hosts behind a bastion/jump server. The `via` field specifies a profile name to tunnel through:
@@ -646,11 +702,12 @@ level number.
 - **Non-root** user in all examples
 - **TOFU** host key verification (accept on first connect, verify after — within one process; see [SECURITY.md](./SECURITY.md#host-key-trust-does-not-survive-a-restart))
 - **RFC 9142** algorithm allow-list (no SHA-1, no CBC, no ssh-rsa)
-- **exec()-only** (no persistent su shells — fixes PTY leak)
+- **exec()-only for elevation** (`privileged-command` takes no `session`, so sudo never runs in a persistent shell — fixes PTY leak. Interactive sessions exist for ordinary commands; this bullet is about elevation, not about every path being an exec channel)
 - **Sudo via stdin** (not argv — fixes process list leak)
 - **Sanitizer** strips CR/LF/NUL from all metadata
 - **3-layer redaction** (field → regex → entropy) on audit logs
 - **No CLI-arg secrets** (use env vars, keychain, or config)
+- **Agent announcement is disclosed, not hidden** — every command tells the host `AI_AGENT=ssh-mcp`, including hosts that never opted in to storing it; clear `announceAgent` on a profile pointing at a host you do not control (see [Host-side identification](#host-side-identification))
 
 ### Hardening Checklist
 
@@ -858,8 +915,10 @@ is an opt-out only for hosts you have not pinned (test environments only).
 ## Testing
 
 ```bash
-# Start test SSH server
-docker-compose --profile test up -d
+# Start test SSH servers. --build matters: compose reuses an existing image, and a
+# fixture change (such as the alpine target's AcceptEnv line) then never lands,
+# which shows up as a product failure in the integration suite.
+docker compose --profile test up -d --build
 
 # Run all tests
 npm test

package/build/cli.js

@@ -331,6 +331,9 @@ export async function buildAppConfig(argv) {
         role: 'admin',
         group: resolveHostGroup(argv),
         readOnly: false,
+        // Same default as the config schema. A CLI profile is the one-off case —
+        // --host/--user with no config file — and it announces like any other.
+        announceAgent: true,
         approvalPolicy: flagEnabled(argv, 'disableApproval') ? 'auto' : defaults.approvalMode,
         cert: false,
         sessionMaxPerConnection: defaults.sessionMaxPerConnection,

package/build/config/schema.js

@@ -161,6 +161,12 @@ export const profileSchema = z.object({
     role: z.string().default('operator'),
     readOnly: z.boolean().default(false),
     cert: z.boolean().default(false),
+    // A schema-level default rather than a [defaults] entry, like tty/readOnly/cert
+    // above: which hosts an operator trusts with the announcement is a property of
+    // the individual host, not something worth setting globally and overriding per
+    // profile. Defaults to true — the announcement is the feature; the switch is for
+    // the host you do not control.
+    announceAgent: z.boolean().default(true),
     // Left optional on purpose: normalizeConfig() fills these from [defaults], and
     // a schema-level .default() would make "user omitted it" indistinguishable
     // from "user set the default value", silently shadowing [defaults].

package/build/policy/classifier.js

@@ -17,18 +17,100 @@ import { AWK_NAMES, readAwkInvocation } from './awk.js';
  * write: run-command still accepts it under policy.
  */
 const SHELL_CONTROL_CHARS = /[;&|<>`$(){}\n\r]/;
-const READ_ONLY_ALLOWLIST = new Set([
-    'ls', 'cat', 'grep', 'find', 'stat', 'df', 'du', 'head', 'tail', 'wc',
-    'ps', 'uname', 'uptime', 'hostname', 'id', 'who', 'whoami', 'date',
-    'printenv', 'pwd', 'echo', 'printf', 'test', 'true', 'false',
-    'which', 'whereis', 'file', 'readlink', 'realpath', 'basename', 'dirname',
-    'seq', 'sort', 'uniq', 'cut', 'tr', 'diff', 'comm',
-    'systemctl status', 'journalctl', 'docker ps', 'docker logs', 'docker inspect',
-    'docker stats', 'docker images', 'free', 'top', 'htop', 'iostat', 'vmstat',
-    'netstat', 'ss', 'ifconfig', 'ip addr', 'ip route', 'arp', 'dig', 'nslookup',
-    'host', 'ping', 'traceroute', 'git status', 'git log',
-    'git diff', 'git branch', 'git show', 'git remote',
-]);
+/**
+ * The binaries this classifier will vouch for, and what it vouches for about them.
+ *
+ * Two questions, kept apart because one Set answering both is how #217 turned the
+ * interpreter carrier scan off for two verbs by adding them to a list about
+ * classes:
+ *
+ *   readOnly         does this binary only read?  -> decides the class
+ *   operandsAreData  can its operands hide a command?  -> decides whether the
+ *                    carrier scan runs
+ *
+ * Both are `true` for every entry today. The value is not the contents but that
+ * the type will not let the next person add a name without answering both.
+ *
+ * Two mechanisms answer the second question outside this table and are not
+ * affected by it — `DISQUALIFYING_ARGS` and `FIND_EXEC_FLAGS` — which is why
+ * `find` can carry `operandsAreData: true` while `find … -exec sudo id +` is
+ * still `privileged`.
+ *
+ * The two-word entries are looked up only for the class: `operandsAreData` reads
+ * a single word, so those rows never reach the second question.
+ */
+const READERS = {
+    "arp": { readOnly: true, operandsAreData: true },
+    "basename": { readOnly: true, operandsAreData: true },
+    "cat": { readOnly: true, operandsAreData: true },
+    "comm": { readOnly: true, operandsAreData: true },
+    "cut": { readOnly: true, operandsAreData: true },
+    "date": { readOnly: true, operandsAreData: true },
+    "df": { readOnly: true, operandsAreData: true },
+    "diff": { readOnly: true, operandsAreData: true },
+    "dig": { readOnly: true, operandsAreData: true },
+    "dirname": { readOnly: true, operandsAreData: true },
+    "docker images": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "docker inspect": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "docker logs": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "docker ps": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "docker stats": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "du": { readOnly: true, operandsAreData: true },
+    "echo": { readOnly: true, operandsAreData: true },
+    "false": { readOnly: true, operandsAreData: true },
+    "file": { readOnly: true, operandsAreData: true },
+    "find": { readOnly: true, operandsAreData: true },
+    "free": { readOnly: true, operandsAreData: true },
+    "git branch": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "git diff": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "git log": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "git remote": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "git show": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "git status": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "grep": { readOnly: true, operandsAreData: true },
+    "head": { readOnly: true, operandsAreData: true },
+    "host": { readOnly: true, operandsAreData: true },
+    "hostname": { readOnly: true, operandsAreData: true },
+    "htop": { readOnly: true, operandsAreData: true },
+    "id": { readOnly: true, operandsAreData: true },
+    "ifconfig": { readOnly: true, operandsAreData: true },
+    "iostat": { readOnly: true, operandsAreData: true },
+    "ip addr": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "ip route": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "journalctl": { readOnly: true, operandsAreData: true },
+    "ls": { readOnly: true, operandsAreData: true },
+    "netstat": { readOnly: true, operandsAreData: true },
+    "nslookup": { readOnly: true, operandsAreData: true },
+    "ping": { readOnly: true, operandsAreData: true },
+    "printenv": { readOnly: true, operandsAreData: true },
+    "printf": { readOnly: true, operandsAreData: true },
+    "ps": { readOnly: true, operandsAreData: true },
+    "pwd": { readOnly: true, operandsAreData: true },
+    "readlink": { readOnly: true, operandsAreData: true },
+    "realpath": { readOnly: true, operandsAreData: true },
+    "seq": { readOnly: true, operandsAreData: true },
+    "sort": { readOnly: true, operandsAreData: true },
+    "ss": { readOnly: true, operandsAreData: true },
+    "stat": { readOnly: true, operandsAreData: true },
+    "systemctl status": { readOnly: true, operandsAreData: true }, // two-word: class only
+    "tail": { readOnly: true, operandsAreData: true },
+    "test": { readOnly: true, operandsAreData: true },
+    "top": { readOnly: true, operandsAreData: true },
+    "tr": { readOnly: true, operandsAreData: true },
+    "traceroute": { readOnly: true, operandsAreData: true },
+    "true": { readOnly: true, operandsAreData: true },
+    "uname": { readOnly: true, operandsAreData: true },
+    "uniq": { readOnly: true, operandsAreData: true },
+    "uptime": { readOnly: true, operandsAreData: true },
+    "vmstat": { readOnly: true, operandsAreData: true },
+    "wc": { readOnly: true, operandsAreData: true },
+    "whereis": { readOnly: true, operandsAreData: true },
+    "which": { readOnly: true, operandsAreData: true },
+    "who": { readOnly: true, operandsAreData: true },
+    "whoami": { readOnly: true, operandsAreData: true },
+};
+/** The class half of READERS, as the shape its consumers already expect. */
+const READ_ONLY_ALLOWLIST = new Set(Object.entries(READERS).filter(([, e]) => e.readOnly).map(([name]) => name));
 // Deliberately NOT read-only: `env`, because it is an exec wrapper. `env <cmd>`
 // runs <cmd>, so allowlisting the name `env` vouched for a command the
 // classifier never looked at — `env sudo rm -f /etc/passwd` classified
@@ -177,44 +259,123 @@ const CLASS_RANK = {
     destructive: 2,
     privileged: 3,
 };
+const INTERPRETERS = Object.assign(Object.create(null), {
+    sh: { programBearingWords: ['-c'], readable: true },
+    bash: { programBearingWords: ['-c'], readable: true },
+    dash: { programBearingWords: ['-c'], readable: true },
+    zsh: { programBearingWords: ['-c'], readable: true },
+    ksh: { programBearingWords: ['-c'], readable: true },
+    ash: { programBearingWords: ['-c'], readable: true },
+    python: { programBearingWords: ['-c'], readable: false },
+    python2: { programBearingWords: ['-c'], readable: false },
+    python3: { programBearingWords: ['-c'], readable: false },
+    perl: { programBearingWords: ['-e', '-E'], readable: false },
+    ruby: { programBearingWords: ['-e'], readable: false },
+    // `-p`/`--print` evaluate exactly as `-e` does and then print the result.
+    node: { programBearingWords: ['-e', '--eval', '-p', '--print'], readable: false },
+    php: { programBearingWords: ['-r'], readable: false },
+    // Measured on 2.11.0: each of these classified `safe` while the identical
+    // attack through python3 -c classified `destructive` (GHSA-qmx6-47vm-3vf7).
+    // `readable: false` throughout, matching python/perl/node: the program is not
+    // shell text, so its presence is what counts rather than its content.
+    osascript: { programBearingWords: ['-e'], readable: false },
+    lua: { programBearingWords: ['-e'], readable: false },
+    Rscript: { programBearingWords: ['-e'], readable: false },
+    bun: { programBearingWords: ['-e'], readable: false },
+    // No program-bearing flag: real tclsh takes a script FILE as its positional
+    // argument or reads one from stdin, unlike sh/bash/python/pwsh, none of
+    // which have a `-c` of its own. An empty list still marks tclsh as an
+    // unreadable interpreter for `readsProgramFromStdin` (`echo … | tclsh`),
+    // which is the genuine carrier; it is simply never handed a program inline
+    // on its own command line, so there is no flag to name here.
+    tclsh: { programBearingWords: [], readable: false },
+    // `eval` is a subcommand, not a flag — the field is named for what it holds.
+    deno: { programBearingWords: ['eval'], readable: false },
+    pwsh: { programBearingWords: ['-c', '-Command', '-e', '-EncodedCommand'], readable: false },
+    powershell: { programBearingWords: ['-c', '-Command', '-e', '-EncodedCommand'], readable: false },
+});
 /**
- * Interpreters, the flags that hand them a program, and whether this file can read it.
+ * Every `INTERPRETERS` entry, keyed by its name lower-cased.
  *
- * One table rather than three overlapping name lists: adding an interpreter here is the
- * whole change, and a shell list that drifts out of step with a readability list is how a
- * new shell ends up treated as an unreadable interpreter.
+ * A second index rather than lower-casing the lookup key against `INTERPRETERS`
+ * directly, because that table's own keys are not uniformly lower-case —
+ * `Rscript` is not `rscript` — so folding only the *input* would still miss it.
+ * Built once at module load: the table is fixed, so there is nothing to keep in
+ * sync.
+ */
+const INTERPRETERS_BY_LOWERCASE_NAME = Object.assign(Object.create(null), Object.fromEntries(Object.entries(INTERPRETERS).map(([name, spec]) => [name.toLowerCase(), spec])));
+/** A Windows executable suffix this table's keys never carry. */
+const WINDOWS_EXE_SUFFIX = /\.(exe|cmd|bat)$/i;
+/**
+ * Resolve an interpreter table entry for a command word already stripped of
+ * its path (`stripPath(unquote(word))`, as every call site already computes
+ * it for the exact-match case below).
  *
- * `readable` means the program is shell, so classifying it is this same job done again
- * and the class it earns is real. Python, Perl, Ruby, Node and PHP are not: their program
- * is a different language, and `os.system('sudo id')` carries an elevation the shell
- * classifier cannot see. Pretending to parse them would be a worse answer than admitting
- * we cannot, so an unreadable program makes the command `destructive` — "we cannot tell",
- * not "this is root", the same answer `hasUnnameableCommand` gives.
+ * The table's keys are exact, case-sensitive, extension-free spellings, so a
+ * direct lookup is tried first and is the whole cost for the common case —
+ * `sh`, `python3`, the bare lowercase `pwsh`. The fallback strips a trailing
+ * `.exe`/`.cmd`/`.bat` and folds case, which is what a Windows target's own
+ * shell hands back for the *same* binary: `powershell.exe`, `PWSH.EXE` and
+ * `PowerShell` all name the interpreter this table already lists under
+ * `powershell`/`pwsh`.
  *
- * `busybox` is not here: it takes an applet name, not `-c`, so `busybox sh -c …` is an
- * `sh` invocation behind a wrapper. It is in EXEC_WRAPPERS instead, which is what it is.
+ * Applied to every entry, not only pwsh/powershell. The measured bug is
+ * about those two, but the gap is not specific to them: a target running
+ * `python.exe` or `Node.EXE` carries the identical mismatch, and scoping the
+ * fix to two names would leave the rest of the table exactly as blind as it
+ * was. This is the binary-*name* question, answered once — it does not touch
+ * flag matching, which stays case-sensitive per interpreter (`perl -E` and
+ * `perl -e` are still two different flags) via the existing, separate
+ * `caseInsensitive` parameter threaded through `programAfterFlag` and
+ * friends.
  */
-// Null-prototype for the reason `mergePolicyRules` spells out (#172): this is indexed by
-// a command word, which is a free string, so on a plain object `INTERPRETERS['toString']`
-// resolves to a function and reading `.flags` off it throws inside the policy gate.
-const INTERPRETERS = Object.assign(Object.create(null), {
-    sh: { flags: ['-c'], readable: true },
-    bash: { flags: ['-c'], readable: true },
-    dash: { flags: ['-c'], readable: true },
-    zsh: { flags: ['-c'], readable: true },
-    ksh: { flags: ['-c'], readable: true },
-    ash: { flags: ['-c'], readable: true },
-    python: { flags: ['-c'], readable: false },
-    python2: { flags: ['-c'], readable: false },
-    python3: { flags: ['-c'], readable: false },
-    perl: { flags: ['-e', '-E'], readable: false },
-    ruby: { flags: ['-e'], readable: false },
-    // `-p`/`--print` evaluate exactly as `-e` does and then print the result.
-    node: { flags: ['-e', '--eval', '-p', '--print'], readable: false },
-    php: { flags: ['-r'], readable: false },
-});
+function resolveInterpreter(word) {
+    const exact = INTERPRETERS[word];
+    if (exact !== undefined)
+        return exact;
+    return INTERPRETERS_BY_LOWERCASE_NAME[word.replace(WINDOWS_EXE_SUFFIX, '').toLowerCase()];
+}
 /** `find … -exec <cmd> +` runs cmd. */
 const FIND_EXEC_FLAGS = new Set(['-exec', '-execdir', '-ok', '-okdir']);
+/**
+ * GNU sort's own long-option table, spelled in full — every entry `sort
+ * --help` lists (coreutils 9.11, `docker exec ssh-mcp-ssh-admin-1 sort
+ * --help`). Used only to compute which prefixes of `--output` and
+ * `--compress-program` `getopt_long` treats as unambiguous.
+ *
+ * `getopt_long` resolves a `--` word to the option whose name it is an
+ * unambiguous prefix of: a prefix shared with another option name is
+ * refused outright ("option '--c' is ambiguous; possibilities: '--check'
+ * '--compress-program'") rather than run, so it must not be treated as a
+ * write. Measured against the binary: `sort --c=x k` exits 2 with no file
+ * created; `sort --co=x k` — the second letter is where `--check` and
+ * `--compress-program` diverge — runs.
+ */
+const SORT_LONG_OPTIONS = [
+    'ignore-leading-blanks', 'dictionary-order', 'ignore-case',
+    'general-numeric-sort', 'ignore-nonprinting', 'month-sort',
+    'human-numeric-sort', 'numeric-sort', 'random-sort', 'random-source',
+    'reverse', 'sort', 'version-sort', 'batch-size', 'check',
+    'compress-program', 'debug', 'files0-from', 'key', 'merge', 'output',
+    'stable', 'buffer-size', 'field-separator', 'temporary-directory',
+    'parallel', 'unique', 'zero-terminated', 'help', 'version',
+];
+/**
+ * The regex-alternation source matching any prefix of `full` that names
+ * exactly one entry of `SORT_LONG_OPTIONS` — every prefix `getopt_long`
+ * would accept for it, from the shortest unambiguous one up to `full`
+ * itself — each optionally followed by `=value`.
+ */
+function unambiguousLongOptionSource(full) {
+    const prefixes = [];
+    for (let len = 1; len <= full.length; len++) {
+        const prefix = full.slice(0, len);
+        if (SORT_LONG_OPTIONS.filter((opt) => opt.startsWith(prefix)).length === 1) {
+            prefixes.push(prefix);
+        }
+    }
+    return `--(?:${prefixes.join('|')})(?:=|$)`;
+}
 /**
  * How deep a substitution may nest before we stop reading and refuse to guess.
  *
@@ -406,8 +567,22 @@ function matchesEitherForm(command, test) {
  * Four carriers, all of which a remote shell expands and runs:
  *   `$(...)`, backticks, process substitution `<(...)` / `>(...)`, and a shell
  *   given `-c`.
+ *
+ * @param speculativeOperands Whether the catch-all below — any multi-word,
+ *   non-flag operand of a segment no more specific reader claimed — should be
+ *   pushed. That catch-all is a guess about a binary this file does not
+ *   recognise; the four carriers above are not guesses, the shell really does
+ *   run what they hold, and are pushed regardless of this flag. Defaults to
+ *   `true` for `classifyCommand`'s own recursion, where a guess may raise a
+ *   command's *class* and leave role, tier and approval to weigh in.
+ *   `findForbiddenMatch` passes `false`: its recursion feeds
+ *   `FORBIDDEN_RULES`, the one unconditional denylist, and a guess must not
+ *   be able to produce a refusal nobody can override (the maintainer's
+ *   ruling — see the block comment above `findForbiddenMatch`). `$()`,
+ *   backticks and `sh -c` are certain carriers and keep reaching the
+ *   denylist either way.
  */
-export function nestedCommands(command) {
+export function nestedCommands(command, speculativeOperands = true) {
     const found = [];
     // `$(...)`, `<(...)`, `>(...)` — scanned rather than matched, because a regex
     // cannot balance parentheses and `echo $(echo $(sudo id))` is the case that
@@ -468,13 +643,86 @@ export function nestedCommands(command) {
         for (const inner of awk?.pipedInto ?? [])
             found.push(inner);
         if (!operandsAreData(words)) {
+            // Which operand *indices* an interpreter actually consumed as a program —
+            // not whether the segment's head happens to be a name in the table, and not
+            // a single segment-wide flag either. A set of indices rather than a boolean:
+            // `unknownbin sh -c true 'sudo id'` has `sh -c` consume `true` (harmless,
+            // pushed below) and leave `'sudo id'` untouched, and a boolean here defused
+            // the catch-all for that second operand too — measured, it classified
+            // `safe`. Only the specific word an interpreter actually read should be
+            // excluded from the catch-all; every other operand in the segment is still
+            // this binary's own, unclaimed by anything more specific.
+            //
+            // A binary being recognised is also not the same as this segment's
+            // invocation of it being one the loop could parse:
+            // `pwsh -ExecutionPolicy Bypass -Command 'sudo id'` has a recognised head
+            // and a program on the line, but `-ExecutionPolicy` takes a value
+            // (`Bypass`) that isn't itself a flag, and `programAfterFlag` gives up
+            // rather than guess past it. Gating the catch-all below on "head is in the
+            // table" excluded exactly the binaries this file just learned, and for
+            // precisely the invocations its own flag-walk cannot follow — a net
+            // regression, not a wash.
+            const consumedOperands = new Set();
             for (let i = 0; i < words.length; i++) {
-                const spec = INTERPRETERS[stripPath(unquote(words[i]))];
-                if (spec === undefined || isFlagValue(words, i, spec.flags))
+                const spec = resolveInterpreter(stripPath(unquote(words[i])));
+                // pwsh/powershell's own parameter binder resolves `-ENC`/`-Enc`/`-enc` to the
+                // same parameter; every other interpreter's flags are exact letters (`-E` and
+                // `-e` are different flags to perl). `-EncodedCommand` only ever appears on
+                // the two entries whose own parameter binder works this way, so its presence
+                // is the signal for which interpreter this is, not a hardcoded name check.
+                const caseInsensitive = spec?.programBearingWords.includes('-EncodedCommand') ?? false;
+                if (spec === undefined || isFlagValue(words, i, spec.programBearingWords, caseInsensitive))
                     continue;
-                const program = programAfterFlag(words, i, spec.flags);
-                if (program !== null)
-                    found.push(program);
+                // Same signal, second job: pwsh/powershell's argument parser also does not stop
+                // at an unrecognised option's bare value (`-ExecutionPolicy Bypass`) the way a
+                // POSIX interpreter stops at its first positional argument. See
+                // `programAfterFlag`'s `tolerateUnknownWordsAtHead` for why this is scoped to
+                // `i === 0` there rather than here.
+                const result = programAfterFlag(words, i, spec.programBearingWords, caseInsensitive, caseInsensitive);
+                if (result !== null) {
+                    consumedOperands.add(result.index);
+                    found.push(result.program);
+                    // An encoded program is opaque to every text scan until it is decoded. Gated on
+                    // the word `programAfterFlag` actually matched — the table's own canonical
+                    // spelling, so every case-folded or clustered form of `-EncodedCommand`/`-e`
+                    // reaches this the same way a literal `-EncodedCommand` does — not a scan of
+                    // the whole segment for one long spelling.
+                    if (caseInsensitive && (result.flag === '-EncodedCommand' || result.flag === '-e')) {
+                        const decoded = decodedPowerShellCommand(result.program);
+                        if (decoded !== null)
+                            found.push(decoded);
+                    }
+                }
+            }
+            // An operand of a binary nothing more specific has read is classified as a
+            // command in its own right, rather than scanned as text.
+            //
+            // The gate is the awk reader's own result, and now which specific operands
+            // an interpreter actually consumed, rather than a list of names: a name
+            // list here would be the defect this change exists to fix
+            // (GHSA-qmx6-47vm-3vf7), and "the head is a name in the table" turned out
+            // to be one too — it answers a different question than "did this
+            // invocation's program-bearing word actually resolve". `awk` is already
+            // null for every non-awk segment.
+            //
+            // Whitespace is what separates an operand worth classifying from one that is
+            // not: a single token is a path, a flag value or a subcommand, while a
+            // multi-word operand has the shape of a command. Flags are skipped.
+            //
+            // Deliberately NOT a text scan for `sudo`. That version asserted elevations
+            // the awk reader and the variable-command-word logic refuse to assert — both
+            // cap at `destructive` on purpose — and it out-ranked the nested
+            // classification that names the elevated binary, reporting `awk` where `id`
+            // was correct.
+            if (speculativeOperands && awk === null) {
+                for (let i = 1; i < words.length; i++) {
+                    if (consumedOperands.has(i))
+                        continue;
+                    if (words[i].startsWith('-'))
+                        continue;
+                    if (/\s/.test(words[i]))
+                        found.push(words[i]);
+                }
             }
         }
         // `-exec` is a flag rather than a command word, so this one is still a scan.
@@ -541,7 +789,58 @@ const EXEC_WRAPPERS = new Set([
  * the `+` terminator carries none.
  */
 // Null-prototype for the same reason as INTERPRETERS: indexed by the command word.
-const DISQUALIFYING_ARGS = Object.assign(Object.create(null), { find: /^-(exec|execdir|ok|okdir|delete|fprintf?|fls)$/ });
+const DISQUALIFYING_ARGS = Object.assign(Object.create(null), {
+    find: /^-(exec|execdir|ok|okdir|delete|fprintf?|fls)$/,
+    // GNU sort execs this for every temporary file it spills, so a reader
+    // becomes a launcher. Measured against coreutils 9.11: an attacker-named
+    // script ran 14,224 times for one 200k-line input, and the whole command
+    // classified `read-only` — which a `readOnly` viewer is allowed to run,
+    // while running that same program directly is denied.
+    //
+    // `-o FILE` / `--output=FILE` is the same shape of bug with a plainer
+    // payoff: it creates and truncates FILE, which is a write a `readOnly`
+    // profile must never reach through a command classified `read-only`.
+    // Measured on HEAD before this rule: `sort -o /root/.ssh/authorized_keys
+    // /tmp/key.pub` classified `read-only`.
+    //
+    // Targeted round (2026-09-24, R2+R3): the version above closed the exact
+    // spellings `-o`, `--output` and `--compress-program` and left the CLASS
+    // open — GNU sort's own option grammar has two escapes past a fixed
+    // spelling, both measured against the real binary:
+    //
+    //  - A short-option cluster is scanned left to right, and any of sort's
+    //    own *argument-less* short flags may sit ahead of `-o` without
+    //    consuming it: `sort -mo out in` writes `out` exactly as `sort -o out
+    //    in` does. `-m` (merge) is itself argument-less, and its absence from
+    //    the char class below is exactly what let `sort -mo …` through as
+    //    `read-only`.
+    //  - `getopt_long` resolves a `--` word by unambiguous-prefix matching:
+    //    `--o`, `--ou`, `--out`, `--outp`, `--outpu` all mean `--output`
+    //    (nothing else starts with `o`), and `--co` through
+    //    `--compress-progra` all mean `--compress-program` (`--c` alone is
+    //    ambiguous with `--check` and sort refuses to run at all —
+    //    `unambiguousLongOptionSource` excludes it for exactly that reason,
+    //    computed from sort's own option table rather than hand-picked).
+    //
+    // The cluster branch is still deliberately narrower than "any `o` in a
+    // dash word": `-[bcCdfghiMmnRrsuVz]*o` only allows GNU sort's own
+    // argument-less short flags ahead of the `o`, so it stops at the first
+    // flag that takes a value of its own. Without that, `-tofile` — `-t`
+    // (field separator) with its value attached, not `-o` — would be
+    // misread as a write. `-t`, `-k`, `-S` and `-T` are exactly the short
+    // flags this excludes, because each consumes the rest of a clustered
+    // word as its own argument, so a following `o` is that argument's text,
+    // not `-o` invoked.
+    //
+    // `find`'s entry above does not get the same prefix-abbreviation
+    // treatment: `find` parses its predicates itself rather than through
+    // `getopt_long`, and accepts no abbreviated spelling of `-exec` — `find .
+    // -exe` is "unknown predicate `-exe`", measured. There is no class to
+    // close there.
+    sort: new RegExp(`^(?:${unambiguousLongOptionSource('compress-program')}`
+        + `|${unambiguousLongOptionSource('output')}`
+        + '|-[bcCdfghiMmnRrsuVz]*o)'),
+});
 /** A leading `NAME=value`, which a shell treats as an assignment, not a command. */
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
 /** `timeout 5s`, `nice 10` — a bare argument some wrappers take before the command. */
@@ -673,11 +972,26 @@ function elevatedBinaryOf(command) {
  * behind a wrapper, behind an assignment, or after a separator all reached root
  * with the command classified `safe` or `read-only`.
  */
-/** An allowlisted binary carrying a flag that makes it write or execute. */
+/**
+ * An allowlisted binary carrying a flag that makes it write or execute.
+ *
+ * Keyed on `effectiveCommandIndex`, not `parseSegments`. `parseSegments`
+ * (`parseWords`) only steps over a privilege prefix (`sudo`, `su`, …), not an
+ * exec wrapper (`env`, `nohup`, `timeout`, …), so `env sort
+ * --compress-program=X` read `head` as `"env"` — not in `DISQUALIFYING_ARGS`
+ * — and the flag went unnoticed. `effectiveCommandIndex` already reads past
+ * both, which is what `operandsAreData` and `readsProgramFromStdin` use it
+ * for. Deliberately not fixed by changing `parseWords` itself:
+ * `invokedWords` also reads it, and widening what counts as "the command"
+ * there is a different, larger change this fix does not take on.
+ */
 function hasDisqualifyingArgs(command) {
-    return parseSegments(command).some(({ head, args }) => {
-        const rule = DISQUALIFYING_ARGS[head];
-        return rule !== undefined && args.some((arg) => rule.test(arg));
+    return tokenizeSegments(command).some((words) => {
+        const idx = effectiveCommandIndex(words);
+        if (idx === -1)
+            return false;
+        const rule = DISQUALIFYING_ARGS[stripPath(words[idx])];
+        return rule !== undefined && words.slice(idx + 1).some((arg) => rule.test(arg));
     });
 }
 function invokedWords(command) {
@@ -769,9 +1083,21 @@ export function findForbiddenMatch(command, depth = 0) {
     // They still classified `destructive`, which on the `prod` tier degrades an
     // absolute `deny` into `require-approval`: a rule that answers "never" became
     // one a human can click through.
+    //
+    // `speculativeOperands: false` — the maintainer's ruling. `nestedCommands`'
+    // catch-all is a guess about an unrecognised binary's operands, and this loop
+    // feeds the one unconditional rule in the policy: a guess may raise a
+    // command's class, which role, tier and approval still get to weigh in on,
+    // but it must not manufacture a refusal nobody can override. Measured before
+    // this parameter existed: `git commit -m 'reboot the worker pool'` was a hard
+    // deny on an admin profile with `approvalPolicy: 'auto'`, because the catch-all
+    // read the quoted commit message as an operand starting with a forbidden word.
+    // `$()`, backticks and `sh -c` are certain carriers, not guesses — the shell
+    // really does run what they hold — and are unaffected: they are pushed by
+    // `nestedCommands` regardless of this flag.
     if (depth >= MAX_NESTING_DEPTH)
         return null;
-    for (const inner of nestedCommands(command)) {
+    for (const inner of nestedCommands(command, false)) {
         const match = findForbiddenMatch(inner, depth + 1);
         if (match !== null)
             return match;
@@ -874,7 +1200,9 @@ function effectiveCommandIndex(words) {
  */
 function operandsAreData(words) {
     const idx = effectiveCommandIndex(words);
-    return idx !== -1 && READ_ONLY_ALLOWLIST.has(stripPath(unquote(words[idx])));
+    if (idx === -1)
+        return false;
+    return READERS[stripPath(unquote(words[idx]))]?.operandsAreData === true;
 }
 /**
  * Whether an interpreter name is the value of the flag before it rather than a command.
@@ -904,59 +1232,169 @@ function operandsAreData(words) {
 function skippableBetweenFlags(word) {
     return word === '' || word.startsWith('-');
 }
-function isFlagValue(words, i, flags) {
+/**
+ * Whether `word` is a spelling of `flag`, honouring case-insensitivity when asked.
+ *
+ * Scoped per call, never globally: pwsh/powershell's own parameter binder resolves
+ * `-ENC`, `-Enc` and `-enc` to the same parameter, but `-E` and `-e` are two different
+ * flags to perl. Every caller here is told explicitly, per invocation, whether the
+ * interpreter it is matching against is one of the case-insensitive ones — folding case
+ * is never the default.
+ */
+function sameFlag(word, flag, caseInsensitive) {
+    return caseInsensitive ? word.toLowerCase() === flag.toLowerCase() : word === flag;
+}
+function isFlagValue(words, i, flags, caseInsensitive = false) {
     if (i === 0)
         return false;
     const previous = words[i - 1];
-    return previous.length > 1 && previous.startsWith('-') && flags.includes(previous);
+    if (!(previous.length > 1 && previous.startsWith('-')))
+        return false;
+    return flags.some((f) => sameFlag(previous, f, caseInsensitive));
 }
 /**
  * The program an interpreter was handed on its command line, or null.
  *
  * Only flags may sit between the interpreter and its flag; anything else means this was
  * not that kind of invocation, which is what keeps `python3 script.py` — a program this
- * cannot read either, but one every deployment runs — out of the gate.
+ * cannot read either, but one every deployment runs — out of the gate. That rule holds
+ * for every interpreter here except pwsh/powershell (see `tolerateUnknownWordsAtHead`):
+ * real POSIX interpreters stop parsing their own options at the first positional
+ * argument — `python3 script.py -c 'evil'` hands `-c evil` to the script as `argv`, not
+ * to python — so treating a bare word as "not this kind of invocation" is correct for
+ * them, not merely convenient.
+ *
+ * Returns which of `flags` matched alongside the program, not just the program text, so
+ * a caller can tell `-EncodedCommand` from its `-e` abbreviation apart from every other
+ * program-bearing word — decoding is specific to that one flag, and both spellings reach
+ * here as an ordinary match.
+ *
+ * @param tolerateUnknownWordsAtHead pwsh/powershell's own argument parser walks the
+ *   whole command line looking for named parameters it recognises and does not stop at
+ *   an unrecognised one's value (`-ExecutionPolicy Bypass`) the way a POSIX interpreter
+ *   stops at its first positional argument. Only takes effect when `from` is the
+ *   segment's *effective* command word — `effectiveCommandIndex(words)`, which reads
+ *   past a privilege prefix or an exec wrapper (`env`, `nohup`, `timeout`, …), not merely
+ *   position 0. `from === 0` missed exactly the shape those wrappers exist to describe:
+ *   `env pwsh -ExecutionPolicy Bypass -EncodedCommand …` put `pwsh` at index 1, the
+ *   tolerance never engaged, and the interpreter loop's own flag-walk gave up at
+ *   `Bypass` before ever reaching `-EncodedCommand` — classified `safe`. Still unambiguous
+ *   about *which* word is being invoked, not a value or a search term this file has no
+ *   business reinterpreting (`grep -e perl -e python` never reaches here with this set,
+ *   because `perl` is not the segment's effective command word and isn't pwsh-family
+ *   regardless; nor is `customtool --search pwsh …`, where `customtool` is). Structural,
+ *   not a list of pwsh's value-taking flags: this file does not need to know
+ *   `-ExecutionPolicy` exists to stop being confused by it.
  */
-function programAfterFlag(words, from, flags) {
+function programAfterFlag(words, from, flags, caseInsensitive = false, tolerateUnknownWordsAtHead = false) {
+    const tolerateUnknownWords = tolerateUnknownWordsAtHead && from === effectiveCommandIndex(words);
     for (let j = from + 1; j < words.length; j++) {
         const word = words[j];
-        if (flags.includes(word))
-            return words[j + 1] ?? null;
+        const exact = flags.find((f) => sameFlag(word, f, caseInsensitive));
+        if (exact !== undefined) {
+            // A subcommand — a program-bearing word that is not itself a `-` flag, such as
+            // `deno`'s `eval` — may still have its own options before the code: `deno eval
+            // --unstable <code>` is one invocation, not two. A real flag like `-c` or
+            // `-Command` never has anything of its own between it and the program, so this
+            // only widens the subcommand case.
+            let k = j + 1;
+            if (!exact.startsWith('-')) {
+                while (k < words.length && skippableBetweenFlags(words[k]))
+                    k++;
+            }
+            const program = words[k];
+            return program === undefined ? null : { program, flag: exact, index: k };
+        }
+        // Deliberately case-SENSITIVE even for pwsh/powershell: this branch exists for a
+        // value glued directly onto a short flag with no separating space (`-csudo id`).
+        // Folding case here as well made `-ExecutionPolicy` — a real pwsh option this file
+        // does not otherwise track — case-insensitively start with `-e` and get read as
+        // `-e` plus an attached `xecutionPolicy`, which swallowed `-ExecutionPolicy Bypass
+        // -Command 'sudo id'` into `destructive` and, worse, made `foundProgram` true so
+        // the catch-all below never ran. Every case-insensitive spelling the table needs
+        // to accept (`-enc`, `-ec`, `-EC`, `-ENC`, `-E`, `-EncodedCOMMAND`, `-COMMAND`,
+        // `-C`, …) is already reached through the exact match above or the cluster match
+        // below, so this branch does not need to fold case to cover them.
         const attached = flags.find((f) => word.startsWith(f) && word.length > f.length);
         if (attached !== undefined) {
             const rest = word.slice(attached.length);
             // `sh -c'sudo id'` tokenises to `-csudo id`, so the program is attached. `bash -cx`
             // is a flag cluster and the program is the next word. A space, or the `=` of
             // `--eval=…`, is what tells them apart: a cluster is letters only.
-            if (/\s/.test(rest) || rest.startsWith('='))
-                return rest.replace(/^=/, '');
-            return words[j + 1] ?? null;
+            if (/\s/.test(rest) || rest.startsWith('=')) {
+                return { program: rest.replace(/^=/, ''), flag: attached, index: j };
+            }
+            const program = words[j + 1];
+            return program === undefined ? null : { program, flag: attached, index: j + 1 };
         }
         // The program flag need not lead the cluster: `bash -xc 'sudo id'` runs exactly what
         // `bash -cx 'sudo id'` runs, and a prefix test saw the second and missed the first.
-        if (clusterCarriesFlag(word, flags))
-            return words[j + 1] ?? null;
-        if (!skippableBetweenFlags(word))
+        const clusterFlag = clusterCarriesFlag(word, flags, caseInsensitive);
+        if (clusterFlag !== null) {
+            const program = words[j + 1];
+            return program === undefined ? null : { program, flag: clusterFlag, index: j + 1 };
+        }
+        if (!skippableBetweenFlags(word) && !tolerateUnknownWords)
             return null;
     }
     return null;
 }
+/** How much base64 is worth decoding before the answer stops changing. */
+const MAX_ENCODED_CHARS = 64 * 1024;
+/**
+ * The command inside `-EncodedCommand`, or null.
+ *
+ * PowerShell encodes UTF-16LE, so decoding as utf8 yields text with a NUL between
+ * every character and no pattern matches it. `Buffer.from(x, 'base64')` never
+ * throws — it drops characters outside the alphabet — so malformed input produces
+ * a wrong answer rather than an exception, and the caller must treat null and
+ * nonsense alike: the flag alone has already made the command `destructive`.
+ *
+ * Reads a bounded, 4-aligned PREFIX rather than refusing outright past the limit. A
+ * refusal is a downgrade path: it turns "pad the payload past 64 KiB" into a way to
+ * trade `privileged` for `destructive`, which is strictly better for whoever is padding
+ * it. 4-aligned because base64 decodes in groups of four characters to three bytes;
+ * truncating mid-group corrupts the last partial character instead of just dropping
+ * trailing content the decode was never going to reach anyway.
+ */
+function decodedPowerShellCommand(operand) {
+    const prefix = operand.length > MAX_ENCODED_CHARS
+        ? operand.slice(0, MAX_ENCODED_CHARS - (MAX_ENCODED_CHARS % 4))
+        : operand;
+    const decoded = Buffer.from(prefix, 'base64').toString('utf16le');
+    return decoded.includes('�') || decoded.trim() === '' ? null : decoded;
+}
 /**
- * What follows a short flag inside a single-dash cluster, or null if it holds none.
+ * What follows a short flag inside a single-dash cluster, or the `flags` entry it
+ * carries, or null if it carries none.
  *
  * Clusters only — a run of single letters after one dash. Long flags and attached values
- * are handled before this is reached.
+ * are handled before this is reached. Returns the canonical flag rather than a boolean
+ * for the same reason `programAfterFlag` does: a caller deciding whether to decode
+ * compares against the table's own spellings, not against whatever letters happened to
+ * be clustered together.
  */
-function clusterCarriesFlag(word, flags) {
+function clusterCarriesFlag(word, flags, caseInsensitive = false) {
     // Three letters at most. `/^-[A-Za-z]+$/` alone also matches every single-dash long
     // option, and `find`'s predicates are full of them: `-type` contains perl's `-e`, so
     // `find . -name perl -type f` read as a carrier and asked for approval.
     if (!/^-[A-Za-z]{2,3}$/.test(word))
-        return false;
-    const body = word.slice(1);
+        return null;
+    const body = caseInsensitive ? word.slice(1).toLowerCase() : word.slice(1);
+    const shortFlags = flags.filter((flag) => flag.length === 2);
     // A cluster is letters only, so whatever follows the program flag is more flags — the
     // program itself is always the next word.
-    return flags.some((flag) => flag.length === 2 && body.includes(flag[1]));
+    //
+    // Scanned by the BODY's own character order, not the table's order: `-ec` must
+    // resolve to `-e` (so a caller deciding whether to decode sees `-e`), not to `-c`
+    // just because `-c` happens to sit first in pwsh's `programBearingWords`. The first
+    // letter in the cluster is the one the invocation leads with.
+    for (const letter of body) {
+        const match = shortFlags.find((flag) => (caseInsensitive ? flag[1].toLowerCase() : flag[1]) === letter);
+        if (match !== undefined)
+            return match;
+    }
+    return null;
 }
 /** Spellings of "the program is on standard input" that look like a file operand. */
 const STDIN_PATHS = new Set(['-', '/dev/stdin', '/dev/fd/0', '/proc/self/fd/0']);
@@ -975,10 +1413,10 @@ function readsProgramFromStdin(words) {
     const bin = stripPath(words[idx]);
     // Interpreters only. awk's one program-from-stdin form is `awk -f -`, already gated as a
     // file flag; every other piped awk reads data, not a program.
-    const spec = INTERPRETERS[bin];
+    const spec = resolveInterpreter(bin);
     if (spec === undefined)
         return false;
-    const flags = spec.flags;
+    const flags = spec.programBearingWords;
     let sawStdinFlag = false;
     for (let j = idx + 1; j < words.length; j++) {
         const word = words[j];
@@ -1074,12 +1512,16 @@ function hasUnreadableProgram(command) {
             return true;
         if (!operandsAreData(words)) {
             for (let j = 0; j < words.length; j++) {
-                const spec = INTERPRETERS[stripPath(unquote(words[j]))];
+                const spec = resolveInterpreter(stripPath(unquote(words[j])));
                 if (spec === undefined || spec.readable)
                     continue;
-                if (isFlagValue(words, j, spec.flags))
+                // Same case-insensitivity as `nestedCommands`'s interpreter loop, and for the
+                // same reason: pwsh/powershell's own parameter binder does not distinguish
+                // `-EC` from `-ec`, so neither should this.
+                const caseInsensitive = spec.programBearingWords.includes('-EncodedCommand');
+                if (isFlagValue(words, j, spec.programBearingWords, caseInsensitive))
                     continue;
-                if (programAfterFlag(words, j, spec.flags) !== null)
+                if (programAfterFlag(words, j, spec.programBearingWords, caseInsensitive, caseInsensitive) !== null)
                     return true;
             }
         }
@@ -1228,4 +1670,4 @@ function classifyOuter(trimmed) {
     }
     return { binary, fullCommand, class: 'safe' };
 }
-export { READ_ONLY_ALLOWLIST, READ_ONLY_SYNTHETIC, isDestructive };
+export { READ_ONLY_ALLOWLIST, READERS, READ_ONLY_SYNTHETIC, isDestructive };

package/build/ssh/connection.js

@@ -7,6 +7,51 @@ import { redactText } from '../guard/redactor.js';
 import { shellSingleQuote } from '../guard/sanitizer.js';
 import { openWithRetry } from './channel-retry.js';
 import { terminateChannel, COULD_NOT_SIGNAL } from './channel-signal.js';
+/**
+ * What this server tells a host it is, on every channel it opens for a command.
+ *
+ * ssh2's `exec()` calls `reqEnv(chan, opts.env)` with no callback, so the request
+ * goes out with `want_reply=0` and the server has nothing to reply to: an
+ * unaccepted name cannot fail the exec. Measured against ssh2 1.17.0
+ * (`lib/client.js:1230` and the `wantReply` line at `:1863`), against Dropbear,
+ * and against Windows OpenSSH on a default config — the command runs, the
+ * variable is simply absent, exit code unchanged.
+ *
+ * **The request is sent to every host, `AcceptEnv` or not.** `AcceptEnv` is the
+ * server's policy about whether it *stores* the pair in the session environment;
+ * it is not a client-side gate, and nothing here consults it. Measured on the
+ * wire against Dropbear, which has no `AcceptEnv` mechanism at all:
+ *
+ *     Outbound: Sending CHANNEL_REQUEST (r:0, env: AI_AGENT=ssh-mcp)
+ *     Outbound: Sending CHANNEL_REQUEST (r:0, exec: echo hi)
+ *
+ * So a host that never opted in still learns that an agent, not a person, is
+ * driving this session. That is a disclosure, and SECURITY.md's threat model
+ * includes a host tailoring its output to inject the model — which is why
+ * `announceAgent = false` exists on the profile. An earlier draft of this comment
+ * called the declaration "inert" on a host that had not opted in; that is true of
+ * the session environment and false of the wire, and the distinction is the whole
+ * reason the profile has a switch.
+ *
+ * Name only, deliberately — no ssh-mcp build number. The transport already
+ * discloses the *library* version in its identification string (ssh2 sends
+ * `SSH-2.0-ssh2js<ver>` and nothing here overrides `ident`), but that is one
+ * library's version across every user of it; a per-build number for this tool
+ * would narrow a hostile host to one deployment.
+ *
+ * `AI_AGENT` is deliberately outside this project's `SSH_MCP_*` namespace. Every
+ * other environment name this repo owns is prefixed; this one is not, because it
+ * is a cross-tool convention read by server-side detectors that do not know or
+ * care which client sent it, and a prefixed name would defeat the only purpose it
+ * has. Renaming it to `SSH_MCP_AGENT` would look like a consistency fix and would
+ * silently break every consumer — hence this paragraph.
+ *
+ * Frozen because it is one object shared by every channel on every connection in
+ * the process. Nothing mutates it today; the first per-command addition to a
+ * channel's `env` would, and would leak across profiles for the life of the
+ * process.
+ */
+const AGENT_ENV = Object.freeze({ AI_AGENT: 'ssh-mcp' });
 /**
  * Stop the command behind `channel`, record why on the span, and return the sentence the
  * rejection should carry.
@@ -74,19 +119,46 @@ export class SSHConnection {
             openShell: async () => {
                 await this.ensureConnected();
                 return new Promise((resolve, reject) => {
-                    this.getClient().shell({ term: 'xterm-256color', cols: 200, rows: 50 }, (err, stream) => (err ? reject(err) : resolve(stream)));
+                    this.getClient().shell({ term: 'xterm-256color', cols: 200, rows: 50 }, 
+                    // Three-argument form, deliberately. ssh2 reclassifies the first
+                    // argument as the options object when it carries `env` or `x11`
+                    // (lib/client.js:1260), so folding the announcement into the window
+                    // object above would silently drop term/cols/rows on every
+                    // interactive session.
+                    this.channelEnv(), (err, stream) => (err ? reject(err) : resolve(stream)));
                 });
             },
             openExec: async (command) => {
                 await this.ensureConnected();
                 return new Promise((resolve, reject) => {
-                    this.getClient().exec(this.applyWorkdir(command), (err, stream) => (err ? reject(err) : resolve(stream)));
+                    this.getClient().exec(this.applyWorkdir(command), this.channelEnv(), (err, stream) => (err ? reject(err) : resolve(stream)));
                 });
             },
             onChannelOpened: () => { this.activeChannels++; },
             onChannelClosed: () => { this.activeChannels--; },
         });
     }
+    /**
+     * The announcement for a channel about to be opened, or nothing.
+     *
+     * One accessor rather than an object literal at each site. The first version of
+     * this feature wrote `{ env: AGENT_ENV }` at two of the three channel-opening
+     * sites and missed `openShell`, which left every command run inside an
+     * interactive session unannounced while the README claimed otherwise. Three
+     * literals give a site the chance to look complete while carrying nothing; a
+     * missing call to this does not.
+     *
+     * Read live, like every other profile field here: the profile object can be
+     * replaced after construction, so an operator clearing `announceAgent` is
+     * honoured on the next channel rather than at the next restart.
+     *
+     * The return type is the intersection both callers accept — `ExecOptions` and
+     * `ShellOptions` declare `env` identically — so one accessor serves `exec()`,
+     * `openExec` and `openShell` without naming either API.
+     */
+    channelEnv() {
+        return this.profile.announceAgent === false ? {} : { env: AGENT_ENV };
+    }
     async ensureConnected() {
         if (this.isConnected())
             return;
@@ -254,7 +326,7 @@ export class SSHConnection {
                     reject(new Error(`Command timed out after ${timeoutMs}ms${note}`));
                 }
             }, timeoutMs);
-            const execOpts = {};
+            const execOpts = { ...this.channelEnv() };
             if (opts.tty || this.profile.tty) {
                 execOpts.pty = { term: 'xterm-256color', cols: 200, rows: 50 };
             }

package/build/tools/audit-effects.js

@@ -0,0 +1,76 @@
+import { createHash } from 'crypto';
+/**
+ * How the transfer tools spell what they are about to do, in the one string the
+ * approver reads, the policy classifies and the audit record keeps.
+ *
+ * Shared because the two tools spelled one concept differently: `sftp-upload-file`
+ * already carried `--overwrite` when it would clobber, while `sftp-upload` — which
+ * always clobbers — carried nothing, so the presence of the flag read as a
+ * difference between the tools rather than between operations (#223). A second
+ * copy of `--overwrite` is one rename away from putting them back out of step, so
+ * there is one.
+ *
+ * `--mode` is *not* at parity and was left that way deliberately. `sftp-upload`
+ * applies 0o644 on a create and never says so, while an absent `--mode=` on
+ * `sftp-upload-file` means 0o600-or-inherited — one absence, two meanings, which
+ * is the same shape of defect #223 describes. Fixing it means deciding what the
+ * effective mode even is on an overwrite (createWriteStream's mode is ignored for
+ * an existing file), which is a separate question from what this module landed for.
+ */
+/**
+ * Spelled once so a rename cannot reach one tool and miss the other.
+ *
+ * Exported rather than reached through `effectSuffix(true)`: `sftp-upload` has no
+ * `overwrite` parameter, so passing a literal `true` to a two-argument helper and
+ * letting the reader constant-fold it needed three lines of comment to say what
+ * one token says.
+ */
+export const OVERWRITE_FLAG = ' --overwrite';
+/** The arguments that change what a transfer does, spelled for policy and the approver. */
+export function effectSuffix(overwrite, mode) {
+    return (overwrite ? OVERWRITE_FLAG : '') + (mode !== undefined ? ` --mode=${mode.toString(8)}` : '');
+}
+/**
+ * 128 bits, because the property claimed here is adversarial, not accidental.
+ *
+ * This was 12 characters on first writing, and 48 truncated bits is ~24 bits of
+ * birthday security — measured, a collision took 12.3 seconds and 10.9M hashes on
+ * one core, producing two 96-byte payloads with the same `--bytes` and the same
+ * digest, hence the byte-identical approved string. `--bytes` costs an attacker
+ * nothing to match, since both candidates can be padded to one length. At 32
+ * characters the same search is 2^64 and not worth describing.
+ *
+ * Length is free on the redaction axis, which is the reason a short digest looked
+ * attractive. The emitted run is `--sha256=<hex>` — `-` and `=` are both in the
+ * redactor's character class, so the run is the flag *plus* the digest, and at any
+ * digest length it is past that scan's 20-character window and is inspected. It
+ * can nonetheless never be redacted: the run draws on 20 distinct symbols, so its
+ * Shannon entropy cannot exceed log2(20) = 4.32 against a 4.5 threshold. Measured
+ * 4.24 at this length. An earlier version of this comment claimed the digest sat
+ * *under* the window; it did not, and reasoning about a length change from that
+ * claim would have started from the wrong mechanism.
+ */
+const DIGEST_CHARS = 32;
+/**
+ * What the approved string says about the bytes, for a tool whose payload is an
+ * argument rather than a named file.
+ *
+ * `sftp-upload` takes its content inline, so unlike the streaming tools there is
+ * no local path in the string to stand for it. Without this, two uploads to the
+ * same destination are the same string — to the approver deciding, to
+ * `ApprovalGrants` keying on it, and to an auditor later asking which one ran.
+ *
+ * Byte length rather than `content.length`: a JS string counts UTF-16 code units,
+ * and the upload writes `Buffer.from(content)` as utf8, so the two disagree on
+ * every multi-byte character. The digest is over the same encoding, which is why
+ * `update(content, 'utf8')` states the encoding rather than relying on a default.
+ *
+ * `string` only, though `SftpClient.upload` also accepts a Buffer: the one tool
+ * that calls this takes its content through `z.string()`, so a Buffer branch here
+ * would be a branch no test could reach honestly. Widen it when a caller needs it,
+ * with the case that needs it.
+ */
+export function payloadSuffix(content) {
+    const digest = createHash('sha256').update(content, 'utf8').digest('hex').slice(0, DIGEST_CHARS);
+    return ` --bytes=${Buffer.byteLength(content, 'utf8')} --sha256=${digest}`;
+}

package/build/tools/descriptions.js

@@ -8,7 +8,7 @@ export const TOOL_DESCRIPTIONS = {
     'read-command': 'Execute a READ-ONLY command from an allowlist (ls, cat, grep, find, stat, df, etc.). This tool does NOT modify the system. Prefer this tool for all read operations. Single-line only: a command containing a line break is refused, so upload a multi-line script with sftp-upload and run it by path.',
     'run-command': 'Execute an arbitrary shell command on the remote server. May modify the system. Commands classified destructive or privileged go through the approval gate; approvalPolicy on the profile decides whether that is a prompt, an automatic allow, or a refusal. Single-line only: a command containing a line break is refused, so upload a multi-line script with sftp-upload and run it by path.',
     'privileged-command': 'Execute a command with sudo elevation. Goes through the approval gate; approvalPolicy on the profile decides whether that is a prompt, an automatic allow, or a refusal. The sudo password is piped via stdin (never visible in process list). Single-line only: a command containing a line break is refused, so upload a multi-line script with sftp-upload and run it by path.',
-    'sftp-upload': 'Upload a file to the remote server via SFTP (secure file transfer, not shell-based).',
+    'sftp-upload': 'Upload a file to the remote server via SFTP (secure file transfer, not shell-based). Replaces an existing file at that path unconditionally — there is no overwrite flag and no way to require a new destination.',
     'sftp-download': 'Download a file from the remote server via SFTP.',
     'sftp-list': 'List a remote directory over SFTP, with a bounded number of entries and a bounded response size. Read-only.',
     'sftp-upload-file': 'Upload a local file to the remote host over SFTP, streaming it without passing the contents through model context. The local file must be inside the transferRoot directory the operator configured; without that setting this tool refuses. Use this for binary or large files; use sftp-upload for short text you already have.',

package/build/tools/file-tools.js

@@ -2,18 +2,27 @@ import { z } from 'zod';
 import { redactText } from '../guard/redactor.js';
 import { remotePathForAudit, sanitizeRemotePath } from '../guard/sanitizer.js';
 import { SftpClient } from '../ssh/sftp.js';
+import { OVERWRITE_FLAG, payloadSuffix } from './audit-effects.js';
 import { TOOL_DESCRIPTIONS as D } from './descriptions.js';
 import { syntheticSuccess, textResult } from './results.js';
 /**
  * SFTP transfer tools.
  *
  * Both paths go through `sanitizeRemotePath`, the same bar the streaming tools
- * hold — for the *path*, which is the only axis brought level here. `sftp-upload`
- * still truncates an existing remote file unconditionally while
- * `sftp-upload-file` refuses unless `overwrite` is passed and spells
- * `--overwrite` into the approved string, and `content` is still absent from that
- * string. Both predate this change and are tracked as #223; saying "the same
- * bar" without this sentence claimed a parity that does not exist. `synthetic: true` skips `sanitizeCommand`, and these two interpolated
+ * hold — for the *path*.
+ *
+ * `sftp-upload` truncates an existing remote file unconditionally where
+ * `sftp-upload-file` refuses unless `overwrite` is passed. What #223 changed is
+ * that the approved string says so: before it named a destination and no effect,
+ * and said nothing at all about the bytes, so two uploads to one path were one
+ * string — one approval, one indistinguishable audit record. The behaviour is
+ * unchanged on purpose: a default of `overwrite: false` would break every caller
+ * that relies on replacement. `--overwrite` is therefore constant here, which does
+ * mean it carries no per-call information — the per-call signal is `--bytes` and
+ * `--sha256`. It stays because the sibling tool omits the flag when it will not
+ * clobber, so an approver comparing the two needs its presence to mean something.
+ *
+ * `synthetic: true` skips `sanitizeCommand`, and these two interpolated
  * the caller's raw string, so nothing refused a bidi override or a zero-width
  * character in a path that is quoted back in the approval prompt and written
  * into a hash-chained audit record — the exact confusion that validator exists
@@ -32,7 +41,19 @@ export function registerFileTools({ server }, pipeline) {
         content: z.string().describe('File content to upload'),
         profile: z.string().optional().describe('Profile name'),
     }, { destructiveHint: true }, async ({ remotePath, content, profile }, extra) => {
-        return runAudited(`sftp:upload ${remotePathForAudit(remotePath)}`, {
+        return runAudited(
+        // Verb, then what the operation does, then the path it does it to — and the
+        // path LAST on purpose. The engine matches `[policy].denylist` against this
+        // whole string, so an operator rule anchored on the path (`authorized_keys$`,
+        // the natural and portable way to write "nothing may write here") keeps
+        // working only while the path ends the line. Measured: with the suffixes
+        // appended after the path instead, that rule silently stops matching and the
+        // refusal degrades to a prompt with no warning. A whole-string rule
+        // (`^sftp:upload /root.*$`) breaks either way — it is coupled to a format
+        // that is ours to change — so the layout is chosen for the form that is not.
+        // `sftp:list` and `sftp:download` carry no flags, so they already read this
+        // way and need no change.
+        `sftp:upload${OVERWRITE_FLAG}${payloadSuffix(content)} ${remotePathForAudit(remotePath)}`, {
             toolName: 'sftp-upload',
             failureClass: 'destructive',
             profile,
@@ -43,10 +64,8 @@ export function registerFileTools({ server }, pipeline) {
             await new SftpClient(rt.conn).upload({ remotePath, content });
             return {
                 audited: syntheticSuccess(rt.profileName),
-                // Byte count, not string length: `content` is a JS string, so
-                // `.length` counts UTF-16 code units and under-reports every
-                // multi-byte character. SftpClient.upload writes Buffer.from(content),
-                // which is utf8, so this is exactly what lands on the remote side.
+                // utf8 bytes, matching the count the approved string already carries —
+                // see `payloadSuffix` in audit-effects.ts for why `.length` is wrong.
                 output: textResult(`Uploaded ${Buffer.byteLength(content, 'utf8')} bytes to ${remotePath}`),
             };
         });

package/build/tools/transfer-tools.js

@@ -3,6 +3,7 @@ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { redactText } from '../guard/redactor.js';
 import { remotePathForAudit, sanitizeRemotePath } from '../guard/sanitizer.js';
 import { SftpClient } from '../ssh/sftp.js';
+import { effectSuffix } from './audit-effects.js';
 import { TOOL_DESCRIPTIONS as D } from './descriptions.js';
 import { createLocalDownload, localFileForRead, localPathForAudit, } from './local-path.js';
 import { syntheticSuccess, textResult } from './results.js';
@@ -142,10 +143,6 @@ export function checkMode(mode) {
     }
     return mode;
 }
-/** The arguments that change what a transfer does, spelled for policy and the approver. */
-function effectSuffix(overwrite, mode) {
-    return (overwrite ? ' --overwrite' : '') + (mode !== undefined ? ` --mode=${mode.toString(8)}` : '');
-}
 /**
  * What the audit record adds once the local path has been resolved.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
   "mcpName": "io.github.tufantunc/ssh-mcp",
   "type": "module",