ssh-mcp 2.19.0 → 2.19.1

package/README.md

@@ -593,6 +593,14 @@ read-only only with the options and operands its grammar lists; `--foo` is not a
 there. ``), so the caller can see which spelling of the same command still works. See
 [SECURITY.md](./SECURITY.md) for the residual risks this leaves open.
 
+A reader also falls to `safe` when its command carries a shell metacharacter — `;` `&` `|`
+`<` `>` `` ` `` `$` `(` `)` `{` `}`, a newline or a carriage return — quoted or not, because
+the allowlist vouches for the binary, never for what a shell might do with the rest of the
+line. The refusal names the first such character. For `sftp-list` and `sftp-download` it is
+in the remote path, so `/srv/backup(old)` is refused for a `readOnly` profile with
+`` The remote path contains `(`, which counts as a shell metacharacter here, so `sftp:list`
+is read-only only for a path without one. ``
+
 A separate **forbidden** list is never allowed, whatever the role or approval
 policy: `rm -rf /`, `mkfs`, `dd of=/dev/`, `shutdown`, `curl|sh`, fork bombs,
 writes naming `/etc/cron`, `/etc/systemd` or any user's `authorized_keys`,

package/build/policy/classifier.js

@@ -2428,9 +2428,10 @@ function classifyCommandInDialect(command, depth, dialect) {
         if (CLASS_RANK[parsed.class] > CLASS_RANK[highest.class])
             highest = parsed;
     }
-    // `readOnlyRejection` only ever describes the outer command's own grammar
-    // rejection, and only means anything when that is also what decided the
-    // final class. `highest === outer` (reference equality) is exactly that
+    // `readOnlyRejection` only ever describes why the outer command's reader was
+    // refused read-only — a grammar rejection or a shell metacharacter, see
+    // `ReadOnlyRejection` — and only means anything when that is also what decided
+    // the final class. `highest === outer` (reference equality) is exactly that
     // condition: the synthetic floor and the nested-command loop above only
     // ever replace `highest` with something of strictly higher rank than
     // `outer`'s, so if either one fired, `highest` is no longer `outer` and the
@@ -2472,8 +2473,20 @@ function classifyOuter(trimmed, dialect) {
     const twoWordPrefix = words.slice(0, 2).join(' ');
     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' };
+        // Whichever key matched decides both which entry answers and how many
+        // leading words are the command name rather than an argument: a two-word
+        // entry's grammar reads words[2..], a one-word entry's reads words[1..]. An
+        // SFTP verb's two-word prefix is never a key, so it is named by itself.
+        const matchedTwoWord = READ_ONLY_ALLOWLIST.has(twoWordPrefix);
+        const readerName = matchedTwoWord ? twoWordPrefix : binary;
+        const metacharacter = SHELL_CONTROL_CHARS.exec(trimmed);
+        if (metacharacter) {
+            return {
+                binary,
+                fullCommand,
+                class: 'safe',
+                readOnlyRejection: { binary: readerName, word: metacharacter[0], cause: 'shell-metacharacter' },
+            };
         }
         // The SFTP verbs are synthesised by the tool layer, never typed by a caller,
         // so there is no argv for a grammar to read — READ_ONLY_SYNTHETIC stays
@@ -2481,11 +2494,6 @@ function classifyOuter(trimmed, dialect) {
         if (READ_ONLY_SYNTHETIC.has(binary)) {
             return { binary, fullCommand, class: 'read-only' };
         }
-        // Whichever key matched decides both which entry answers and how many
-        // leading words are the command name rather than an argument: a two-word
-        // entry's grammar reads words[2..], a one-word entry's reads words[1..].
-        const matchedTwoWord = READ_ONLY_ALLOWLIST.has(twoWordPrefix);
-        const readerName = matchedTwoWord ? twoWordPrefix : binary;
         const entry = READERS[readerName];
         const argWords = words.slice(matchedTwoWord ? 2 : 1);
         // An unquoted glob word is not a word this grammar can vouch for: the
@@ -2501,7 +2509,7 @@ function classifyOuter(trimmed, dialect) {
                     binary,
                     fullCommand,
                     class: 'safe',
-                    readOnlyRejection: { binary: readerName, word: globWord },
+                    readOnlyRejection: { binary: readerName, word: globWord, cause: 'grammar' },
                 };
             }
         }
@@ -2511,7 +2519,7 @@ function classifyOuter(trimmed, dialect) {
                 binary,
                 fullCommand,
                 class: 'safe',
-                readOnlyRejection: { binary: readerName, word: match.word },
+                readOnlyRejection: { binary: readerName, word: match.word, cause: 'grammar' },
             };
         }
         return { binary, fullCommand, class: 'read-only' };
@@ -2519,17 +2527,40 @@ function classifyOuter(trimmed, dialect) {
     return { binary, fullCommand, class: 'safe' };
 }
 /**
- * The sentence a refusal appends when it carries a `readOnlyRejection`, worded
- * so the reason names the binary that would have qualified and the argv word
- * that cost it: "is not accepted there" rather than "is not one of them",
- * because most rejections are operand rules (`hostname NAME`, `sort /data`) or
- * a listed value flag missing its value, where "is not one of them" would be
- * false — it may be a perfectly good flag name, just not one bare or in this
- * position. One function so the engine's role-binding denial and
- * `read-command`'s `enforceClass` refusal never drift into two spellings of
- * the same sentence.
+ * The sentence a refusal appends when it carries a `readOnlyRejection`, in one of
+ * two shapes chosen by its `cause`. Both name the reader that would have qualified
+ * and what cost it the class.
+ *
+ * - `grammar`: names the argv word, as "is not accepted there" rather than "is not
+ *   one of them", because most rejections are operand rules (`hostname NAME`,
+ *   `sort /data`) or a listed value flag missing its value, where "is not one of
+ *   them" would be false — it may be a perfectly good flag name, just not one bare
+ *   or in this position.
+ * - `shell-metacharacter`: names the character, and for the SFTP verbs says it is
+ *   in the remote path (#224).
+ *
+ * One function so the engine's role-binding denial and `read-command`'s
+ * `enforceClass` refusal never drift into two spellings of the same sentence.
  */
 function formatReadOnlyRejection(rejection) {
+    if (rejection.cause === 'shell-metacharacter') {
+        // `\n` and `\r` are in SHELL_CONTROL_CHARS, and quoted raw they would break the
+        // sentence across lines or render as nothing. A backtick is in it too, and inside
+        // single backticks it would print as three in a row; double backticks with
+        // padding is Markdown's own way to quote one.
+        const char = rejection.word.replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+        const quoted = char === '`' ? '`` ` ``' : `\`${char}\``;
+        // The SFTP verbs' operand is a path the tool layer built the command from, so the
+        // path is what the caller can change — not "the command", which they never typed.
+        // The verb is named as the audit record spells it (`sftp:list`), not as the tool
+        // (`sftp-list`), so the refusal and the record it is filed under read the same.
+        if (READ_ONLY_SYNTHETIC.has(rejection.binary)) {
+            return `The remote path contains ${quoted}, which counts as a shell metacharacter here, ` +
+                `so \`${rejection.binary}\` is read-only only for a path without one.`;
+        }
+        return `\`${rejection.binary}\` is read-only only when the command contains no shell metacharacter; ` +
+            `${quoted} is one.`;
+    }
     // The rejected word can be the empty string — a quoted empty operand
     // (`hostname ""`) — and two bare backticks would render as a blank where
     // the word that cost the class should be. `""` is the shell's own spelling

