ssh-mcp 2.2.0 → 2.2.2

package/README.md

@@ -378,6 +378,19 @@ distinguishable from a fresh human answer.
 **Off by default** (`0` = always prompt). Auto-approval weakens the gate that
 makes destructive commands safe, so turning it on should be a decision.
 
+#### Answering the prompt
+
+Approval goes through the MCP elicitation request, so what you see is your
+client's dialog. Accepting it approves the command — there is no second field to
+fill in.
+
+You have **10 minutes** to answer. Past that the request expires and the command
+is refused rather than left pending, and the refusal says so; the prompt may
+still be open in your client, in which case run the command again once you are
+ready. If your client does not support elicitation at all, every destructive and
+privileged command is refused with `APPROVAL_UNAVAILABLE` naming that cause —
+approval fails closed by design.
+
 ### Command Quota
 
 `commandQuotaPerDay` bounds how many commands a profile may run in a rolling

package/build/guard/elicitation.js

@@ -1,3 +1,17 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * How long a person has to read a destructive command and decide.
+ *
+ * Explicit because the SDK's DEFAULT_REQUEST_TIMEOUT_MSEC is 60 seconds, and
+ * inheriting it here set a human's reading time from a default chosen for
+ * machine round trips. An operator who stepped away, or who was working out an
+ * unfamiliar dialog, had the request expire underneath them and the command
+ * refused (#91).
+ *
+ * Ten minutes is long enough to be interrupted and come back, and still bounded
+ * so a client that never answers cannot pin a tool call open forever.
+ */
+export const APPROVAL_TIMEOUT_MS = 600_000;
 /**
  * Ask the MCP client to confirm a destructive or privileged command.
  *
@@ -6,8 +20,9 @@
  * of silently disabling the gate that guards every destructive command.
  *
  * Fails closed: any error (client without elicitation support, transport
- * failure, malformed reply) denies the command. The failure is logged, because
- * a gate that always denies for an unnoticed reason is its own kind of outage.
+ * failure, timeout, malformed reply) denies the command. The failure is logged,
+ * because a gate that always denies for an unnoticed reason is its own kind of
+ * outage.
  */
 export async function requestApproval(server, command, profileName, evaluation) {
     const message = `Confirm ${evaluation.commandClass} command on "${profileName}":\n\n${command}`;
@@ -22,17 +37,47 @@ export async function requestApproval(server, command, profileName, evaluation)
                         title: 'Approve this command?',
                     },
                 },
-                required: ['confirm'],
+                // `confirm` is deliberately not required. The protocol already carries
+                // the decision in `action`, where accept and decline are distinct
+                // results, so requiring a boolean on top asked the user to say the
+                // same thing twice — and clients render a required boolean as a
+                // checkbox beside the accept/decline row. Choosing Accept without
+                // ticking it submits a form missing a required field, so the client
+                // can produce no valid result and sends `cancel`, which arrived here
+                // as "User did not approve this command". The user picked Approve and
+                // was told they had declined (#91).
             },
