ssh-mcp 2.9.1 → 2.11.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/guard/sanitizer.js

@@ -1,24 +1,42 @@
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+// The classifier's own resolver, not a second one. See SYNTHETIC_NAMESPACE below.
+import { extractBinary } from '../policy/classifier.js';
 /** Every character a shell would read as the end of one command and the start of another. */
 const LINE_BREAKS = /[\r\n\u2028\u2029]/;
 const NUL = /\u0000/;
 /**
- * Validate a caller-supplied command.
+ * Verbs this server builds for itself, which a caller may therefore not type.
  *
- * A line break is refused, not removed. The constraint itself is not negotiable
- * — a newline inside `command` would let a second command ride along past a
- * classifier that parsed only the first, which is #44 — but an earlier version
- * enforced it by replacing the break with a space, and *that* is the part worth
- * changing. The caller got no error and a different command than it asked for:
- * two lines joined, so `ls\necho x` ran `ls echo x`; or a `#` comment in a
- * `python3 -c` body pulled onto the same line, commenting out everything after
- * it. Sometimes that raises. Sometimes it runs and quietly does half the work,
- * which is the failure mode worth removing (#198).
+ * `classifyOuter` cannot tell a synthetic string from one a caller typed — both
+ * arrive as text. So the moment `sftp:list` was given a class, `read-command`
+ * accepted it as a command word too: measured, a `readOnly` viewer could send
+ * `read-command "sftp:list /tmp sudo id"` and the classifier answered
+ * `read-only`, the gate allowed it, and `exec` ran it. On main the same string
+ * was `safe` and refused.
  *
- * Trailing and leading breaks are trimmed rather than refused. A client that
- * appends a newline works today, refusing it would break that for no gain, and
- * a break at either end cannot join two commands.
+ * The audit log had the same problem from the other side: a forged record was
+ * identical in every field to one the tool itself produced.
+ *
+ * `sanitizeCommand` is the right place because it runs, by construction, only
+ * for commands that did *not* come from us — `runAudited` skips it when
+ * `synthetic: true`.
+ *
+ * Tested against `extractBinary`, the classifier's own resolver, rather than
+ * against a first-token helper of this file's own. A private one was written
+ * first and drifted immediately: `extractBinary` strips a leading `-c ` and the
+ * leading privilege prefixes, which the helper did not, so
+ * `read-command "-c sftp:download /etc/shadow"` resolved to binary
+ * `sftp:download`, classified `read-only`, was allowed on a profile that denies
+ * it on main, and executed. Two resolvers answering one question is the bug;
+ * asking the one that decides is the fix.
+ *
+ * Scope of the guarantee, stated narrowly on purpose: an `sftp:*` or `session:*`
+ * audit record is provably tool-generated. `signal-process` synthesises
+ * `kill -TERM <pid>`, which is outside this namespace and cannot be reserved —
+ * `kill` is a binary a caller may legitimately need — so a record of that shape
+ * is not covered.
  */
