ssh-mcp 2.5.1 → 2.7.0

package/build/policy/engine.js

@@ -1,5 +1,17 @@
 import { classifyCommand, findForbiddenMatch } from './classifier.js';
 import { OperatorError } from '../errors.js';
+/**
+ * How long to wait for the OPA sidecar before treating it as unavailable.
+ *
+ * Bounded because an unbounded wait held every tool call for undici's five-minute header
+ * timeout. Ten seconds and not two: in the default mode a timeout falls back to the local
+ * decision, so the budget is also the price of turning an explicit OPA *deny* into an
+ * allow — at two seconds a sidecar under load crosses it by accident, and anyone who can
+ * add latency crosses it on purpose. Ten is above a loaded sidecar's p99 and still thirty
+ * times cheaper than the hang it replaced. `--opaTimeoutMs` moves it: lower makes the
+ * fail-open cheaper to reach, higher makes an outage slower to notice.
+ */
+const DEFAULT_OPA_TIMEOUT_MS = 10_000;
 /** Tiers, most restrictive first. Unknown/unset tiers resolve to the first. */
 export const HOST_GROUPS = ['prod', 'staging', 'dev'];
 export const DEFAULT_RULES = {
@@ -184,6 +196,8 @@ export function resolvePolicyRules(profiles, override) {
 export class PolicyEngine {
     rules;
     opaUrl = null;
+    opaFailClosed = false;
+    opaTimeoutMs = DEFAULT_OPA_TIMEOUT_MS;
     /** Rate-limits the fail-open warning so one outage can't flood stderr. */
     lastOpaWarning = 0;
     /** The operator's patterns, compiled once. The built-ins live in classifier.ts. */
@@ -202,8 +216,15 @@ export class PolicyEngine {
             }
         });
     }
-    setOpaUrl(url) {
+    setOpaUrl(url, failClosed = false, timeoutMs = DEFAULT_OPA_TIMEOUT_MS) {
+        this.opaTimeoutMs = timeoutMs;
+        // Reset the warning throttle when the mode changes, or the one warning per minute can
+        // be the *previous* mode's sentence — "commands OPA would deny may now be allowed"
+        // printed while the engine refuses everything.
+        if (failClosed !== this.opaFailClosed || url !== this.opaUrl)
+            this.lastOpaWarning = 0;
         this.opaUrl = url;
+        this.opaFailClosed = failClosed;
     }
     evaluate(command, profile, _toolName) {
         const parsed = classifyCommand(command);
@@ -277,13 +298,31 @@ export class PolicyEngine {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ input }),
+                // A sidecar that accepts the connection and never answers is the canonical way
+                // OPA is "unreachable", and without this the call ran to undici's five-minute
+                // header timeout while every tool call waited on it. The abort lands in the catch
+                // below, so both modes reach their own answer inside the budget.
+                signal: AbortSignal.timeout(this.opaTimeoutMs),
             });
             if (!resp.ok) {
-                this.warnOpaUnavailable(`HTTP ${resp.status} from ${this.opaUrl}`);
-                return local;
+                return this.onOpaUnavailable(`HTTP ${resp.status}`, local);
             }