-        });
-        if (result.action === 'accept' && result.content?.confirm === true) {
+        }, { timeout: APPROVAL_TIMEOUT_MS });
+        // `action` decides. An explicit `confirm: false` from a client that still
+        // sends the field is honoured, because refusing to run on an explicit "no"
+        // costs nothing and reading it as approval would be indefensible.
+        if (result.action === 'accept' && result.content?.confirm !== false) {
             return { approved: true, approver: 'mcp-client' };
         }
         return { approved: false };
     }
     catch (err) {
+        const timedOut = err instanceof McpError && err.code === ErrorCode.RequestTimeout;
+        const cause = err instanceof Error ? err.message : String(err);
+        // stderr still gets it for the operator's logs, but it cannot be the only
+        // copy: for a stdio MCP server that is a client log file nobody reads, so
+        // the caller gets the diagnosis too and can put it in front of the user.
         console.error(`Approval request failed for ${evaluation.commandClass} command on "${profileName}" — denying. ` +
-            `Does this client support elicitation? Cause: ${err instanceof Error ? err.message : String(err)}`);
-        return { approved: false };
+            `${timedOut ? `No answer within ${APPROVAL_TIMEOUT_MS / 1000}s.` : 'Does this client support elicitation?'} ` +
+            `Cause: ${cause}`);
+        // Naming the cause rather than guessing at it. This message was introduced
+        // to stop APPROVAL_DENIED covering two different failures, and then led with
+        // "a client without elicitation support" for every error the catch saw,
+        // timeouts included — the same defect, inside its own fix.
+        return {
+            approved: false,
+            unavailable: timedOut
+                ? `no answer arrived within ${APPROVAL_TIMEOUT_MS / 1000}s, so it was refused rather than left ` +
+                    `pending. The prompt may still be open in your client; approve the command again once you are ` +
+                    `ready to answer it.`
+                : `this MCP client could not be asked to approve it. The likely cause is a client without ` +
+                    `elicitation support; a transport failure or a malformed reply does the same. Approval fails ` +
+                    `closed, so the command was refused rather than run. Underlying error: ${cause}`,
+        };
     }
 }

package/build/index.js

@@ -24,6 +24,27 @@ function parseArgv() {
     }
     return config;
 }