+const SYNTHETIC_NAMESPACE = /^(?:sftp|session):/;
 export function sanitizeCommand(command, maxChars) {
     if (typeof command !== 'string') {
         throw new McpError(ErrorCode.InvalidParams, 'Command must be a string');
@@ -36,6 +54,11 @@ export function sanitizeCommand(command, maxChars) {
     if (NUL.test(cleaned)) {
         throw new McpError(ErrorCode.InvalidParams, 'Command cannot contain a null byte');
     }
+    if (SYNTHETIC_NAMESPACE.test(extractBinary(cleaned))) {
+        throw new McpError(ErrorCode.InvalidParams, 'Command cannot begin with "sftp:" or "session:": that namespace is reserved for the ' +
+            'strings this server builds for its own tools, and the classifier cannot tell a typed ' +
+            'one from a generated one. Use the sftp-* and *-session tools instead.');
+    }
     if (Number.isFinite(maxChars) && cleaned.length > maxChars) {
         throw new McpError(ErrorCode.InvalidParams, `Command is too long (max ${maxChars} characters)`);
     }
@@ -45,23 +68,35 @@ export function sanitizeCommand(command, maxChars) {
  * Every character that could make the audited string, the approval prompt and
  * the path actually used disagree with each other.
  *
- * C0 and C1 controls, the Unicode line separators, the whole Bidi_Control set
- * (U+061C, U+200E, U+200F, U+202A-U+202E, U+2066-U+2069) and the zero-width
- * formatters. A remote path is quoted back to a human in the approval prompt
- * and written into a hash-chained audit record, so a name carrying a
- * right-to-left override renders as one path and transfers another, and one
- * carrying a zero-width space renders identically to a different path.
+ * C0 and C1 controls, the Unicode line separators, the Bidi_Control set
+ * (U+061C, U+200E, U+200F, U+202A-U+202E, U+2066-U+2069), and the zero-width
+ * characters that carry no meaning of their own. A remote path is quoted back to
+ * a human in the approval prompt and written into a hash-chained audit record,
+ * so a name carrying a right-to-left override renders as one path and transfers
+ * another, and one carrying a zero-width space renders identically to a
+ * different path.
  *
  * An earlier version stopped at the overrides and isolates, which left the
  * marks that reorder *neutral* characters — and a path is mostly neutrals:
  * slashes, dots, hyphens and digits.
  *
+ * **U+200C and U+200D are deliberately not here**, though they sit inside the
+ * range an earlier version of this class swept up. ZWNJ and ZWJ are invisible
+ * but not meaningless: they are orthographically required in Persian and in the
+ * Indic scripts, and structural inside an emoji sequence. Refusing them rejected
+ * real filenames — measured, `/srv/mi<ZWNJ>ravad.txt` is a name a filesystem
+ * accepts and a user types. The spoofing argument does not reach them either,
+ * since it rests on two *different* paths rendering identically, and this
+ * codebase already accepts that for homoglyphs (Cyrillic а against Latin a),
+ * which no character class can catch. Refusing the joiners while accepting those
+ * was inconsistent and cost legitimate input.
+ *
  * Exported because `tools/local-path.ts` asks the same question of the local
  * half. The two *functions* are split for a real reason — that one has to stat
  * and this one must not — but the character class is one threat model, and two
  * copies of it drift the first time a codepoint is added.
  */
-export const PATH_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/;
+export const PATH_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b\u200e\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/;
 /** Longer than any path a real filesystem accepts, so this bounds nothing legitimate. */
 const MAX_REMOTE_PATH_CHARS = 4096;
 /** What the audit record calls a path that never passed validation. */

package/build/policy/classifier.js

@@ -47,6 +47,36 @@ const READ_ONLY_ALLOWLIST = new Set([
 // Residual risk kept on purpose: dig/nslookup/host/ping/traceroute can leak
 // small amounts of data through DNS/ICMP queries. They cannot modify the host,
 // so they stay read-only; tighten them via profile policy if egress matters.
+/**
+ * The SFTP read verbs, which the tool layer synthesises rather than a caller typing.
+ *
+ * A second set rather than two more entries in READ_ONLY_ALLOWLIST, and the
+ * reason is that that Set is dual-purpose: `operandsAreData` reads it too, to
+ * decide whether a segment's operands are data rather than commands. Putting
+ * these verbs there silenced the carrier scan for them — measured,
+ * `sftp:list /tmp sh -c 'sudo id'` fell from `privileged` to `read-only`,
+ * because `nestedCommands` stopped extracting the `sh -c` payload. That is the
+ * one carrier form carrying no character from SHELL_CONTROL_CHARS, i.e. exactly
+ * the form the scan is load-bearing for.
+ *
+ * The suppression buys nothing here anyway. It exists so `grep python3 -c file`
+ * is not read as invoking python; these verbs take a path nobody parses, so
+ * there is no false positive to suppress.
+ *
+ * Why they are lowered at all: both carry `readOnlyHint: true`, the README marks
+ * both read-only, `sftp-list`'s description ends "Read-only." — and `safe` is
+ * refused outright by a `readOnly` profile, so the one profile class the
+ * annotation targets was the one that could not run them (#217).
+ * (`sftp-download`'s description makes no read-only claim; an earlier version of
+ * this paragraph said both did, which is the overstatement this file keeps
+ * catching.) The lowering grants that
+ * profile nothing new: `cat /etc/shadow` and `ls /root` are already `read-only`,
+ * so the authority to read any file the SSH user can read is already held.
+ *
+ * `sftp:upload`, `sftp:upload-file` and `sftp:download-file` stay out — the
+ * first two write on the remote host, the third inside the transfer root.
+ */
+const READ_ONLY_SYNTHETIC = new Set(['sftp:list', 'sftp:download']);
 /**
  * Commands that are never allowed, whatever the role or approval policy.
  *
@@ -1091,14 +1121,22 @@ function hasUnnameableCommand(command) {
  * `~/.ssh/authorized_keys` without touching a shell. Opening a session is the same
  * argument, since it hands over an interactive shell.
  *
- * `sftp:download`, `sftp:list` and `session:close` are deliberately absent. Each would
- * move *down* from `safe` — download and list to `read-only`, matching their
- * `readOnlyHint`, and close being a release rather than an acquisition. Lowering a class
- * is a widening, and a security release is the wrong place for one; they keep the class
- * they have today. `sftp:list` is worth spelling out because it is new: a `read-only`
- * entry for it would also be inert, since the floor below can only raise, and the effect
- * anyone reaching for it actually wants — letting a `viewer` list a remote directory — is
- * a binding change, not a classification one.
+ * `session:close` is deliberately absent: it is a release rather than an acquisition, and
+ * no tool advertises it as a read.
+ *
+ * `sftp:download` and `sftp:list` are absent for a different reason now. They *are*
+ * lowered to `read-only` — by `READ_ONLY_SYNTHETIC` near the top of this file — because
+ * both tools advertise `readOnlyHint: true` and `safe` is refused outright by a `readOnly`
+ * profile, so the one profile class the annotation targeted was the one that could not run
+ * them (#217). They cannot be lowered *here*, because this table is a floor and a floor
+ * can only raise; an entry would be inert. That inertness is the trap worth keeping
+ * written down — it produced two wrong attempts during #212.
+ *
+ * What this paragraph used to say, and what was wrong with it: that the effect anyone
+ * wants from lowering `sftp:list` — letting a `viewer` list a remote directory — is "a
+ * binding change, not a classification one". It is a classification one, because the tool
+ * ships an annotation and a description that both claim read-only, and a policy that
+ * disagreed with them was the defect rather than the binding.
  *
  * `sftp:upload-file` and `sftp:download-file` are `destructive` because each writes a
  * file: the first on the remote host, the second inside the operator's transfer root.
@@ -1181,7 +1219,8 @@ function classifyOuter(trimmed) {
         return { binary, fullCommand, class: 'destructive' };
     }
     const twoWordPrefix = (tokenizeSegments(fullCommand)[0] ?? []).slice(0, 2).join(' ');
-    if (READ_ONLY_ALLOWLIST.has(binary) || READ_ONLY_ALLOWLIST.has(twoWordPrefix)) {
+    if (READ_ONLY_ALLOWLIST.has(binary) || READ_ONLY_ALLOWLIST.has(twoWordPrefix)
+        || READ_ONLY_SYNTHETIC.has(binary)) {
         if (SHELL_CONTROL_CHARS.test(trimmed)) {
             return { binary, fullCommand, class: 'safe' };
         }
@@ -1189,4 +1228,4 @@ function classifyOuter(trimmed) {
     }
     return { binary, fullCommand, class: 'safe' };
 }
-export { READ_ONLY_ALLOWLIST, isDestructive };
+export { READ_ONLY_ALLOWLIST, 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

@@ -1,35 +1,88 @@
 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. */
+/**
+ * SFTP transfer tools.
+ *
+ * Both paths go through `sanitizeRemotePath`, the same bar the streaming tools
+ * 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
+ * to stop. The check runs as a `preCheck`, inside the pipeline's try, so a
+ * refused call still leaves an audit record.
+ *
+ * Pre-existing, and reachable before only by roles holding `safe`; lowering
+ * `sftp:download` to `read-only` (#217) is what would have opened it to every
+ * `readOnly` profile, so it is closed here rather than after.
+ */
 export function registerFileTools({ server }, pipeline) {
     const { runAudited } = pipeline;
     // ─── sftp-upload ───────────────────────────────────────────────────────
     server.tool('sftp-upload', D["sftp-upload"], {
-        remotePath: z.string().describe('Remote file path'),
+        remotePath: z.string().describe('Remote file path. No leading or trailing whitespace, and no control, bidirectional or zero-width characters: the approval prompt and the audit record quote this path back.'),
         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 ${remotePath}`, { toolName: 'sftp-upload', failureClass: 'destructive', profile, extra, synthetic: true }, async (rt) => {
+        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,
+            extra,
+            synthetic: true,
+            preCheck: () => { sanitizeRemotePath(remotePath); },
+        }, async (rt) => {
             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}`),
             };
         });
     });
     // ─── sftp-download ─────────────────────────────────────────────────────
     server.tool('sftp-download', D["sftp-download"], {
-        remotePath: z.string().describe('Remote file path to download'),
+        remotePath: z.string().describe('Remote file path. No leading or trailing whitespace, and no control, bidirectional or zero-width characters: the approval prompt and the audit record quote this path back.'),
         profile: z.string().optional().describe('Profile name'),
     }, { readOnlyHint: true }, async ({ remotePath, profile }, extra) => {
-        return runAudited(`sftp:download ${remotePath}`, { toolName: 'sftp-download', failureClass: 'read-only', profile, extra, synthetic: true }, async (rt) => {
+        return runAudited(`sftp:download ${remotePathForAudit(remotePath)}`, {
+            toolName: 'sftp-download',
+            failureClass: 'read-only',
+            profile,
+            extra,
+            synthetic: true,
+            preCheck: () => { sanitizeRemotePath(remotePath); },
+        }, async (rt) => {
             const data = await new SftpClient(rt.conn).download({ remotePath });
             return {
                 audited: syntheticSuccess(rt.profileName),

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.
  *
@@ -199,7 +196,7 @@ export function registerTransferTools({ server, localPath }, pipeline) {
     const ctx = localPath ?? { transferRoot: undefined };
     // ─── sftp-list ─────────────────────────────────────────────────────────
     server.tool('sftp-list', D['sftp-list'], {
-        remotePath: z.string().describe('Remote directory to list'),
+        remotePath: z.string().describe('Remote directory to list. No leading or trailing whitespace, and no control, bidirectional or zero-width characters.'),
         maxEntries: z.number().int().min(1).max(MAX_LIST_ENTRIES).optional()
             .describe(`Max entries to return (default ${DEFAULT_LIST_ENTRIES}, hard cap ${MAX_LIST_ENTRIES})`),
         profile: z.string().optional().describe('Profile name'),
@@ -237,7 +234,7 @@ export function registerTransferTools({ server, localPath }, pipeline) {
     // ─── sftp-upload-file ──────────────────────────────────────────────────
     server.tool('sftp-upload-file', D['sftp-upload-file'], {
         localPath: z.string().describe('Local file to upload, inside defaults.transferRoot'),
-        remotePath: z.string().describe('Remote destination path'),
+        remotePath: z.string().describe('Remote destination path. No leading or trailing whitespace, and no control, bidirectional or zero-width characters.'),
         overwrite: z.boolean().optional().describe('Replace an existing remote file (default false)'),
         // The range is deliberately NOT declared here, only in `checkMode`. The SDK
         // validates this schema before the handler runs, so a zod bound refuses a
@@ -296,7 +293,7 @@ export function registerTransferTools({ server, localPath }, pipeline) {
     });
     // ─── sftp-download-file ────────────────────────────────────────────────
     server.tool('sftp-download-file', D['sftp-download-file'], {
-        remotePath: z.string().describe('Remote file to download'),
+        remotePath: z.string().describe('Remote file to download. No leading or trailing whitespace, and no control, bidirectional or zero-width characters.'),
         localPath: z.string().describe('Local destination, inside defaults.transferRoot'),
         overwrite: z.boolean().optional().describe('Replace an existing local file (default false)'),
         profile: z.string().optional().describe('Profile name'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.9.1",
+  "version": "2.11.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",