-            const data = await resp.json();
-            if (data.result === false) {
+            const payload = await resp.json();
+            // Guarded, not cast. `as { result?: unknown }` is a lie for a `null` body — reading
+            // `.result` off it threw, so the cause on stderr read as a defect in this server
+            // rather than as the "no decision" condition it names below.
+            const result = typeof payload === 'object' && payload !== null
+                ? payload.result
+                : undefined;
+            if (typeof result !== 'boolean') {
+                // A 200 carrying no decision is how OPA answers for an undefined document, which
+                // is what a wrong package path, an unactivated bundle, or an `allow` rule written
+                // without `default allow := false` all produce. Reading that as consent meant
+                // `--opaFailClosed` did not cover the way an OPA gate actually goes down: six of
+                // seven response shapes allowed, with no warning at all.
+                return this.onOpaUnavailable('no boolean `result` in the response', local);
+            }
+            if (result === false) {
                 return {
                     decision: 'deny',
                     commandClass: parsed.class,
@@ -294,10 +333,36 @@ export class PolicyEngine {
             }
         }
         catch (err) {
-            this.warnOpaUnavailable(err instanceof Error ? err.message : String(err));
+            return this.onOpaUnavailable(err instanceof Error ? err.message : String(err), local);
         }
         return local;
     }
+    /**
+     * What an OPA outage means, which is the operator's choice rather than ours.
+     *
+     * Falling back to the local decision is the default and stays the default: OPA is an
+     * additional deny layer, and an outage that stopped all work would be a worse failure
+     * than one that narrows the policy. But an operator who deployed OPA *as* the
+     * authorization gate has a control that disappears during an outage, and the only signal
+     * is a stderr line that MCP clients usually discard. `--opaFailClosed` lets them say
+     * that the gate being down means no.
+     */
+    onOpaUnavailable(cause, local) {
+        this.warnOpaUnavailable(cause);
+        if (!this.opaFailClosed)
+            return local;
+        return {
+            decision: 'deny',
+            commandClass: local.commandClass,
+            binary: local.binary,
+            ruleId: 'opa-unavailable',
+            // Fixed string. `cause` goes to stderr, where the operator is; this `reason` is
+            // rethrown as the tool's error text and written to the audit record, and it carried
+            // `this.opaUrl` — an internal hostname, and any credential embedded in it — out to
+            // the MCP client on every refusal.
+            reason: 'OPA evaluation unavailable and --opaFailClosed is set',
+        };
+    }
     /**
      * OPA is an *additional* deny layer, so an outage falls back to the local
      * decision rather than blocking all work. That is a deliberate trade-off, but
@@ -311,7 +376,9 @@ export class PolicyEngine {
             return;
         this.lastOpaWarning = now;
         console.error(`POLICY WARNING: OPA evaluation unavailable (${cause}). ` +
-            'Falling back to local policy — commands OPA would deny may now be allowed.');
+            (this.opaFailClosed
+                ? 'Refusing every command while it is down, because --opaFailClosed is set.'
+                : 'Falling back to local policy — commands OPA would deny may now be allowed.'));
     }
     /**
      * Say which three things produced the refusal, not one of them.

package/build/tools/descriptions.js

@@ -6,8 +6,8 @@ export const TOOL_DESCRIPTIONS = {
     'close-session': 'Close a named session. A background session\'s command is signalled on the host (INT, then TERM, then KILL) before its channel is dropped; an interactive session\'s shell is ended. The response says so if the command could not be signalled or had not stopped in time.',
     'read-session-output': 'Read recent output from a background session (e.g., tail -f logs).',
     '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.',
-    'run-command': 'Execute an arbitrary shell command on the remote server. May modify the system. Destructive commands require user approval.',
-    'privileged-command': 'Execute a command with sudo elevation. ALWAYS requires user approval. The sudo password is piped via stdin (never visible in process list).',
+    '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.',
+    '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).',
     'sftp-upload': 'Upload a file to the remote server via SFTP (secure file transfer, not shell-based).',
     'sftp-download': 'Download a file from the remote server via SFTP.',
     'signal-process': 'Send a signal (INT, TERM, KILL) to a remote process by PID.',

package/build/transport/http.js

@@ -1,5 +1,6 @@
 import { createServer } from 'http';
 import { randomUUID, timingSafeEqual } from 'crypto';
+import { isIP } from 'net';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { SERVER_VERSION } from '../version.js';
@@ -7,32 +8,193 @@ import { OperatorError } from '../errors.js';
 const MAX_BODY_SIZE = 1_048_576; // 1MB
 /** Cap on concurrent MCP sessions, so unauthenticated-adjacent churn can't grow the map without bound. */
 const MAX_SESSIONS = 64;
+/** How many failed auth attempts one client may make per minute. 0 disables the check. */
+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;
+/**
+ * One token-bucket step, shared by the two limiters so the refill arithmetic exists once.
+ *
+ * Mutates the bucket. Refills proportionally to elapsed time rather than on a timer, so an
+ * 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);
+    if (refilled > 0) {
+        bucket.tokens = Math.min(maxTokens, bucket.tokens + refilled);
+        bucket.lastRefill += Math.round((refilled / maxTokens) * REFILL_INTERVAL_MS);
+    }
+    if (bucket.tokens > 0) {
+        bucket.tokens--;
+        return { allowed: true, retryAfterMs: 0 };
+    }
+    return { allowed: false, retryAfterMs: Math.ceil(REFILL_INTERVAL_MS / maxTokens) };
+}
 class RateLimiter {
-    tokens;
-    lastRefill;
     maxTokens;
-    refillIntervalMs;
-    constructor(maxRequestsPerMinute) {
-        this.maxTokens = maxRequestsPerMinute;
-        this.tokens = maxRequestsPerMinute;
-        this.lastRefill = Date.now();
-        this.refillIntervalMs = 60_000;
+    bucket;
+    constructor(maxTokens) {
+        this.maxTokens = maxTokens;
+        this.bucket = { tokens: maxTokens, lastRefill: Date.now() };
     }
     tryConsume() {
-        const now = Date.now();
-        const elapsed = now - this.lastRefill;
-        const refilled = Math.floor((elapsed / this.refillIntervalMs) * this.maxTokens);
-        if (refilled > 0) {
-            this.tokens = Math.min(this.maxTokens, this.tokens + refilled);
-            this.lastRefill += Math.round((refilled / this.maxTokens) * this.refillIntervalMs);
-        }
-        if (this.tokens > 0) {
-            this.tokens--;
+        return consume(this.bucket, this.maxTokens);
+    }
+}
+/**
+ * A bucket per client, for throttling failed authentication.
+ *
+ * Separate from the request limiter on purpose. The auth check returned before the request
+ * 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.
+ *
+ * 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
+ * is not a promise that a correct token always passes: once an address has spent its
+ * budget, everything from that address waits, correct tokens included. That is the whole
+ * point. Charging only after the comparison would leave the guess itself evaluated and the
+ * status code would still tell the attacker which token was right.
+ */
+export class AuthFailureLimiter {
+    maxTokens;
+    buckets = new Map();
+    constructor(maxTokens) {
+        this.maxTokens = maxTokens;
+    }
+    /** Whether this client may make another attempt. Does not consume. */
+    peek(key) {
+        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)
             return { allowed: true, retryAfterMs: 0 };
+        return { allowed: false, retryAfterMs: Math.ceil(REFILL_INTERVAL_MS / this.maxTokens) };
+    }
+    /** Charge this client for a failed attempt. */
+    recordFailure(key) {
+        let bucket = this.buckets.get(key);
+        if (bucket === undefined) {
+            bucket = { tokens: this.maxTokens, lastRefill: Date.now() };
+            if (this.buckets.size >= MAX_TRACKED_CLIENTS) {
+                // Evict the *fullest* entry, not the oldest. An exhausted bucket has the oldest
+                // `lastRefill` by construction, so evicting by age evicted the locked-out client
+                // 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);
+                // Every tracked client is spent, so the table itself is the signal and a new key
+                // does not get a full budget.
+                //
+                // The cost, stated because it is real and cannot be softened here: while the table
+                // is saturated an arriving client has one attempt rather than the full budget, so
+                // a first typo leaves its correct token waiting. Seeding one token instead of zero
+                // looks like it would help and does not — `consume` spends it immediately, and
+                // `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)
+                    bucket = { tokens: 0, lastRefill: Date.now() };
+            }
+            this.buckets.set(key, bucket);
         }
-        const retryAfterMs = Math.ceil(this.refillIntervalMs / this.maxTokens);
-        return { allowed: false, retryAfterMs };
+        consume(bucket, this.maxTokens);
+    }
+}
+/**
+ * Which client an attempt is charged to.
+ *
+ * The socket's remote address, which is the real client on a direct connection — how this
+ * server is normally run. `X-Forwarded-For` is read only when a proxy is explicitly
+ * trusted: honouring it unconditionally would let any client forge its own key and so opt
+ * out of the limit entirely.
+ *
+ * When it is read, the **rightmost** entry is the one taken, not the leftmost. A proxy
+ * appends the address it saw, so the rightmost entry is what the nearest trusted proxy
+ * observed while every entry to its left came from the client. Reading the leftmost was
+ * worse than having no limit: a client sending `X-Forwarded-For: 10.0.0.1` minted a fresh
+ * budget per request — measured as nine wrong tokens and zero 429s — and sending a
+ * victim's address burned *their* budget instead, locking out a correct token.
+ *
+ * This assumes exactly one trusted proxy in front, which is what `--trustProxy` means. A
+ * chain of two would need the second-from-right, and this does not try to guess the depth.
+ * Anything that is not an IP address is discarded rather than used as a map key.
+ */
+export function clientKey(req, trustProxy, trustedProxies) {
+    const peer = canonicalAddress(req.socket.remoteAddress ?? 'unknown');
+    const forwarded = req.headers['x-forwarded-for'];
+    if (!trustProxy || forwarded === undefined)
+        return { key: peer, forwardedIgnored: false };
+    // The rightmost entry is proxy-authored only if a proxy actually appended one. Nothing
+    // about the header says whether it did, so the *peer* has to be the proxy — otherwise a
+    // client reaching the listener directly sends one forged entry, that entry is the
+    // rightmost, and it picks its own key. Both attacks this keying was fixed to stop came
+    // back alive in exactly that configuration.
+    if (!isTrustedPeer(peer, trustedProxies)) {
+        return { key: peer, forwardedIgnored: true };
+    }
+    const raw = Array.isArray(forwarded) ? forwarded.join(',') : forwarded;
+    const entries = raw.split(',').map((e) => e.trim()).filter(Boolean);
+    const nearest = entries[entries.length - 1];
+    const address = nearest === undefined ? undefined : forwardedAddress(nearest);
+    if (address === undefined)
+        return { key: peer, forwardedIgnored: true };
+    return { key: address, forwardedIgnored: false };
+}
+/**
+ * Whether the peer may speak for other clients.
+ *
+ * Bare `--trustProxy` means a loopback peer, which is the deployment the README asks for:
+ * the server binds to 127.0.0.1 and a proxy on the same host terminates TLS. A proxy
+ * somewhere else has to be named, because "trust whoever connected" is the assumption that
+ * made the header forgeable again.
+ */
+function isTrustedPeer(peer, trustedProxies) {
+    if (trustedProxies !== undefined && trustedProxies.length > 0) {
+        return trustedProxies.includes(peer);
+    }
+    return peer === '127.0.0.1' || peer === '::1' || peer.startsWith('127.');
+}
+/**
+ * One `X-Forwarded-For` entry as an address, or undefined if it is not one.
+ *
+ * `net.isIP` rejects the bracketed and port-suffixed spellings, which is how IPv6 usually
+ * appears in this header — and rejecting silently collapsed every client onto the proxy's
+ * key, which is worse than not keying at all.
+ */
+function forwardedAddress(entry) {
+    let candidate = entry;
+    const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(candidate);
+    if (bracketed)
+        candidate = bracketed[1];
+    // A trailing `:port` only when what is left is not itself an IPv6 literal: `::1` has
+    // colons of its own and must not be truncated.
+    else if (isIP(candidate) === 0 && /^[^:]+:\d+$/.test(candidate)) {
+        candidate = candidate.slice(0, candidate.lastIndexOf(':'));
     }
+    candidate = canonicalAddress(candidate);
+    return isIP(candidate) === 0 ? undefined : candidate;
+}
+/** `::ffff:127.0.0.1` and `127.0.0.1` are the same client; key them the same way. */
+function canonicalAddress(address) {
+    return address.startsWith('::ffff:') ? address.slice(7) : address;
 }
 function jsonRpcError(res, status, code, message) {
     res.writeHead(status, { 'Content-Type': 'application/json' });
@@ -49,6 +211,26 @@ export async function startHttpServer(createMcpServer, opts) {
         throw new OperatorError('HTTP transport requires --bearerToken. Example: --transport=http --bearerToken=secret\n' +
             'Without authentication, any network client can execute SSH commands on your hosts.');
     }
+    const authFailureLimit = opts.authFailureLimit ?? DEFAULT_AUTH_FAILURE_LIMIT;
+    const authFailureLimiter = authFailureLimit > 0
+        ? 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.
+    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.');
+    };
     const rateLimiter = opts.rateLimit && opts.rateLimit > 0
         ? new RateLimiter(opts.rateLimit)
         : null;