+/**
+ * Whether a boolean flag was passed at all.
+ *
+ * `parseArgv` stores `null` for a flag written without `=`, which is how every
+ * documented boolean flag is written. Testing that value for truthiness makes
+ * the flag a no-op: `--disableApproval`, `--auditEntropyScan` and
+ * `--auditTamperEvident` all did nothing unless spelled `--flag=1`, which
+ * nothing documents (#91). The two call sites that got it right already used
+ * `!== undefined`; this gives the check a name so the next one cannot miss it.
+ *
+ * `--flag=false` and `--flag=0` turn it off, because a flag that cannot be
+ * turned off once written into a wrapper script is its own annoyance.
+ */
+function flagEnabled(argv, name) {
+    if (!(name in argv))
+        return false;
+    const value = argv[name];
+    if (value === null || value === '')
+        return true;
+    return !['false', '0', 'no', 'off'].includes(value.toLowerCase());
+}
 /**
  * v1 flags that v2 removed. Silently ignoring them means the user only finds
  * out at the first command, as an auth failure with no hint about the cause.
@@ -62,7 +83,7 @@ function parseMaxChars(raw) {
  * existed. `--insecureHostKey` is kept as an alias for the documented flag.
  */
 function resolveHostKeyMode(argv) {
-    if (argv.insecureHostKey !== undefined)
+    if (flagEnabled(argv, 'insecureHostKey'))
         return 'insecure';
     const mode = argv.hostKeyMode;
     if (mode === null || mode === undefined)
@@ -134,7 +155,7 @@ async function buildAppConfig(argv) {
         role: 'admin',
         group: resolveHostGroup(argv),
         readOnly: false,
-        approvalPolicy: argv.disableApproval ? 'auto' : defaults.approvalMode,
+        approvalPolicy: flagEnabled(argv, 'disableApproval') ? 'auto' : defaults.approvalMode,
         cert: false,
         sessionMaxPerConnection: defaults.sessionMaxPerConnection,
         sessionIdleTimeoutMs: defaults.sessionIdleTimeoutMs,
@@ -152,8 +173,8 @@ async function main() {
     }
     const config = await buildAppConfig(argv);
     const hostKeyMode = resolveHostKeyMode(argv);
-    const entropyScan = !!argv.auditEntropyScan;
-    const tamperEvident = !!argv.auditTamperEvident;
+    const entropyScan = flagEnabled(argv, 'auditEntropyScan');
+    const tamperEvident = flagEnabled(argv, 'auditTamperEvident');
     await initKeychain();
     if (argv.otelEndpoint) {
         const { initTracing } = await import('./observability/tracer.js');
@@ -242,4 +263,4 @@ if (isCliEnabled || isTestMode) {
         process.exit(1);
     });
 }
-export { parseArgv, buildAppConfig, checkRemovedFlags, parseMaxChars };
+export { parseArgv, buildAppConfig, checkRemovedFlags, parseMaxChars, flagEnabled, resolveHostKeyMode };

package/build/policy/classifier.js

@@ -60,14 +60,9 @@ const FORBIDDEN_PATTERNS = [
     /mkfs\./,
     /dd\s.*\bof=\/dev\//,
     />\s*\/dev\/sd/,
-    /\bshutdown\b/,
-    /\breboot\b/,
-    /\bhalt\b/,
-    /\bpoweroff\b/,
     /:\(\)\s*\{\s*:\|:\&\s*\}\s*;\s*:/, // fork bomb
     /curl\s[^|]*\|\s*(sh|bash|zsh)/,
     /wget\s[^|]*\|\s*(sh|bash|zsh)/,
-    /\beval\b/,
     />\s*\/etc\/cron/,
     />\s*\/etc\/systemd/,
     />\s*~\/.ssh\/authorized_keys/,
@@ -75,6 +70,98 @@ const FORBIDDEN_PATTERNS = [
     /\bchmod\s+-R\s+777\s+\//,
     /\bchown\s+-R\s.*\s\/\s*$/,
 ];
+/**
+ * Words that are forbidden when *invoked*, which the patterns above cannot
+ * express.
+ *
+ * These used to be `/\breboot\b/` and friends, matching the word anywhere in
+ * the string. `last reboot` reads a log and was refused for containing the
+ * word; so were `grep -r reboot /etc/`, `cat /var/run/reboot-required` and
+ * `journalctl | grep shutdown`. On a NAS an agent checking boot history trips
+ * this on its first command, which is how it was reported (#91).
+ *
+ * Matching an invocation rather than a mention needs to know where a command
+ * word can start, and that is a tokenizer's job, not a regex's — the regex
+ * forms that come close all reintroduce the `\S*` backtracking the block above
+ * exists to avoid.
+ */
+const FORBIDDEN_INVOCATIONS = new Set(['shutdown', 'reboot', 'halt', 'poweroff', 'eval']);
+/** Binaries that take the dangerous action as an argument: `systemctl reboot`. */
+const ACTION_MULTIPLEXERS = new Set(['systemctl', 'init', 'telinit']);
+const PRIVILEGE_PREFIXES = new Set(['sudo', 'su', 'doas', 'pkexec']);
+/**
+ * Privilege-prefix flags that consume the next argument, so `sudo -u root
+ * reboot` is not read as invoking `root`. Enumerable because it is one tool's
+ * option set, unlike "every flag of every binary".
+ */
+const PREFIX_VALUE_FLAGS = new Set([
+    '-u', '-g', '-p', '-C', '-h', '-r', '-t', '-U', '-c',
+    '--user', '--group', '--prompt', '--close-from', '--host', '--role', '--type',
+    '--other-user', '--command',
+]);
+/** `/sbin/reboot` and `reboot` are the same invocation. */
+function stripPath(word) {
+    const slash = word.lastIndexOf('/');
+    return slash === -1 ? word : word.slice(slash + 1);
+}
+/**
+ * The command words a shell would actually execute — the head of every
+ * `;`/`&&`/`||`/`|`/newline-separated segment, past any privilege prefix, plus
+ * the arguments of a multiplexer like `systemctl`.
+ *
+ * Pure string work: split, trim, set lookups. No quantifiers, so nothing here
+ * can backtrack.
+ */
+function invokedWords(command) {
+    const invoked = [];
+    for (const segment of command.split(/[;&|\n]/)) {
+        const words = segment.trim().split(/\s+/).filter(Boolean).map(stripPath);
+        let i = 0;
+        while (i < words.length && PRIVILEGE_PREFIXES.has(words[i])) {
+            i++;
+            while (i < words.length && words[i].startsWith('-')) {
+                const consumesValue = PREFIX_VALUE_FLAGS.has(words[i]);
+                i++;
+                if (consumesValue)
+                    i++;
+            }
+        }
+        const head = words[i];
+        if (!head)
+            continue;
+        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
+        // here costs little.
+        if (ACTION_MULTIPLEXERS.has(head)) {
+            invoked.push(...words.slice(i + 1).filter((w) => !w.startsWith('-')));
+        }
+    }
+    return invoked;
+}
+const FORBIDDEN_RULES = [
+    ...FORBIDDEN_PATTERNS.map((re) => ({ label: String(re), test: (c) => re.test(c) })),
+    {
+        label: 'invoking a power-state command (shutdown, reboot, halt, poweroff) or eval',
+        test: (command) => invokedWords(command).some((w) => FORBIDDEN_INVOCATIONS.has(w)),
+    },
+];
+/**
+ * Which never-allowed rule this command trips, or null. The single entry point:
+ * FORBIDDEN_PATTERNS is deliberately not exported, because half of the list
+ * lives in FORBIDDEN_RULES and a caller checking only the regexes would quietly
+ * permit `sudo reboot`.
+ */
+export function findForbiddenMatch(command) {
+    for (const rule of FORBIDDEN_RULES) {
+        if (rule.test(command))
+            return rule.label;
+    }
+    return null;
+}
+export function isForbidden(command) {
+    return findForbiddenMatch(command) !== null;
+}
 /**
  * Commands that are destructive but legitimate under approval — e.g.
  * `rm -rf /tmp/build`, which must NOT be confused with `rm -rf /`.
@@ -82,8 +169,17 @@ const FORBIDDEN_PATTERNS = [
 const DESTRUCTIVE_PATTERNS = [
     /rm\s+-rf?\s+\//,
 ];
-/** Everything that classifies as destructive: forbidden commands included. */
-const DESTRUCTIVE_DENYLIST = [...FORBIDDEN_PATTERNS, ...DESTRUCTIVE_PATTERNS];
+/**
+ * Everything that classifies as destructive: forbidden commands included.
+ *
+ * Goes through isForbidden() rather than the regex list, so a command caught by
+ * an invocation rule is classified destructive too — and, just as importantly,
+ * reading a log that mentions `reboot` is no longer classified destructive
+ * either.
+ */
+function isDestructive(command) {
+    return isForbidden(command) || DESTRUCTIVE_PATTERNS.some((re) => re.test(command));
+}
 const PRIVILEGED_INDICATORS = [
     /^\s*sudo\b/,
     /^\s*su\b/,
@@ -109,10 +205,8 @@ export function classifyCommand(command) {
     if (isPrivileged) {
         return { binary, fullCommand, class: 'privileged' };
     }
-    for (const pattern of DESTRUCTIVE_DENYLIST) {
-        if (pattern.test(trimmed)) {
-            return { binary, fullCommand, class: 'destructive' };
-        }
+    if (isDestructive(trimmed)) {
+        return { binary, fullCommand, class: 'destructive' };
     }
     const twoWordPrefix = fullCommand.split(/\s+/).slice(0, 2).join(' ');
     if (READ_ONLY_ALLOWLIST.has(binary) || READ_ONLY_ALLOWLIST.has(twoWordPrefix)) {
@@ -123,4 +217,4 @@ export function classifyCommand(command) {
     }
     return { binary, fullCommand, class: 'safe' };
 }
-export { READ_ONLY_ALLOWLIST, DESTRUCTIVE_DENYLIST, FORBIDDEN_PATTERNS };
+export { READ_ONLY_ALLOWLIST, isDestructive };

package/build/policy/engine.js

@@ -1,4 +1,4 @@
-import { classifyCommand, FORBIDDEN_PATTERNS } from './classifier.js';
+import { classifyCommand, findForbiddenMatch } from './classifier.js';
 /** Tiers, most restrictive first. Unknown/unset tiers resolve to the first. */
 export const HOST_GROUPS = ['prod', 'staging', 'dev'];
 export const DEFAULT_RULES = {
@@ -163,14 +163,14 @@ export class PolicyEngine {
     opaUrl = null;
     /** Rate-limits the fail-open warning so one outage can't flood stderr. */
     lastOpaWarning = 0;
-    /** Canonical patterns plus the operator's, compiled once at construction. */
-    denyPatterns;
+    /** The operator's patterns, compiled once. The built-ins live in classifier.ts. */
+    userPatterns;
     constructor(rules = DEFAULT_RULES) {
         this.rules = rules;
         // Compile eagerly: a deny rule that silently degrades (the old code fell
         // back to substring-matching the command against the regex *source*) is
         // worse than a startup failure, because nothing surfaces the degradation.
-        const userPatterns = (rules.denylist ?? []).map((pattern) => {
+        this.userPatterns = (rules.denylist ?? []).map((pattern) => {
             try {
                 return new RegExp(pattern);
             }
@@ -178,7 +178,6 @@ export class PolicyEngine {
                 throw new Error(`Invalid denylist pattern ${JSON.stringify(pattern)}: ${err instanceof Error ? err.message : String(err)}`);
             }
         });
-        this.denyPatterns = [...FORBIDDEN_PATTERNS, ...userPatterns];
     }
     setOpaUrl(url) {
         this.opaUrl = url;
@@ -187,13 +186,14 @@ export class PolicyEngine {
         const parsed = classifyCommand(command);
         const allowedClasses = this.getAllowedClasses(profile);
         const classAllowed = allowedClasses.includes(parsed.class);
-        if (this.matchesDenylist(command)) {
+        const denied = this.findDenyMatch(command);
+        if (denied) {
             return {
                 decision: 'deny',
                 commandClass: parsed.class,
                 binary: parsed.binary,
                 ruleId: 'denylist',
-                reason: 'Command matches denylist pattern',
+                reason: denied,
             };
         }
         const needsApproval = parsed.class === 'destructive' || parsed.class === 'privileged';
@@ -363,7 +363,28 @@ export class PolicyEngine {
         // ask-destructive and deny both gate on destructive/privileged commands.
         return needsApproval;
     }
-    matchesDenylist(command) {
-        return this.denyPatterns.some((pattern) => pattern.test(command));
+    /**
+     * Which deny rule refused this command, worded so the reader can act on it.
+     *
+     * The old message was `Command matches denylist pattern` and named nothing —
+     * not the rule, not where it came from, not whether the operator could change
+     * it. A user who hit it had no way to tell a built-in refusal from one they
+     * had written themselves (#91). explainRoleDenial already names the role, the
+     * group, the class and the allowed set; this path never got the same
+     * treatment.
+     */
+    findDenyMatch(command) {
+        const builtIn = findForbiddenMatch(command);
+        if (builtIn) {
+            return `Command matches a built-in never-allowed rule: ${builtIn}. ` +
+                `This list cannot be switched off — the [policy].denylist key adds patterns, it does not remove these.`;
+        }
+        for (const pattern of this.userPatterns) {
+            if (pattern.test(command)) {
+                return `Command matches /${pattern.source}/, a pattern from [policy].denylist in your config file. ` +
+                    `Remove or narrow it there to allow this command.`;
+            }
+        }
+        return null;
     }
 }

package/build/tools/pipeline.js

@@ -55,7 +55,12 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
                 }
                 const approval = await requestApproval(server, command, conn.profile.name, evaluation);
                 if (!approval.approved) {
-                    throw new PolicyRefusedError('APPROVAL_DENIED: User did not approve this command', evaluation);
+                    // Two different failures used to share one message. "User did not
+                    // approve" is true when the user declined and a lie when the client
+                    // could not be asked, and the reader cannot tell which they got (#91).
+                    throw new PolicyRefusedError(approval.unavailable
+                        ? `APPROVAL_UNAVAILABLE: ${approval.unavailable}`
+                        : 'APPROVAL_DENIED: User did not approve this command', evaluation);
                 }
                 grants.record(conn.profile.name, command, evaluation.commandClass);
                 return { conn, evaluation, approver: approval.approver };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
   "type": "module",
   "bin": {