ssh-mcp 2.13.0 → 2.15.0

package/README.md

@@ -4,6 +4,7 @@
 [![Downloads](https://img.shields.io/npm/dm/ssh-mcp)](https://www.npmjs.com/package/ssh-mcp)
 [![CI](https://github.com/tufantunc/ssh-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tufantunc/ssh-mcp/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/tufantunc/ssh-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/tufantunc/ssh-mcp)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15082/badge)](https://www.bestpractices.dev/projects/15082)
 [![codecov](https://codecov.io/gh/tufantunc/ssh-mcp/graph/badge.svg?branch=main)](https://codecov.io/gh/tufantunc/ssh-mcp)
 [![License](https://img.shields.io/github/license/tufantunc/ssh-mcp)](./LICENSE)
 [![GitHub issues](https://img.shields.io/github/issues/tufantunc/ssh-mcp)](https://github.com/tufantunc/ssh-mcp/issues)
@@ -763,7 +764,7 @@ ssh-mcp --transport=http --httpPort=3000 --bearerToken=secret --rateLimit=60
 | `--bearerToken` | required | Bearer token for authentication (all routes except `GET /health`) |
 | `--httpPort` | 3000 | HTTP listen port |
 | `--httpHost` | 127.0.0.1 | Bind address |
-| `--rateLimit` | 0 (off) | Max requests per minute (0 = unlimited) |
+| `--rateLimit` | 0 (off) | Max authenticated requests per minute, per client (0 = unlimited) |
 | `--authFailureLimit` | 10 | Failed bearer-auth attempts allowed per client per minute (0 = off) |
 | `--trustProxy` | false | Read the client address from `X-Forwarded-For`, but only when the peer is the proxy — bare means a loopback peer |
 | `--trustedProxies` | — | Comma-separated peer addresses allowed to send `X-Forwarded-For`. Empty means loopback only |
@@ -776,7 +777,13 @@ case of a config bind mount that silently did not attach: the server binds the p
 refuses every tool call. `GET /status` carries the profile list itself and stays behind the
 bearer token.
 
-When rate limit is exceeded, the server returns HTTP 429 with `Retry-After` header and a JSON-RPC error body so MCP clients can handle it gracefully.
+`--rateLimit` is a budget per client, keyed the same way as the failed-auth budget below,
+and every authenticated request spends from it: `POST /` and the rest of the MCP route,
+`GET /status`, and an authenticated request to a path that does not exist. `GET /health`
+never does. A wrong token never does either, so unauthenticated traffic cannot spend a
+working client's budget. When a client's budget is spent the server returns HTTP 429 with
+a JSON-RPC error body, and `Retry-After` gives the seconds until that client's next request
+will be accepted.
 
 Failed authentication is throttled separately, and on by default. `--rateLimit` never saw a
 wrong bearer token, because the auth check answers before the limiter is reached — so
@@ -784,18 +791,20 @@ guessing ran at network speed. `--authFailureLimit` gives each client its own sm
 spent only on a 401; a correct token never consumes from it, so a working client never
 throttles itself. Once an address has spent its budget every request from it waits,
 including one with the right token — that is deliberate, since answering the guess would
-otherwise tell the caller which token was right. Clients are told apart by socket address. **Behind a
-reverse proxy that means every client shares one budget**, so set `--trustProxy` when the
-proxy is yours — the server prints a warning the first time it sees `X-Forwarded-For`
-without it. `--trustProxy` takes the *rightmost* `X-Forwarded-For` entry, which is the hop
-the proxy itself appended; everything to its left came from the client, so reading the
-leftmost would let a client choose its own budget or spend a victim's. That only holds if a
-proxy actually appended the entry, so the header is read **only when the peer is the
-proxy** — bare `--trustProxy` means a loopback peer, which is the deployment above; name a
-proxy elsewhere with `--trustedProxies`. When the header cannot be read as an address, or
-the peer is not trusted, the server falls back to the socket address and says so once, so
-a flag that is not taking effect is not silent. One trusted hop is assumed. A malformed `--authFailureLimit` is refused at startup rather than silently
-disabling the check; only `0` turns it off.
+otherwise tell the caller which token was right. Clients are told apart by socket address,
+for this budget and for `--rateLimit` alike. **Behind a reverse proxy that means every
+client shares one of each**, so set `--trustProxy` when the proxy is yours — the server
+prints a warning the first time it sees `X-Forwarded-For` without it. `--trustProxy` takes
+the *rightmost* `X-Forwarded-For` entry, which is the hop the proxy itself appended;
+everything to its left came from the client, so reading the leftmost would let a client
+choose its own budget or spend a victim's. That only holds if a proxy actually appended
+the entry, so the header is read **only when the peer is the proxy** — bare `--trustProxy`
+means a loopback peer, which is the deployment above; name a proxy elsewhere with
+`--trustedProxies`. When the header cannot be read as an address, or the peer is not
+trusted, the server falls back to the socket address and says so once, so a flag that is
+not taking effect is not silent. One trusted hop is assumed. A malformed
+`--authFailureLimit` is refused at startup rather than silently disabling the check; only
+`0` turns it off.
 
 **Always terminate TLS at a reverse proxy** (Caddy/nginx). The server listens on `127.0.0.1` only.
 
@@ -845,7 +854,7 @@ Secrets are **never** passed as CLI arguments.
 | `--httpPort` | 3000 | HTTP transport port |
 | `--httpHost` | 127.0.0.1 | HTTP bind address |
 | `--bearerToken` | — | Bearer token for HTTP transport auth (required for `--transport=http`) |
-| `--rateLimit` | 0 | HTTP requests per minute on the MCP route (0 = unlimited) |
+| `--rateLimit` | 0 | Max authenticated requests per minute, per client (0 = unlimited) |
 | `--authFailureLimit` | 10 | Failed bearer-auth attempts allowed per client per minute (0 = off) |
 | `--trustProxy` | false | Read the client address from `X-Forwarded-For`, but only when the peer is the proxy — bare means a loopback peer |
 | `--trustedProxies` | — | Comma-separated peer addresses allowed to send `X-Forwarded-For`. Empty means loopback only |

package/build/policy/classifier.js

@@ -41,7 +41,7 @@ const SHELL_CONTROL_CHARS = /[;&|<>`$(){}\n\r]/;
  * branch, which only runs when the command words matched a READERS key
  * exactly — never sees one either.
  */
-function firstUnquotedGlobWord(command, honorQuotes = true) {
+function firstUnquotedGlobWord(command, honorQuotes = true, dialect = 'posix') {
     let quote = null;
     let escaped = false;
     let word = '';
@@ -56,7 +56,7 @@ function firstUnquotedGlobWord(command, honorQuotes = true) {
         if (quote) {
             // Backslash is literal inside single quotes; inside double quotes it
             // escapes — the same distinction the tokeniser makes.
-            if (ch === '\\' && quote === '"') {
+            if (dialect === 'posix' && ch === '\\' && quote === '"') {
                 escaped = true;
                 continue;
             }
@@ -66,7 +66,7 @@ function firstUnquotedGlobWord(command, honorQuotes = true) {
                 word += ch;
             continue;
         }
-        if (ch === '\\') {
+        if (dialect === 'posix' && ch === '\\') {
             escaped = true;
             continue;
         }
@@ -90,7 +90,7 @@ function firstUnquotedGlobWord(command, honorQuotes = true) {
     // `tokenizeSegmentsDetailed`). Judge it the same way here: in that reading
     // the glob character is unquoted.
     if (honorQuotes && quote !== null)
-        return firstUnquotedGlobWord(command, false);
+        return firstUnquotedGlobWord(command, false, dialect);
     return globInWord ? word : null;
 }
 /**
@@ -822,9 +822,11 @@ const MAX_NESTING_DEPTH = 8;
  * Not a shell parser. Variable expansion, arithmetic and here-documents are out of scope —
  * `hasUnnameableCommand` is what refuses a command word this cannot resolve.
  */
-function tokenizeSegments(command) {
-    return tokenizeSegmentsDetailed(command).map((segment) => segment.words);
+function tokenizeSegments(command, dialect = 'posix') {
+    return tokenizeSegmentsDetailed(command, true, dialect).map((segment) => segment.words);
 }
+/** Inside double quotes, the characters POSIX lets a backslash escape. */
+const DOUBLE_QUOTE_ESCAPABLE = new Set(['$', '`', '"', '\\', '\n']);
 /**
  * The same split, keeping the separator that introduced each segment.
  *
@@ -832,7 +834,7 @@ function tokenizeSegments(command) {
  * and `&` merely sequence, and a rule about pipes must not fire on a rule about sequences.
  * Deriving both views from one tokeniser is what stops the two from drifting apart.
  */
-function tokenizeSegmentsDetailed(command, honorQuotes = true) {
+function tokenizeSegmentsDetailed(command, honorQuotes = true, dialect = 'posix') {
     const segments = [];
     let pending = '';
     let words = [];
@@ -867,7 +869,8 @@ function tokenizeSegmentsDetailed(command, honorQuotes = true) {
         words = [];
         pending = sep;
     };
-    for (const ch of command) {
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
         if (escaped) {
             // A backslash quotes the next character, so `\reboot` runs reboot. Keeping the
             // character and dropping the backslash is what the shell does.
@@ -877,8 +880,18 @@ function tokenizeSegmentsDetailed(command, honorQuotes = true) {
         }
         if (quote) {
             // Backslash is literal inside single quotes; inside double quotes it escapes.
-            if (ch === '\\' && quote === '"') {
-                escaped = true;
+            if (dialect === 'posix' && ch === '\\' && quote === '"') {
+                const next = command[i + 1];
+                // POSIX keeps `\x` before an ordinary character: only $ ` " \ and a
+                // newline are escapable, so the backslash survives into the word
+                // (GHSA-972x-g47g-3922's second finding — dropping it misread both
+                // dialects at once). At end of string there is no next character to
+                // protect, and the open quote sends the whole scan to the fallback.
+                if (next === undefined || DOUBLE_QUOTE_ESCAPABLE.has(next)) {
+                    escaped = true;
+                    continue;
+                }
+                current += ch;
                 continue;
             }
             if (ch === quote)
@@ -887,7 +900,7 @@ function tokenizeSegmentsDetailed(command, honorQuotes = true) {
                 current += ch;
             continue;
         }
-        if (ch === '\\') {
+        if (dialect === 'posix' && ch === '\\') {
             escaped = true;
             continue;
         }
@@ -913,7 +926,7 @@ function tokenizeSegmentsDetailed(command, honorQuotes = true) {
     // `privileged` before this tokeniser and `safe` after. So fall back to the scan that
     // treats the quote character as ordinary text, which splits and still sees `sudo id`.
     if (quote !== null)
-        return tokenizeSegmentsDetailed(command, false);
+        return tokenizeSegmentsDetailed(command, false, dialect);
     return segments;
 }
 /**
@@ -922,20 +935,26 @@ function tokenizeSegmentsDetailed(command, honorQuotes = true) {
  * Segments are rejoined with `; ` so a pattern cannot match across two commands that the
  * shell would run separately.
  */
-let lastNormalizedInput = null;
-let lastNormalizedOutput = '';
-function normalizeCommand(command) {
+const normalizedCache = new Map();
+function normalizeCommand(command, dialect) {
     // One evaluate asks for this about nineteen times, once per regex rule, and each ask
     // re-ran the tokeniser over the whole command. The asks arrive in a row on the same
-    // input, so a one-entry cache removes almost all of it.
-    if (command === lastNormalizedInput)
-        return lastNormalizedOutput;
-    lastNormalizedInput = command;
-    lastNormalizedOutput = normalizeUncached(command);
-    return lastNormalizedOutput;
+    // input, so a small cache, evicting the oldest inserted entry, removes almost
+    // all of it. The key carries the dialect because both readings of one command
+    // are asked about in the same row.
+    const key = `${dialect}\u0000${command}`;
+    const hit = normalizedCache.get(key);
+    if (hit !== undefined)
+        return hit;
+    const value = normalizeUncached(command, dialect);
+    normalizedCache.set(key, value);
+    if (normalizedCache.size > 8) {
+        normalizedCache.delete(normalizedCache.keys().next().value);
+    }
+    return value;
 }
-function normalizeUncached(command) {
-    return tokenizeSegments(command)
+function normalizeUncached(command, dialect) {
+    return tokenizeSegments(command, dialect)
         .map((words) => words.map((w) => (QUOTED_CONTENT.test(w) ? PLACEHOLDER : w)).join(' '))
         .join('; ');
 }
@@ -976,8 +995,8 @@ const PLACEHOLDER = '\u0000';
  * inside a quoted argument into a real one — `grep -E "warn|reboot" syslog` became an
  * unconditional refusal, which is the mention-vs-invocation bug of #91 all over again.
  */
-function matchesEitherForm(command, test) {
-    return test(command) || test(normalizeCommand(command));
+function matchesEitherForm(command, test, dialect) {
+    return test(command) || test(normalizeCommand(command, dialect));
 }
 /**
  * The commands hiding inside a command.
@@ -1008,7 +1027,7 @@ function matchesEitherForm(command, test) {
  *   backticks and `sh -c` are certain carriers and keep reaching the
  *   denylist either way.
  */
-export function nestedCommands(command, speculativeOperands = true) {
+export function nestedCommands(command, speculativeOperands = true, dialect = 'posix') {
     const found = [];
     // `$(...)`, `<(...)`, `>(...)` — scanned rather than matched, because a regex
     // cannot balance parentheses and `echo $(echo $(sudo id))` is the case that
@@ -1046,7 +1065,7 @@ export function nestedCommands(command, speculativeOperands = true) {
     // scan above does not see it. Read each segment's command word rather than scanning
     // every word: matching a mention rather than an invocation is #91, and
     // `cat /usr/bin/python3` names an interpreter without running one.
-    const segments = tokenizeSegmentsDetailed(command);
+    const segments = tokenizeSegmentsDetailed(command, true, dialect);
     for (const { words } of segments) {
         // Every word, not just the command word. Stopping at the head lost the carrier behind
         // any wrapper this file does not list: `xargs -I {} sh -c 'sudo id'` stops on `{}`, and
@@ -1277,9 +1296,16 @@ const BARE_NUMERIC = /^\d+(\.\d+)?[smhd]?$/;
  * `\sudo`, `'sudo'` and `"sudo"` all execute sudo — the backslash only
  * suppresses alias expansion — but a verbatim string comparison sees three
  * different words. Without this, a one-character edit walks around the check.
+ *
+ * One surrounding quote pair, and nothing else: the scanner has already
+ * resolved escapes by the time a word reaches this, in both the
+ * quote-honouring scan and the `honorQuotes = false` fallback, so a second
+ * pass here could only remove backslashes the dialect meant to keep — the
+ * literal ones inside single quotes, and the POSIX-retained ones inside
+ * double quotes (GHSA-972x-g47g-3922).
  */
 function unquote(word) {
-    return word.replace(/^(['"])(.*)\1$/, '$2').replace(/\\(.)/g, '$1');
+    return word.replace(/^(['"])(.*)\1$/, '$2');
 }
 /**
  * Privilege-prefix flags that consume the next argument, so `sudo -u root
@@ -1291,14 +1317,14 @@ const PREFIX_VALUE_FLAGS = new Set([
     '--user', '--group', '--prompt', '--close-from', '--host', '--role', '--type',
     '--other-user', '--command',
 ]);
-/** `/sbin/reboot` and `reboot` are the same invocation. */
+/** `/sbin/reboot`, `C:\Windows\reboot.exe` and `reboot` are the same invocation. */
 function stripPath(word) {
-    const slash = word.lastIndexOf('/');
-    return slash === -1 ? word : word.slice(slash + 1);
+    const cut = Math.max(word.lastIndexOf('/'), word.lastIndexOf('\\'));
+    return cut === -1 ? word : word.slice(cut + 1);
 }
-function parseSegments(command) {
+function parseSegments(command, dialect = 'posix') {
     const segments = [];
-    for (const words of tokenizeSegments(command)) {
+    for (const words of tokenizeSegments(command, dialect)) {
         const segment = parseWords(words);
         if (segment !== null)
             segments.push(segment);
@@ -1383,8 +1409,8 @@ function elevatedBinary(words) {
  * holding, and `echo hi; sudo id` recorded `binary: "echo"` against a
  * privileged decision — in the audit log, the OTel span and OPA's input (#134).
  */
-function elevatedBinaryOf(command) {
-    for (const words of tokenizeSegments(command)) {
+function elevatedBinaryOf(command, dialect = 'posix') {
+    for (const words of tokenizeSegments(command, dialect)) {
         const found = elevatedBinary(words);
         if (found !== null)
             return found;
@@ -1411,8 +1437,8 @@ function elevatedBinaryOf(command) {
  * `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 tokenizeSegments(command).some((words) => {
+function hasDisqualifyingArgs(command, dialect = 'posix') {
+    return tokenizeSegments(command, dialect).some((words) => {
         const idx = effectiveCommandIndex(words);
         if (idx === -1)
             return false;
@@ -1420,9 +1446,9 @@ function hasDisqualifyingArgs(command) {
         return rule !== undefined && words.slice(idx + 1).some((arg) => rule.test(arg));
     });
 }
-function invokedWords(command) {
+function invokedWords(command, dialect = 'posix') {
     const invoked = [];
-    for (const { head, args } of parseSegments(command)) {
+    for (const { head, args } of parseSegments(command, dialect)) {
         invoked.push(head);
         // `systemctl reboot` restarts the host. Reading a unit that happens to be
         // named after a power action is rare enough that erring towards refusal
@@ -1444,11 +1470,11 @@ const DOWNLOADERS = new Set(['curl', 'wget']);
  * runs a shell when the download fails, which is not meaningfully safer than
  * running one when it succeeds.
  */
-function pipesDownloadIntoShell(command) {
+function pipesDownloadIntoShell(command, dialect = 'posix') {
     // One head per pipe stage. Splitting on every separator would make `curl -O x;
     // bash build.sh` — download, then run a local script — match a rule whose label says
     // "piping a download into a shell", on a list that cannot be switched off.
-    const segments = tokenizeSegmentsDetailed(command);
+    const segments = tokenizeSegmentsDetailed(command, true, dialect);
     const heads = segments
         .filter((segment, i) => i === 0 || segment.sep === '|')
         .map((segment) => parseWords(segment.words)?.head);
@@ -1458,8 +1484,8 @@ function pipesDownloadIntoShell(command) {
     return heads.slice(firstDownload + 1).some((h) => h !== undefined && SHELLS.has(h));
 }
 /** `dd … of=/dev/sda` — writing an image straight onto a block device. */
-function writesToDevice(command) {
-    return parseSegments(command).some(({ head, args }) => head === 'dd' && args.some((a) => a.startsWith('of=/dev/')));
+function writesToDevice(command, dialect = 'posix') {
+    return parseSegments(command, dialect).some(({ head, args }) => head === 'dd' && args.some((a) => a.startsWith('of=/dev/')));
 }
 /**
  * `chown -R … /` — a recursive chown whose target is the filesystem root.
@@ -1467,8 +1493,8 @@ function writesToDevice(command) {
  * The last non-flag argument is the target; `chown -R app:app /srv/app` is
  * ordinary and stays allowed.
  */
-function chownsRoot(command) {
-    return parseSegments(command).some(({ head, args }) => {
+function chownsRoot(command, dialect = 'posix') {
+    return parseSegments(command, dialect).some(({ head, args }) => {
         if (head !== 'chown' || !args.includes('-R'))
             return false;
         const positional = args.filter((a) => !a.startsWith('-'));
@@ -1478,18 +1504,18 @@ function chownsRoot(command) {
 const FORBIDDEN_RULES = [
     ...FORBIDDEN_PATTERNS.map((re) => ({
         label: String(re),
-        test: (c) => matchesEitherForm(c, (form) => re.test(form)),
+        test: (c, dialect) => matchesEitherForm(c, (form) => re.test(form), dialect),
     })),
     {
         label: 'invoking a power-state command (shutdown, reboot, halt, poweroff) or eval',
-        test: (command) => invokedWords(command).some((w) => FORBIDDEN_INVOCATIONS.has(w)),
+        test: (command, dialect) => invokedWords(command, dialect).some((w) => FORBIDDEN_INVOCATIONS.has(w)),
     },
     {
         label: 'piping a download into a shell (curl or wget into sh, bash or zsh)',
-        test: pipesDownloadIntoShell,
+        test: (c, dialect) => pipesDownloadIntoShell(c, dialect),
     },
-    { label: 'dd writing to a block device (of=/dev/…)', test: writesToDevice },
-    { label: 'a recursive chown of the filesystem root', test: chownsRoot },
+    { label: 'dd writing to a block device (of=/dev/…)', test: (c, dialect) => writesToDevice(c, dialect) },
+    { label: 'a recursive chown of the filesystem root', test: (c, dialect) => chownsRoot(c, dialect) },
 ];
 /**
  * Which never-allowed rule this command trips, or null. The single entry point:
@@ -1498,8 +1524,21 @@ const FORBIDDEN_RULES = [
  * permit `sudo reboot`.
  */
 export function findForbiddenMatch(command, depth = 0) {
+    // The engine calls this directly, so it is a decision point of its own and
+    // reads both dialects like `classifyCommand` does: a refusal under either
+    // reading is a refusal. The destructive-class consultation *inside* a
+    // dialect pass (`isDestructive`) stays in-dialect — that pass is already one
+    // reading of the whole string.
+    if (command.includes('\\')) {
+        const windows = findForbiddenMatchInDialect(command, depth, 'windows');
+        if (windows !== null)
+            return windows;
+    }
+    return findForbiddenMatchInDialect(command, depth, 'posix');
+}
+function findForbiddenMatchInDialect(command, depth, dialect) {
     for (const rule of FORBIDDEN_RULES) {
-        if (rule.test(command))
+        if (rule.test(command, dialect))
             return rule.label;
     }
     // The same carriers the class scan reads, for the same reason. This list is the
@@ -1523,15 +1562,15 @@ export function findForbiddenMatch(command, depth = 0) {
     // `nestedCommands` regardless of this flag.
     if (depth >= MAX_NESTING_DEPTH)
         return null;
-    for (const inner of nestedCommands(command, false)) {
-        const match = findForbiddenMatch(inner, depth + 1);
+    for (const inner of nestedCommands(command, false, dialect)) {
+        const match = findForbiddenMatchInDialect(inner, depth + 1, dialect);
         if (match !== null)
             return match;
     }
     return null;
 }
-export function isForbidden(command) {
-    return findForbiddenMatch(command) !== null;
+export function isForbidden(command, dialect = 'posix') {
+    return findForbiddenMatchInDialect(command, 0, dialect) !== null;
 }
 /**
  * Commands that are destructive but legitimate under approval — e.g.
@@ -1548,9 +1587,9 @@ const DESTRUCTIVE_PATTERNS = [
  * reading a log that mentions `reboot` is no longer classified destructive
  * either.
  */
-function isDestructive(command) {
-    return (isForbidden(command) ||
-        matchesEitherForm(command, (form) => DESTRUCTIVE_PATTERNS.some((re) => re.test(form))));
+function isDestructive(command, dialect = 'posix') {
+    return (isForbidden(command, dialect) ||
+        matchesEitherForm(command, (form) => DESTRUCTIVE_PATTERNS.some((re) => re.test(form)), dialect));
 }
 const LEADING_PRIVILEGE_PREFIXES = [
     /^\s*sudo\b/,
@@ -1558,13 +1597,13 @@ const LEADING_PRIVILEGE_PREFIXES = [
     /^\s*doas\b/,
     /^\s*pkexec\b/,
 ];
-export function extractBinary(command) {
+export function extractBinary(command, dialect = 'posix') {
     // The first segment's words, so quoting is resolved — `s"u"do id` used to report
     // `s"u"do` in the audit record and the refusal message. Reading the normalised whole
     // command instead would be wrong in the other direction: it rejoins segments with
     // `; `, so `ls | grep x` would report `ls;`, and this name reaches the audit record,
     // the OTel span and OPA's input (#134). A separator is not a binary.
-    let cmd = (tokenizeSegments(command)[0] ?? []).join(' ').trim();
+    let cmd = (tokenizeSegments(command, dialect)[0] ?? []).join(' ').trim();
     for (const prefix of LEADING_PRIVILEGE_PREFIXES) {
         cmd = cmd.replace(prefix, '').trim();
     }
@@ -1910,8 +1949,8 @@ function awkFindings(words) {
  * `awk 'BEGIN{system("sudo id")}'` comes out `privileged` rather than flattened
  * to the `destructive` this function reports.
  */
-function hasDangerousAwk(command) {
-    for (const { words } of tokenizeSegmentsDetailed(command)) {
+function hasDangerousAwk(command, dialect = 'posix') {
+    for (const { words } of tokenizeSegmentsDetailed(command, true, dialect)) {
         const findings = awkFindings(words);
         if (findings === null)
             continue;
@@ -1923,15 +1962,15 @@ function hasDangerousAwk(command) {
         // prints into it, and that is assembled at run time. So it is the same
         // "we cannot tell" this module reports for `-f progfile`.
         for (const target of findings.pipedInto) {
-            const stage = tokenizeSegmentsDetailed(target)[0];
+            const stage = tokenizeSegmentsDetailed(target, true, dialect)[0];
             if (stage !== undefined && readsProgramFromStdin(stage.words))
                 return true;
         }
     }
     return false;
 }
-function hasUnreadableProgram(command) {
-    const segments = tokenizeSegmentsDetailed(command);
+function hasUnreadableProgram(command, dialect = 'posix') {
+    const segments = tokenizeSegmentsDetailed(command, true, dialect);
     for (let i = 0; i < segments.length; i++) {
         const { words, sep } = segments[i];
         if (sep === '|' && readsProgramFromStdin(words))
@@ -1971,8 +2010,8 @@ function hasUnreadableProgram(command) {
  * Only the command word, never the arguments. `echo $HOME` names a command we know;
  * promoting that would put a prompt on most ordinary shell usage.
  */
-function hasUnnameableCommand(command) {
-    for (const words of tokenizeSegments(command)) {
+function hasUnnameableCommand(command, dialect = 'posix') {
+    for (const words of tokenizeSegments(command, dialect)) {
         const head = effectiveCommandWord(words);
         if (head !== null && /[$`]/.test(head))
             return true;
@@ -2018,8 +2057,8 @@ const SYNTHETIC_CLASSES = Object.assign(Object.create(null), {
     'session:open': 'destructive',
 });
 /** The first word, tokenised — the synthetic verb when there is one. */
-function syntheticVerb(command) {
-    return tokenizeSegments(command)[0]?.[0] ?? '';
+function syntheticVerb(command, dialect = 'posix') {
+    return tokenizeSegments(command, dialect)[0]?.[0] ?? '';
 }
 /**
  * The class of a command, and of everything it carries.
@@ -2033,8 +2072,20 @@ function syntheticVerb(command) {
  * Taking the maximum is what makes the scan unable to lower anything.
  */
 export function classifyCommand(command, depth = 0) {
+    // One string, two dialects, and the class is the worse of the two readings:
+    // the classifier cannot know whether the host shell reads a backslash as an
+    // escape or as a path separator, so policy must hold on whichever host
+    // receives the command (GHSA-972x-g47g-3922). A command without a backslash
+    // is byte-identical under both dialects, so it keeps the single pass.
+    if (!command.includes('\\'))
+        return classifyCommandInDialect(command, depth, 'posix');
+    const posix = classifyCommandInDialect(command, depth, 'posix');
+    const windows = classifyCommandInDialect(command, depth, 'windows');
+    return CLASS_RANK[windows.class] > CLASS_RANK[posix.class] ? windows : posix;
+}
+function classifyCommandInDialect(command, depth, dialect) {
     const trimmed = command.trim();
-    const outer = classifyOuter(trimmed);
+    const outer = classifyOuter(trimmed, dialect);
     if (depth >= MAX_NESTING_DEPTH) {
         // Nesting this deep is not something an operator writes, and we have stopped
         // reading. Refusing to guess is the only answer consistent with the rest of this
@@ -2045,13 +2096,13 @@ export function classifyCommand(command, depth = 0) {
     // A floor, not a verdict. Returning the synthetic class outright would put it above
     // the elevation and never-allowed checks, so `sftp:upload /tmp/x; sudo id` would
     // record `destructive` where the command is `privileged`.
-    const verb = syntheticVerb(trimmed);
+    const verb = syntheticVerb(trimmed, dialect);
     const floor = SYNTHETIC_CLASSES[verb];
     if (floor !== undefined && CLASS_RANK[floor] > CLASS_RANK[highest.class]) {
         highest = { binary: verb, fullCommand: trimmed, class: floor };
     }
-    for (const inner of nestedCommands(trimmed)) {
-        const parsed = classifyCommand(inner, depth + 1);
+    for (const inner of nestedCommands(trimmed, true, dialect)) {
+        const parsed = classifyCommandInDialect(inner, depth + 1, dialect);
         // `binary` follows the winning side deliberately: it is what the audit record and
         // the refusal message name, and naming the outer `echo` would describe the wrong
         // process as the one that ran as root.
@@ -2073,18 +2124,18 @@ export function classifyCommand(command, depth = 0) {
     return result;
 }
 /** The class of the command itself, reading none of what it carries. */
-function classifyOuter(trimmed) {
-    const binary = extractBinary(trimmed);
+function classifyOuter(trimmed, dialect) {
+    const binary = extractBinary(trimmed, dialect);
     const fullCommand = trimmed;
     // `binary` names the subject of the class. For everything below it is the
     // leading command; here it is the one that runs as root, which are the same
     // thing only when the prefix leads.
-    const elevated = elevatedBinaryOf(trimmed);
+    const elevated = elevatedBinaryOf(trimmed, dialect);
     if (elevated !== null) {
         return { binary: elevated, fullCommand, class: 'privileged' };
     }
-    if (hasUnreadableProgram(trimmed) || hasDangerousAwk(trimmed)
-        || isDestructive(trimmed) || hasDisqualifyingArgs(trimmed)) {
+    if (hasUnreadableProgram(trimmed, dialect) || hasDangerousAwk(trimmed, dialect)
+        || isDestructive(trimmed, dialect) || hasDisqualifyingArgs(trimmed, dialect)) {
         return { binary, fullCommand, class: 'destructive' };
     }
     // Below this point every branch assumes the command word names something we
@@ -2095,10 +2146,10 @@ function classifyOuter(trimmed) {
     // `destructive` rather than `privileged`: this is "we cannot tell", not "this is
     // root". It gates on approval instead of refusing outright, which keeps
     // `$PREFIX/bin/tool` usable for a role that holds `destructive` on the tier.
-    if (hasUnnameableCommand(trimmed)) {
+    if (hasUnnameableCommand(trimmed, dialect)) {
         return { binary, fullCommand, class: 'destructive' };
     }
-    const words = tokenizeSegments(fullCommand)[0] ?? [];
+    const words = tokenizeSegments(fullCommand, dialect)[0] ?? [];
     const twoWordPrefix = words.slice(0, 2).join(' ');
     if (READ_ONLY_ALLOWLIST.has(binary) || READ_ONLY_ALLOWLIST.has(twoWordPrefix)
         || READ_ONLY_SYNTHETIC.has(binary)) {
@@ -2125,7 +2176,7 @@ function classifyOuter(trimmed) {
         // no option or operand of the binary writes or executes, so extra
         // operands from an expansion are still data.
         if (entry.grammar.args !== 'any') {
-            const globWord = firstUnquotedGlobWord(fullCommand);
+            const globWord = firstUnquotedGlobWord(fullCommand, true, dialect);
             if (globWord !== null) {
                 return {
                     binary,

package/build/transport/http.js

@@ -13,6 +13,54 @@ export const DEFAULT_AUTH_FAILURE_LIMIT = 10;
 /** Cap on tracked clients, for the reason `MAX_SESSIONS` exists: churn must not grow a map. */
 export const MAX_TRACKED_CLIENTS = 1024;
 const REFILL_INTERVAL_MS = 60_000;
+/** Whole tokens earned since `lastRefill`. Negative when the clock stepped back; callers clamp. */
+function tokensEarned(bucket, maxTokens) {
+    return Math.floor(((Date.now() - bucket.lastRefill) / REFILL_INTERVAL_MS) * maxTokens);
+}
+/** Tokens the bucket would hold if refilled now, without changing it. */
+function availableTokens(bucket, maxTokens) {
+    return Math.min(maxTokens, bucket.tokens + Math.max(tokensEarned(bucket, maxTokens), 0));
+}
+/**
+ * How long until this bucket earns its next token, for `Retry-After`.
+ *
+ * Exact, where it used to be the fixed `REFILL_INTERVAL_MS / maxTokens`. That is how long
+ * one token takes, so a client refused halfway through the interval was told to wait
+ * twice as long as it had to. Bounded on both sides: below at a second, because
+ * `Retry-After` is whole seconds and `0` reads as "retry now"; above at one token's
+ * interval, because a clock that stepped backwards puts `lastRefill` in the future, and
+ * the raw difference would then advertise an arbitrarily long wait. Rounded up to whole
+ * milliseconds: a limit that does not divide a minute gives a fractional interval, and
+ * rounding down would name a moment at which the token has not yet arrived.
+ */
+function nextTokenWaitMs(bucket, maxTokens) {
+    const interval = REFILL_INTERVAL_MS / maxTokens;
+    return Math.max(1000, Math.ceil(Math.min(interval, bucket.lastRefill + interval - Date.now())));
+}
+/**
+ * The tracked key whose bucket holds the most tokens *after refill*: the entry with the
+ * least worth remembering, so the one to evict.
+ *
+ * Refilled, not stored. A key that stops sending keeps its stored count forever, so
+ * ranking by `tokens` treated a bucket spent an hour ago as still spent. A table that
+ * was saturated once was then judged saturated for good, which was measured.
+ *
+ * Linear in the table, and left that way: it runs only when a new key arrives at a full
+ * table, and stops early at the first full bucket. The worst case, every bucket partly
+ * spent, measured about 46µs per new key at 1024 entries (Apple M4 Max, Node 24), and
+ * the same for both limiters.
+ */
+function fullestBucket(buckets, maxTokens) {
+    let fullest;
+    for (const [key, bucket] of buckets) {
+        const available = availableTokens(bucket, maxTokens);
+        if (fullest === undefined || available > fullest.available)
+            fullest = { key, available };
+        if (available === maxTokens)
+            break;
+    }
+    return fullest;
+}
 /**
  * One token-bucket step, shared by the two limiters so the refill arithmetic exists once.
  *
@@ -20,8 +68,7 @@ const REFILL_INTERVAL_MS = 60_000;
  * idle server costs nothing and there is no interval to clean up.
  */
 function consume(bucket, maxTokens) {
-    const elapsed = Date.now() - bucket.lastRefill;
-    const refilled = Math.floor((elapsed / REFILL_INTERVAL_MS) * maxTokens);
+    const refilled = tokensEarned(bucket, maxTokens);
     if (refilled > 0) {
         bucket.tokens = Math.min(maxTokens, bucket.tokens + refilled);
         bucket.lastRefill += Math.round((refilled / maxTokens) * REFILL_INTERVAL_MS);
@@ -30,17 +77,41 @@ function consume(bucket, maxTokens) {
         bucket.tokens--;
         return { allowed: true, retryAfterMs: 0 };
     }
-    return { allowed: false, retryAfterMs: Math.ceil(REFILL_INTERVAL_MS / maxTokens) };
+    return { allowed: false, retryAfterMs: nextTokenWaitMs(bucket, maxTokens) };
 }
-class RateLimiter {
+/**
+ * A request bucket per client, so `--rateLimit` means N requests per minute *per caller*.
+ *
+ * It was one bucket for the process: one client spent `--rateLimit` for every other, and
+ * a client that had sent nothing was refused (#187, measured). Keyed by `clientKey()`,
+ * the same key the failure budget uses, and charged only after the token check passes,
+ * so unauthenticated traffic cannot create entries or drain anyone's budget.
+ *
+ * Bounded like `AuthFailureLimiter`, and it evicts the fullest bucket for the same reason.
+ * Where it differs: an arriving key always starts full, even when every tracked bucket is
+ * spent. Saturating this table takes 1024 addresses that hold the token, and a token
+ * holder with that many addresses already has that many budgets. The refund opens nothing
+ * new, while starting empty would refuse a legitimate client's first request because of
+ * other clients' traffic.
+ */
+export class ClientRateLimiter {
     maxTokens;
-    bucket;
+    buckets = new Map();
     constructor(maxTokens) {
         this.maxTokens = maxTokens;
-        this.bucket = { tokens: maxTokens, lastRefill: Date.now() };
     }
-    tryConsume() {
-        return consume(this.bucket, this.maxTokens);
+    tryConsume(key) {
+        let bucket = this.buckets.get(key);
+        if (bucket === undefined) {
+            if (this.buckets.size >= MAX_TRACKED_CLIENTS) {
+                const fullest = fullestBucket(this.buckets, this.maxTokens);
+                if (fullest !== undefined)
+                    this.buckets.delete(fullest.key);
+            }
+            bucket = { tokens: this.maxTokens, lastRefill: Date.now() };
+            this.buckets.set(key, bucket);
+        }
+        return consume(bucket, this.maxTokens);
     }
 }
 /**
@@ -50,8 +121,8 @@ class RateLimiter {
  * limiter was reached, so a wrong bearer token consumed nothing and guessing ran at network
  * speed with no backoff — measured as twelve 401s and zero 429s against `--rateLimit=3`.
  * Moving the request limiter above the auth check would have closed that and opened
- * something worse: the request bucket is global, so unauthenticated traffic could then
- * starve every legitimate client.
+ * something worse: its 429 would answer a guess without evaluating it, and unauthenticated
+ * traffic reaching a request bucket could spend a victim's budget under a spoofable key.
  *
  * Only failures consume a token, so a working client never builds a budget up and is never
  * throttled by its own traffic — which is what makes this safe to have on by default. It
@@ -71,12 +142,9 @@ export class AuthFailureLimiter {
         const bucket = this.buckets.get(key);
         if (bucket === undefined)
             return { allowed: true, retryAfterMs: 0 };
-        const elapsed = Date.now() - bucket.lastRefill;
-        const refilled = Math.floor((elapsed / REFILL_INTERVAL_MS) * this.maxTokens);
-        const available = Math.min(this.maxTokens, bucket.tokens + Math.max(refilled, 0));
-        if (available > 0)
+        if (availableTokens(bucket, this.maxTokens) > 0)
             return { allowed: true, retryAfterMs: 0 };
-        return { allowed: false, retryAfterMs: Math.ceil(REFILL_INTERVAL_MS / this.maxTokens) };
+        return { allowed: false, retryAfterMs: nextTokenWaitMs(bucket, this.maxTokens) };
     }
     /** Charge this client for a failed attempt. */
     recordFailure(key) {
@@ -89,16 +157,9 @@ export class AuthFailureLimiter {
                 // first and then handed its key a fresh budget: minting enough keys cleared a
                 // lockout, which was measured end to end. A full bucket is the one with nothing
                 // worth remembering.
-                let fullestKey = null;
-                let fullest = -1;
-                for (const [k, b] of this.buckets) {
-                    if (b.tokens > fullest) {
-                        fullest = b.tokens;
-                        fullestKey = k;
-                    }
-                }
-                if (fullestKey !== null)
-                    this.buckets.delete(fullestKey);
+                const fullest = fullestBucket(this.buckets, this.maxTokens);
+                if (fullest !== undefined)
+                    this.buckets.delete(fullest.key);
                 // Every tracked client is spent, so the table itself is the signal and a new key
                 // does not get a full budget.
                 //
@@ -109,8 +170,9 @@ export class AuthFailureLimiter {
                 // `peek` already allows a key it has never seen, so the first attempt is free
                 // either way and the second is refused either way. Measured both, identical.
                 // Giving an arriving key a real budget is the refund this rule exists to stop.
-                // Saturation needs 1024 addresses that have each spent a full budget.
-                if (fullest <= 0)
+                // Saturation needs 1024 addresses that have each spent a full budget *recently*:
+                // `fullestBucket` ranks by refilled tokens, so the condition ends once they refill.
+                if (fullest === undefined || fullest.available <= 0)
                     bucket = { tokens: 0, lastRefill: Date.now() };
             }
             this.buckets.set(key, bucket);
@@ -216,23 +278,25 @@ export async function startHttpServer(createMcpServer, opts) {
         ? new AuthFailureLimiter(authFailureLimit)
         : null;
     // Said once, when it turns out to matter. Behind a proxy with `--trustProxy` off, every
-    // client is keyed on the proxy's socket address and so shares one budget — which means
-    // ten failures from anyone locks out everyone. The README tells operators to terminate
-    // TLS at a proxy, so this is the configuration it recommends, and the collapse is
-    // invisible until a legitimate client is refused.
+    // client is keyed on the proxy's socket address and so shares one failure budget and one
+    // request budget — ten failures from anyone locks out everyone, and one busy client
+    // starves the rest. The README tells operators to terminate TLS at a proxy, so this is
+    // the configuration it recommends, and the collapse is invisible until a legitimate
+    // client is refused.
     let warnedSharedBudget = false;
     const warnSharedBudget = () => {
         if (warnedSharedBudget)
             return;
         warnedSharedBudget = true;
         console.error('POLICY WARNING: X-Forwarded-For is present but not being used to tell clients ' +
-            'apart, so every client shares one failed-auth budget and one failing client can ' +
-            'lock out the rest. Either --trustProxy is off, or the peer is not a trusted proxy ' +
-            '(bare --trustProxy trusts a loopback peer; name others with --trustedProxies), or ' +
-            'the rightmost entry is not an address this server can read.');
+            'apart, so every client is charged to one key: one failed-auth budget and one ' +
+            'request budget between them, for whichever of the two is on, and one client can ' +
+            'lock out or starve the rest. Either --trustProxy is off, or the peer is not a ' +
+            'trusted proxy (bare --trustProxy trusts a loopback peer; name others with ' +
+            '--trustedProxies), or the rightmost entry is not an address this server can read.');
     };
     const rateLimiter = opts.rateLimit && opts.rateLimit > 0
-        ? new RateLimiter(opts.rateLimit)
+        ? new ClientRateLimiter(opts.rateLimit)
         : null;
     // DNS rebinding: a page the user visits can make their browser POST to a
     // localhost server, and the bearer token does not help if the browser is
@@ -284,22 +348,24 @@ export async function startHttpServer(createMcpServer, opts) {
         // is configured — see the handler below for why that second bit is not a secret.
         const isHealthProbe = req.method === 'GET' && url.pathname === '/health';
         if (!isHealthProbe) {
-            // Checked before the token is compared, not after — so an exhausted budget answers
-            // 429 without evaluating the guess. Gating only the 401 path instead would throttle
-            // nothing: the comparison would still happen and a correct token would still be
-            // served, so the status code would still tell an attacker which guess was right.
             let key = '';
-            if (authFailureLimiter) {
+            if (authFailureLimiter || rateLimiter) {
                 const resolved = clientKey(req, opts.trustProxy === true, opts.trustedProxies);
                 key = resolved.key;
                 // Warned in both directions. Without `--trustProxy` a proxied deployment shares
                 // one budget; *with* it, an entry that could not be read leaves the same collapse
                 // in place, and that case used to be the silent one — the operator had set the
                 // flag and had no way to know it was not taking effect.
+                // Resolved for either limiter: with only `--rateLimit` on, skipping this charged
+                // every client to one key and kept the warning silent.
                 if (resolved.forwardedIgnored || (opts.trustProxy !== true && req.headers['x-forwarded-for'])) {
                     warnSharedBudget();
                 }
             }
+            // Checked before the token is compared, not after — so an exhausted budget answers
+            // 429 without evaluating the guess. Gating only the 401 path instead would throttle
+            // nothing: the comparison would still happen and a correct token would still be
+            // served, so the status code would still tell an attacker which guess was right.
             if (authFailureLimiter) {
                 const { allowed, retryAfterMs } = authFailureLimiter.peek(key);
                 if (!allowed) {
@@ -341,23 +407,29 @@ export async function startHttpServer(createMcpServer, opts) {
                 }));
                 return;
             }
-        }
-        if (rateLimiter && url.pathname === '/' && (req.method === 'POST' || req.method === 'GET' || req.method === 'DELETE')) {
-            const { allowed, retryAfterMs } = rateLimiter.tryConsume();
-            if (!allowed) {
-                const retryAfterSec = Math.ceil(retryAfterMs / 1000);
-                res.writeHead(429, {
-                    'Content-Type': 'application/json',
-                    'Retry-After': String(retryAfterSec),
-                });
-                res.end(JSON.stringify({
-                    jsonrpc: '2.0',
-                    error: {
-                        code: -32604,
-                        message: `Rate limit exceeded. Retry after ${retryAfterSec}s.`,
-                    },
-                }));
-                return;
+            // Charged after the token check, never before: a request bucket is per client, but
+            // unauthenticated traffic reaching it could still spend a victim's budget under a
+            // spoofable key, and its 429 would answer a guess without evaluating it. Every
+            // authenticated route spends from it, `/status` and 404s included: `/status` was
+            // unlimited, so a token holder could poll it without bound.
+            if (rateLimiter) {
+                const { allowed, retryAfterMs } = rateLimiter.tryConsume(key);
+                if (!allowed) {
+                    const retryAfterSec = Math.ceil(retryAfterMs / 1000);
+                    res.writeHead(429, {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(retryAfterSec),
+                    });
+                    res.end(JSON.stringify({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32604,
+                            message: `Rate limit exceeded. Retry after ${retryAfterSec}s.`,
+                        },
+                        id: null,
+                    }));
+                    return;
+                }
             }
         }
         if (req.method === 'POST' && url.pathname === '/') {
@@ -464,7 +536,7 @@ export async function startHttpServer(createMcpServer, opts) {
             console.error(`SSH MCP Server v2 (HTTP) listening on http://${host}:${port}`);
             console.error('Endpoints: POST / (MCP), GET /status, GET /health');
             if (rateLimiter) {
-                console.error(`Rate limit: ${opts.rateLimit} req/min`);
+                console.error(`Rate limit: ${opts.rateLimit} req/min per client`);
             }
             if (authFailureLimiter) {
                 console.error(`Auth failure limit: ${authFailureLimit}/min per client`);

package/package.json

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