package/build/policy/engine.js

@@ -453,9 +453,9 @@ export class PolicyEngine {
             }
         }
         // A `safe` command refused here is often not a hard "no" — it is one
-        // argv word away from `read-only`, and without this the reader concludes
-        // the binary is forbidden outright and never learns which spelling would
-        // have worked.
+        // spelling away from `read-only` (an argv word the grammar refused, or a
+        // shell metacharacter), and without this the reader concludes the binary is
+        // forbidden outright and never learns which spelling would have worked.
         if (parsed.readOnlyRejection) {
             reason += ` ${formatReadOnlyRejection(parsed.readOnlyRejection)}`;
         }

package/build/tools/pipeline.js

@@ -170,11 +170,12 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
             const { conn, evaluation, approver } = await checkPolicyAndApprove(effective, profileName, opts.toolName, opts.resource);
             state.evaluation = evaluation;
             if (opts.enforceClass && evaluation.commandClass !== opts.enforceClass) {
-                // A command that fell to `safe` because a reader's grammar rejected one
-                // of its argv words is one spelling away from the class this tool
-                // demands — say which word, or the caller only learns that the tool
-                // refused it, not why the reader that ran the exact same binary
-                // would not have.
+                // A command that fell to `safe` because a reader was refused read-only —
+                // its grammar rejected an argv word, or the command carries a shell
+                // metacharacter — is one spelling away from the class this tool demands.
+                // Say which word or character, or the caller only learns that the tool
+                // refused it, not why the reader that ran the exact same binary would
+                // not have.
                 const rejectionSuffix = evaluation.readOnlyRejection
                     ? ` ${formatReadOnlyRejection(evaluation.readOnlyRejection)}`
                     : '';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.19.0",
+  "version": "2.19.1",
   "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",
@@ -14,7 +14,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.test.json",
     "inspect": "npx @modelcontextprotocol/inspector node build/index.js",
     "changeset": "changeset",
-    "version": "changeset version && node scripts/sync-server-json.mjs",
+    "version": "changeset version && node scripts/sync-server-json.mjs && node scripts/sync-lockfile-version.mjs",
     "test": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run",
     "test:unit": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run test/unit/ test/property/",
     "test:integration": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run test/integration/",
@@ -27,7 +27,7 @@
     "build"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
     "@opentelemetry/resources": "^2.9.0",