ssh-mcp 2.4.0 → 2.4.2

package/README.md

@@ -3,6 +3,7 @@
 [![NPM Version](https://img.shields.io/npm/v/ssh-mcp)](https://www.npmjs.com/package/ssh-mcp)
 [![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.securityscorecards.dev/projects/github.com/tufantunc/ssh-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/tufantunc/ssh-mcp)
 [![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)
@@ -523,6 +524,45 @@ deny if {
 
 See [SECURITY.md](./SECURITY.md) for the full threat model, vulnerability reporting policy, and deployment checklist.
 
+### Supply chain
+
+Releases carry signed attestations, published through [Sigstore](https://www.sigstore.dev/)
+and recorded in its public transparency log. They live in **two different stores**, which is
+what decides how each is verified:
+
+| Attestation | Predicate | Stored by | Since |
+|---|---|---|---|
+| Build provenance — [SLSA](https://slsa.dev/) Build **Level 2** | `slsa.dev/provenance/v1` | npm | every release |
+| SBOM — CycloneDX and SPDX | `cyclonedx.org/bom`, `spdx.dev/Document` | GitHub | releases after v2.4.0 |
+
+Provenance comes from npm [trusted publishing](https://docs.npmjs.com/trusted-publishers):
+the release workflow authenticates with a short-lived OIDC token and no stored credential,
+so there is no long-lived npm token to leak.
+
+```bash
+npm audit signatures        # provenance, against an installed tree
+
+npm pack ssh-mcp            # the SBOM attestation is bound to the tarball, so fetch it
+gh attestation verify ssh-mcp-*.tgz --repo tufantunc/ssh-mcp --predicate-type https://cyclonedx.org/bom
+```
+
+Both flags on the last command are load-bearing. `gh attestation verify` defaults to the
+SLSA predicate, so without `--predicate-type` it filters the SBOM out and reports nothing
+found — and the provenance it would look for instead is in npm's store, not the GitHub
+store `--repo` queries. Use `https://spdx.dev/Document` for the SPDX one.
+
+Both SBOMs are also attached to each
+[GitHub release](https://github.com/tufantunc/ssh-mcp/releases), for reading rather than
+verifying.
+
+**Level 2, not 3.** Provenance is signed by the generic GitHub-hosted runner —
+`builder.id` is `https://github.com/actions/runner/github-hosted` — which the build itself
+can influence; Build L3 requires an isolated builder it cannot. Reaching L3 is not
+currently compatible with trusted publishing: npm turns on its own provenance whenever that
+setting is left at its default, and then ignores any externally generated one. So L3 today
+would mean returning to a long-lived npm token — trading the property described above for a
+level number.
+
 ### Safe Defaults
 
 - **Non-root** user in all examples
@@ -735,3 +775,9 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md). Please follow the [security checklist]
 ## Support
 
 If you find SSH MCP Server helpful, consider starring the repository or [sponsoring](https://github.com/sponsors/tufantunc)!
+
+## Listed on
+
+[![SSH MCP Server on Glama](https://glama.ai/mcp/servers/tufantunc/ssh-mcp/badge)](https://glama.ai/mcp/servers/tufantunc/ssh-mcp)
+
+Also on the [official MCP registry](https://registry.modelcontextprotocol.io) as `io.github.tufantunc/ssh-mcp`.

package/build/policy/classifier.js

@@ -122,6 +122,134 @@ const ACTION_MULTIPLEXERS = new Set(['systemctl', 'init', 'telinit']);
  * control inside a security release. `gosu` and `run0` were never caught by
  * either form.
  */
+/**
+ * Class ordering, so a command that contains another can take the higher of the two.
+ *
+ * Only used by the nesting scan below. Everything else in this file decides a single
+ * class outright.
+ */
+const CLASS_RANK = {
+    'read-only': 0,
+    safe: 1,
+    destructive: 2,
+    privileged: 3,
+};
+/** Shells that run their next argument as a command when given `-c`. */
+const SHELL_BINARIES = new Set([
+    'sh', 'bash', 'dash', 'zsh', 'ksh', 'ash', 'busybox',
+]);
+/**
+ * How deep a substitution may nest before we stop reading and refuse to guess.
+ *
+ * Reached only by input no operator writes — the tests use two hundred levels. The
+ * fallback is `privileged` rather than a lower class because the entire point of
+ * this scan is that a command we cannot read must not be treated as one we can.
+ */
+const MAX_NESTING_DEPTH = 8;
+/**
+ * Split on whitespace the way a shell would, keeping quoted runs together.
+ *
+ * `parseSegments` splits on `/\s+/`, which turns `sh -c "sudo id"` into
+ * `["sh", "-c", "\"sudo", "id\""]` — the argument is no longer a unit, so nothing
+ * downstream can classify it as the command it is.
+ */
+function splitRespectingQuotes(command) {
+    const words = [];
+    let current = '';
+    let quote = null;
+    for (const ch of command) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else
+                current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (current)
+                words.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    if (current)
+        words.push(current);
+    return words;
+}
+/**
+ * The commands hiding inside a command.
+ *
+ * The elevation scan reads tokens produced by splitting on `;&|` and whitespace, so
+ * it only ever saw the outer command: `echo $(sudo id)` tokenised to
+ * `["echo", "$(sudo", "id)"]`, `echo` was taken to be the real command, and no
+ * elevation was found (GHSA-v8jh-gv7v-3gvq). The destructive scan never had this
+ * problem because it reads the raw text — which is why `echo $(rm -rf /)` was
+ * classified correctly the whole time. This closes that asymmetry by pulling the
+ * inner commands out so they can be classified in their own right.
+ *
+ * Four carriers, all of which a remote shell expands and runs:
+ *   `$(...)`, backticks, process substitution `<(...)` / `>(...)`, and a shell
+ *   given `-c`.
+ */
+export function nestedCommands(command) {
+    const found = [];
+    // `$(...)`, `<(...)`, `>(...)` — scanned rather than matched, because a regex
+    // cannot balance parentheses and `echo $(echo $(sudo id))` is the case that
+    // matters most.
+    for (let i = 0; i < command.length; i++) {
+        const opensSubstitution = command[i] === '$' && command[i + 1] === '(';
+        const opensProcess = (command[i] === '<' || command[i] === '>') && command[i + 1] === '(';
+        if (!opensSubstitution && !opensProcess)
+            continue;
+        // `$((1 + 1))` is arithmetic, not a command. Skipping it keeps the approval
+        // prompt off `echo $((1 + 1))`.
+        if (opensSubstitution && command[i + 2] === '(')
+            continue;
+        let depth = 0;
+        for (let j = i + 1; j < command.length; j++) {
+            if (command[j] === '(')
+                depth++;
+            else if (command[j] === ')') {
+                depth--;
+                if (depth === 0) {
+                    found.push(command.slice(i + 2, j));
+                    i = j;
+                    break;
+                }
+            }
+        }
+    }
+    // Backticks. No nesting to balance — the shell requires escaping to nest them.
+    const backticks = command.match(/`([^`]*)`/g);
+    if (backticks) {
+        for (const raw of backticks)
+            found.push(raw.slice(1, -1));
+    }
+    // `sh -c <command>`. Carries no substitution at all, so the scan above does not
+    // see it; found while mapping the reported bypass rather than in the report.
+    const words = splitRespectingQuotes(command);
+    for (let i = 0; i < words.length; i++) {
+        if (!SHELL_BINARIES.has(stripPath(unquote(words[i]))))
+            continue;
+        for (let j = i + 1; j < words.length; j++) {
+            if (words[j] === '-c') {
+                if (words[j + 1] !== undefined)
+                    found.push(words[j + 1]);
+                break;
+            }
+            // Only flags may sit between the shell and its `-c`; anything else means
+            // this was not a `-c` invocation.
+            if (!words[j].startsWith('-'))
+                break;
+        }
+    }
+    return found.filter((c) => c.trim().length > 0);
+}
 const PRIVILEGE_PREFIXES = new Set([
     'sudo', 'su', 'doas', 'pkexec',
     // BusyBox/Alpine, Docker entrypoints, the Rust sudo now default on some
@@ -356,11 +484,25 @@ const FORBIDDEN_RULES = [
  * lives in FORBIDDEN_RULES and a caller checking only the regexes would quietly
  * permit `sudo reboot`.
  */
-export function findForbiddenMatch(command) {
+export function findForbiddenMatch(command, depth = 0) {
     for (const rule of FORBIDDEN_RULES) {
         if (rule.test(command))
             return rule.label;
     }
+    // The same carriers the class scan reads, for the same reason. This list is the
+    // one unconditional rule in the policy — forbidden regardless of role, tier or
+    // approval — and it was decided from the outer command alone, so
+    // `sh -c "shutdown -h now"` and `echo $(shutdown -h now)` were not forbidden.
+    // They still classified `destructive`, which on the `prod` tier degrades an
+    // absolute `deny` into `require-approval`: a rule that answers "never" became
+    // one a human can click through.
+    if (depth >= MAX_NESTING_DEPTH)
+        return null;
+    for (const inner of nestedCommands(command)) {
+        const match = findForbiddenMatch(inner, depth + 1);
+        if (match !== null)
+            return match;
+    }
     return null;
 }
 export function isForbidden(command) {
@@ -401,10 +543,97 @@ export function extractBinary(command) {
     const parts = cmd.split(/\s+/);
     return parts[0] || '';
 }
-export function classifyCommand(command) {
+/**
+ * The word a segment will actually execute, read past anything that is not it.
+ *
+ * Distinct from `elevatedBinary`, which answers "does this ask for elevation".
+ * This answers "what is the name of the thing that runs", so it can be asked
+ * whether that name is knowable at all.
+ */
+function effectiveCommandWord(words) {
+    let i = 0;
+    while (i < words.length) {
+        const raw = words[i];
+        const word = stripPath(unquote(raw));
+        if (PRIVILEGE_PREFIXES.has(word) || EXEC_WRAPPERS.has(word)) {
+            i++;
+            while (i < words.length && words[i].startsWith('-')) {
+                const consumesValue = PREFIX_VALUE_FLAGS.has(words[i]);
+                i++;
+                if (consumesValue)
+                    i++;
+            }
+            continue;
+        }
+        if (ASSIGNMENT.test(raw) || raw.startsWith('-') || BARE_NUMERIC.test(raw)) {
+            i++;
+            continue;
+        }
+        return raw;
+    }
+    return null;
+}
+/**
+ * Whether any segment runs a command this process cannot name.
+ *
+ * The class — and with it the approval gate — is decided from the literal text of
+ * the command word. A word carrying `$` or a backtick is a name the shell resolves
+ * at run time, so `$S id` was classified as though `$S` were a binary, and came
+ * out `safe` (GHSA-fj9r-f47j-c73x).
+ *
+ * Resolving the variable is not the answer and cannot be: a session run keeps the
+ * caller's shell state, so `S=sudo` and `$S id` can arrive as two separate calls,
+ * and a variable exported in the target's own profile is never visible here at
+ * all. What is answerable is whether we know the name — and when we do not, saying
+ * so is the only honest class.
+ *
+ * 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 raw of command.split(/[;&|\n]/)) {
+        const words = raw.trim().split(/\s+/).filter(Boolean);
+        const head = effectiveCommandWord(words);
+        if (head !== null && /[$`]/.test(head))
+            return true;
+    }
+    return false;
+}
+export function classifyCommand(command, depth = 0) {
     const trimmed = command.trim();
     const binary = extractBinary(trimmed);
     const fullCommand = trimmed;
+    // A command that carries another command decides nothing on its own: the remote
+    // shell expands `$(...)`, backticks, `<(...)` and `sh -c` and runs what is inside,
+    // so the class has to be the higher of the two. Before this, the outer command
+    // decided alone and `echo $(sudo id)` was `safe` — a class the default rules grant
+    // on `prod` to `operator` and `admin`, while granting `privileged` there to nobody
+    // at all (GHSA-v8jh-gv7v-3gvq). It also skipped the approval prompt, since only
+    // `destructive` and `privileged` raise one, and the audit record said `safe`.
+    //
+    // Runs before the checks below rather than after, so the class it produces is not
+    // something a later branch can lower.
+    if (depth < MAX_NESTING_DEPTH) {
+        let highest = null;
+        for (const inner of nestedCommands(trimmed)) {
+            const parsed = classifyCommand(inner, depth + 1);
+            if (highest === null || CLASS_RANK[parsed.class] > CLASS_RANK[highest.class]) {
+                highest = parsed;
+            }
+        }
+        // `binary` comes from the inner command 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.
+        if (highest !== null && CLASS_RANK[highest.class] > CLASS_RANK['safe']) {
+            return { binary: highest.binary, fullCommand, class: highest.class };
+        }
+    }
+    else {
+        // 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 function.
+        return { binary, fullCommand, class: 'privileged' };
+    }
     // `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.
@@ -415,6 +644,17 @@ export function classifyCommand(command) {
     if (isDestructive(trimmed) || hasDisqualifyingArgs(trimmed)) {
         return { binary, fullCommand, class: 'destructive' };
     }
+    // Below this point every branch assumes the command word names something we
+    // recognised. When it is a variable expansion it names nothing we can check, so
+    // the allowlist must not be consulted — `$S` is not on it, and falling through to
+    // the default made an unknown command `safe`.
+    //
+    // `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)) {
+        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)) {
         if (SHELL_CONTROL_CHARS.test(trimmed)) {

package/package.json

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