@@ -102,6 +284,41 @@ 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) {
+                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.
+                if (resolved.forwardedIgnored || (opts.trustProxy !== true && req.headers['x-forwarded-for'])) {
+                    warnSharedBudget();
+                }
+            }
+            if (authFailureLimiter) {
+                const { allowed, retryAfterMs } = authFailureLimiter.peek(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: `Too many failed authentication attempts. Retry after ${retryAfterSec}s.`,
+                        },
+                        id: null,
+                    }));
+                    return;
+                }
+            }
             const auth = req.headers.authorization || '';
             const expected = `Bearer ${bearerToken}`;
             const authBuf = Buffer.from(auth);
@@ -109,6 +326,7 @@ export async function startHttpServer(createMcpServer, opts) {
             const match = authBuf.length === expectedBuf.length &&
                 timingSafeEqual(authBuf, expectedBuf);
             if (!match) {
+                authFailureLimiter?.recordFailure(key);
                 // RFC 7235: a 401 must say how to authenticate. MCP clients also parse
                 // JSON-RPC envelopes on this route, so 401 speaks the same dialect as
                 // the 429 and 413 responses rather than a bare {error}.
@@ -248,6 +466,9 @@ export async function startHttpServer(createMcpServer, opts) {
             if (rateLimiter) {
                 console.error(`Rate limit: ${opts.rateLimit} req/min`);
             }
+            if (authFailureLimiter) {
+                console.error(`Auth failure limit: ${authFailureLimit}/min per client`);
+            }
             resolve();
         });
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.5.1",
+  "version": "2.7.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",
@@ -38,8 +38,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "^0.7.0",
-    "@changesets/cli": "^2.31.0",
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.1",
     "@types/node": "^26.2.0",
     "@types/ssh2": "^1.15.5",
     "@vitest/coverage-v8": "^4.1.10",