ssh-mcp 2.0.3 → 2.1.0

package/README.md

@@ -244,6 +244,25 @@ without it the tier is guessed from the profile name (`prod`/`staging`/`dev`,
 the strictest tier. A production host named `web-01` is therefore treated as
 production rather than silently getting dev permissions.
 
+Note what this means for `sudo`: **`admin` has no `privileged` on `prod`**, so
+`privileged-command` is refused there by design — including on a quick-start
+profile, which has no name to infer from and therefore lands on `prod`. If the
+host is not production, say so:
+
+```bash
+npx ssh-mcp --host=10.0.0.5 --user=deploy --group=dev
+```
+
+```toml
+[[profiles]]
+name = "build-box"
+group = "dev"
+```
+
+Leaving a real production host on `prod` and granting sudo there is a policy
+change, not a flag: add `privileged` to `admin.prod` in the config's
+`roleBindings`.
+
 ### Command Classification
 
 Every command is classified before execution:
@@ -439,6 +458,7 @@ Secrets are **never** passed as CLI arguments.
 | `--port` | 22 | Quick start: SSH port |
 | `--key` | — | Quick start: Path to private key |
 | `--workdir` | — | Quick start: Working directory for commands and sessions |
+| `--group` | prod | Quick start: Policy tier — `prod`, `staging` or `dev` |
 | `--timeout` | 60000 | Command timeout in ms |
 | `--maxChars` | 5000 | Max command length (`none` or `0` disables the limit) |
 | `--sessionMax` | 5 | Max concurrent sessions per connection |

package/build/index.js

@@ -3,7 +3,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { loadConfig } from './config/loader.js';
 import { ConnectionRegistry } from './ssh/connection-registry.js';
-import { PolicyEngine, DEFAULT_RULES } from './policy/engine.js';
+import { PolicyEngine, DEFAULT_RULES, HOST_GROUPS } from './policy/engine.js';
 import { AuditStore } from './audit/store.js';
 import { registerTools, registerResources, getToolHashes } from './tools/registry.js';
 import { initKeychain } from './config/credential-resolver.js';
@@ -71,6 +71,27 @@ function resolveHostKeyMode(argv) {
         return mode;
     throw new Error(`Invalid --hostKeyMode=${mode}. Expected one of: tofu, strict, insecure.`);
 }
+/**
+ * Which policy tier a CLI-configured host belongs to.
+ *
+ * Without this there was no way to say it from the command line at all. The
+ * inline profile carries no group, so it fell to the strictest tier, where the
+ * `admin` role has no `privileged` — meaning `sudo` could never run for anyone
+ * who had not written a config file (#91).
+ *
+ * The default stays `prod`. Guessing an unknown host is production is the safe
+ * direction; what was missing was a way to correct the guess.
+ */
+export function resolveHostGroup(argv) {
+    const group = argv.group;
+    if (group === null || group === undefined)
+        return 'prod';
+    if (HOST_GROUPS.includes(group))
+        return group;
+    // Falling through would silently apply the prod bindings to a typo, and the
+    // operator would read the refusal as policy rather than as their own slip.
+    throw new Error(`Invalid --group=${group}. Expected one of: ${HOST_GROUPS.join(', ')}.`);
+}
 async function buildAppConfig(argv) {
     if (argv.config) {
         return loadConfig(argv.config);
@@ -111,6 +132,7 @@ async function buildAppConfig(argv) {
         maxChars: defaults.commandMaxChars,
         maxOutputBytes: defaults.commandMaxOutputBytes,
         role: 'admin',
+        group: resolveHostGroup(argv),
         readOnly: false,
         approvalPolicy: argv.disableApproval ? 'auto' : defaults.approvalMode,
         cert: false,

package/build/policy/classifier.js

@@ -1,3 +1,21 @@
+/**
+ * Anything through which the shell can start a second command.
+ *
+ * This gate decides whether an allowlisted binary counts as read-only, and the
+ * allowlist only vouches for the binary — never for what a shell might run
+ * beside it. It used to test /[>;|]/, which let `ls $(touch /tmp/x)` through as
+ * read-only: `ls` is allowlisted, no listed metacharacter appears, and the
+ * remote shell expands the substitution and runs the inner command anyway
+ * (GHSA-r8hm-vpm8-cfh6).
+ *
+ * Listing every dangerous construct is a losing game — `$()`, backticks,
+ * `<(...)`, `${x:=...}`, `&&`, a bare newline — so this refuses every character
+ * with syntactic meaning to the shell instead, and `$` wholesale rather than
+ * just `$(`. The cost is that `echo $HOME` is no longer classified read-only.
+ * That is the right trade for the tool whose entire promise is that it cannot
+ * write: run-command still accepts it under policy.
+ */
+const SHELL_CONTROL_CHARS = /[;&|<>`$(){}\n\r]/;
 const READ_ONLY_ALLOWLIST = new Set([
     'ls', 'cat', 'grep', 'find', 'stat', 'df', 'du', 'head', 'tail', 'wc',
     'ps', 'uname', 'uptime', 'hostname', 'id', 'who', 'whoami', 'date',
@@ -98,7 +116,7 @@ export function classifyCommand(command) {
     }
     const twoWordPrefix = fullCommand.split(/\s+/).slice(0, 2).join(' ');
     if (READ_ONLY_ALLOWLIST.has(binary) || READ_ONLY_ALLOWLIST.has(twoWordPrefix)) {
-        if (/[>;|]/.test(trimmed)) {
+        if (SHELL_CONTROL_CHARS.test(trimmed)) {
             return { binary, fullCommand, class: 'safe' };
         }
         return { binary, fullCommand, class: 'read-only' };

package/build/policy/engine.js

@@ -1,6 +1,6 @@
 import { classifyCommand, FORBIDDEN_PATTERNS } from './classifier.js';
 /** Tiers, most restrictive first. Unknown/unset tiers resolve to the first. */
-const HOST_GROUPS = ['prod', 'staging', 'dev'];
+export const HOST_GROUPS = ['prod', 'staging', 'dev'];
 export const DEFAULT_RULES = {
     roleBindings: {
         viewer: {
@@ -66,7 +66,7 @@ export class PolicyEngine {
                 commandClass: parsed.class,
                 binary: parsed.binary,
                 ruleId: 'role-binding',
-                reason: `Role "${profile.role}" cannot run "${parsed.class}" commands`,
+                reason: this.explainRoleDenial(profile, parsed.class),
             };
         }
         if (approvalRequired) {
@@ -152,6 +152,39 @@ export class PolicyEngine {
         console.error(`POLICY WARNING: OPA evaluation unavailable (${cause}). ` +
             'Falling back to local policy — commands OPA would deny may now be allowed.');
     }
+    /**
+     * Say which three things produced the refusal, not one of them.
+     *
+     * The message used to read `Role "admin" cannot run "privileged" commands`,
+     * which names the role and the class but not the host group — and the group
+     * is usually what decided, because `admin` has `privileged` on staging and
+     * dev but not on prod. A reader concludes their role is simply incapable of
+     * sudo and goes looking for a bigger role that does not exist (#91).
+     *
+     * The inferred case matters most: a profile with no group set lands on the
+     * strictest tier, so the reason is something the operator never wrote down
+     * anywhere and cannot see.
+     */
+    explainRoleDenial(profile, commandClass) {
+        if (profile.readOnly) {
+            return `Profile "${profile.name}" is read-only, so "${commandClass}" commands are refused. ` +
+                `Clear readOnly on the profile to allow them.`;
+        }
+        const group = this.resolveHostGroup(profile);
+        const inferred = !profile.group;
+        const allowed = this.getAllowedClasses(profile).join(', ');
+        let reason = `Role "${profile.role}" on host group "${group}" cannot run "${commandClass}" commands ` +
+            `(allowed: ${allowed}).`;
+        if (inferred) {
+            reason +=
+                ` No group is set for profile "${profile.name}", so it defaulted to the most restrictive tier.` +
+                    ` Set group = "dev" or "staging" on the profile, or pass --group, if this host is not production.`;
+        }
+        else {
+            reason += ` Change the profile's group, or grant the class to this role in the policy's roleBindings.`;
+        }
+        return reason;
+    }
     getAllowedClasses(profile) {
         if (profile.readOnly) {
             return ['read-only'];

package/package.json

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