ssh-mcp 2.1.0 → 2.2.0

package/README.md

@@ -3,13 +3,13 @@
 [![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)
-[![codecov](https://codecov.io/gh/tufantunc/ssh-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/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)
 
 **SSH MCP Server** is a security-first Model Context Protocol server that gives LLM agents controlled SSH access to remote hosts — with command classification, policy-based authorization, human-in-the-loop approval, and full audit logging.
 
-> **WARNING — Lethal Trifecta Risk.** Giving an LLM SSH access creates a ["Lethal Trifecta"](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) (private data + untrusted input + network egress). **Never run as root. Never enable `auto` approval on production.** See [SECURITY.md](./SECURITY.md) for the full threat model and mitigation checklist.
+> **The risk this server exists to manage.** Giving an LLM shell access on a remote host puts private data, untrusted input and network egress in one place — Simon Willison's ["lethal trifecta"](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/). Prompt injection has no general fix, so ssh-mcp assumes any command may be attacker-influenced: it classifies before executing, authorizes against a role × host-group matrix, gates destructive work behind approval, and records the decision either way. That narrows the blast radius; it does not remove the risk. Two things stay yours: **never point it at a root account**, and **never set `auto` approval on a production profile**. [SECURITY.md](./SECURITY.md) has the full threat model.
 
 ---
 
@@ -166,7 +166,7 @@ auth = "agent"                      # agent | key | password | keychain
 keyRef = "~/.ssh/id_ed25519"        # for auth=key
 keychainEntry = "ssh-mcp/prod"      # for auth=keychain (requires @napi-rs/keyring)
 via = "bastion"                     # ProxyJump — route through bastion profile
-group = "prod"                      # Policy tier: prod | staging | dev
+group = "prod"                      # Policy tier: prod | staging | dev, or your own (see [policy])
 workdir = "/var/www"
 trustedHostKey = "SHA256:..."       # Pin host key (optional)
 tty = false
@@ -177,8 +177,24 @@ cert = false                        # SSH CA cert auth — auto-detects keyRef-c
 sessionMaxPerConnection = 3         # per-profile override
 sessionIdleTimeoutMs = 300000       # stricter for prod
 commandQuotaPerDay = 200            # per-profile override
+
+# Optional. Merged over the built-in role matrix; see "Policy Engine" below.
+# roleBindings is keyed by role and then by tier, so the block below changes
+# operator on prod and leaves operator's other tiers, and viewer and admin,
+# on their defaults.
+[policy]
+denylist = ["^terraform\\s+destroy"]
+
+[policy.roleBindings.operator]
+prod = ["read-only", "safe", "destructive"]
 ```
 
+Unknown sections and keys are a startup error, not a warning, so a typo cannot
+leave you running defaults you thought you had overridden. That extends to role
+and tier names: every one you write under `[policy.roleBindings]` has to be
+reachable by some profile, and every profile's role and tier has to resolve to
+real bindings. Both directions are checked at startup.
+
 ### ProxyJump (Bastion)
 
 Reach internal hosts behind a bastion/jump server. The `via` field specifies a profile name to tunnel through:
@@ -259,9 +275,69 @@ 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`.
+### Configuring the matrix
+
+The table above is the default, not a limit. An optional `[policy]` section is
+merged over it at startup, so granting sudo on a host you have honestly
+labelled `prod` is a reviewable line in a config file rather than a relabelling:
+
+```toml
+[policy.roleBindings.admin]
+prod = ["read-only", "safe", "destructive", "privileged"]
+```
+
+The merge is at role *and* tier depth. That block changes `admin` on `prod` and
+nothing else: `admin` on `staging` and `dev` keep their defaults, and `viewer`
+and `operator` are untouched. Roles and tiers the defaults have never heard of
+are added rather than rejected, which is what makes a custom `group` resolve to
+real bindings instead of falling back to the strictest tier:
+
+```toml
+[[profiles]]
+name = "build-box"
+role = "admin"
+group = "tier-1"
+
+[policy.roleBindings.admin]
+"tier-1" = ["read-only", "safe", "destructive"]
+```
+
+Extra deny patterns live in the same section, and are applied on top of the
+never-allowed list rather than replacing it:
+
+```toml
+[policy]
+denylist = ["^terraform\\s+destroy"]
+```
+
+Because role and tier names are free strings, nothing in the merge itself can
+tell a new custom role from a misspelling of an existing one. A cross-check at
+startup does, and these all fail there rather than at the point of use:
+
+- a command class outside `read-only | safe | destructive | privileged`, so a
+  `priviledged` typo cannot parse into a grant of nothing and then read as a
+  policy decision when a command is refused;
+- any unrecognised section or key anywhere in the config, so a block the parser
+  does not understand is an error rather than a clean startup with none of the
+  behaviour you configured;
+- a role or tier under `[policy.roleBindings]` that no profile uses, so
+  `[policy.roleBindings.operater]` cannot merge in as a fourth role while the
+  profiles you meant to restrict keep running on defaults;
+- a profile whose `role` has no bindings, or whose tier has none under that
+  role, so a host cannot end up on `read-only` for a reason nobody wrote down.
+
+The last one covers the tier you did not set as well as the one you did. A
+profile with no `group` still resolves to one by name, and that inferred tier
+has to exist under the profile's role like any other.
+
+A tier with no bindings for a role grants `read-only`, and never another tier's
+classes. There is no fallback between tiers: while the matrix was compiled in,
+falling back to `prod` meant falling back to a role's strictest cell, but a
+`[policy]` block can write that cell now.
+
+An OPA sidecar is not an alternative route to the same grant. OPA is consulted
+only for commands the local policy already allows, so it can refuse more but
+never widen. Widening happens here or not at all.
 
 ### Command Classification
 
@@ -323,7 +399,11 @@ For organizations that standardize on Open Policy Agent / Rego:
 ssh-mcp --opaUrl=http://localhost:8181
 ```
 
-When `--opaUrl` is set, every command is additionally evaluated by OPA after the built-in policy engine. The request shape follows the AuthZEN Access Evaluation contract:
+When `--opaUrl` is set, commands the built-in engine allows are additionally
+evaluated by OPA. **OPA can only narrow.** A command the built-in engine has
+already denied returns that denial without OPA being consulted at all, so a
+sidecar answering `allow` cannot grant a class the role bindings withhold. To
+widen, edit `[policy]`. The request shape follows the AuthZEN Access Evaluation contract:
 
 ```json
 {
@@ -344,7 +424,8 @@ package ssh.mcp
 
 default allow := false
 
-# Admins can run anything on dev hosts
+# Admins pass the OPA gate on dev hosts. The built-in policy still applies on
+# top: this widens nothing that the role bindings withhold.
 allow if {
   input.subject.role == "admin"
   startswith(input.subject.profile, "dev")

package/build/config/loader.js

@@ -57,8 +57,11 @@ export async function loadConfig(customPath) {
     }
     const result = configSchema.safeParse(parsed);
     if (!result.success) {
+        // A root-level issue has an empty path, which used to render as a bare
+        // colon. Unreachable while the root schema accepted anything; an unknown
+        // top-level section reaches it now.
         const issues = result.error.issues
-            .map((i) => `  ${i.path.join('.')}: ${i.message}`)
+            .map((i) => `  ${i.path.length ? i.path.join('.') : '(root)'}: ${i.message}`)
             .join('\n');
         throw new Error(`Config validation error:\n${issues}`);
     }
@@ -86,7 +89,10 @@ function normalizeConfig(raw) {
         sessionBackgroundMaxMs: p.sessionBackgroundMaxMs ?? defaults.sessionBackgroundMaxMs,
         commandQuotaPerDay: p.commandQuotaPerDay ?? defaults.commandQuotaPerDay,
     }));
-    return { defaults, profiles };
+    // Passed through untouched. mergePolicyRules() owns the layering over
+    // DEFAULT_RULES, so the loader has no policy semantics of its own to get
+    // wrong.
+    return { defaults, profiles, policy: raw.policy };
 }
 export function getProfile(config, name) {
     const targetName = name || config.defaults.defaultProfile;

package/build/config/schema.js

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 const authMethodSchema = z.enum(['agent', 'key', 'password', 'keychain']);
 const approvalModeSchema = z.enum(['auto', 'ask-destructive', 'ask-all', 'deny']);
+const commandClassSchema = z.enum(['read-only', 'safe', 'destructive', 'privileged']);
+/**
+ * Role and tier names, which are free strings so operators can define their own.
+ *
+ * `__proto__` is excluded because merging assigns into a plain object, and that
+ * assignment lands on the prototype instead of creating a key: a role by that
+ * name would be accepted and then not exist. `constructor` and `prototype` are
+ * excluded alongside it rather than reasoned about case by case.
+ */
+const RESERVED_BINDING_KEYS = ['__proto__', 'constructor', 'prototype'];
+const bindingKeySchema = z.string().min(1).refine((key) => !RESERVED_BINDING_KEYS.includes(key), { message: `Reserved name (${RESERVED_BINDING_KEYS.join(', ')}). Rename the role or tier.` });
 export const defaultsSchema = z.object({
     defaultProfile: z.string().optional(),
     sessionMaxPerConnection: z.number().int().positive().default(5),
@@ -47,7 +58,30 @@ export const profileSchema = z.object({
     sessionBackgroundMaxMs: z.number().int().positive().optional(),
     commandQuotaPerDay: z.number().int().nonnegative().optional(),
 }).strict();
+/**
+ * Overrides merged over the compiled-in DEFAULT_RULES at startup.
+ *
+ * `roleBindings` is keyed role → host group → command classes, and the group
+ * key is a free string on purpose: a config that defines its own tier makes
+ * `group = "tier-1"` on a profile resolve to that tier instead of falling back
+ * to the strictest one.
+ *
+ * Command classes are validated against the enum rather than accepted as free
+ * strings, so `priviledged` fails at load instead of parsing to a grant of
+ * nothing, which reads at runtime exactly like a policy decision.
+ *
+ * `allowlist` is deliberately absent: PolicyRules declares the field but no
+ * code reads it, so accepting it here would document a key that does nothing.
+ */
+export const policySchema = z.object({
+    roleBindings: z.record(bindingKeySchema, z.record(bindingKeySchema, z.array(commandClassSchema))).optional(),
+    denylist: z.array(z.string()).optional(),
+}).strict();
+// .strict() on the root as well: without it an unknown section (a typo, or a
+// key from a newer version) parses cleanly and is dropped with no warning, so
+// the operator gets a clean startup and none of the behaviour they configured.
 export const configSchema = z.object({
     defaults: defaultsSchema.default({}),
     profiles: z.array(profileSchema).min(1),
-});
+    policy: policySchema.optional(),
+}).strict();

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, HOST_GROUPS } from './policy/engine.js';
+import { PolicyEngine, HOST_GROUPS, resolvePolicyRules } 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';
@@ -160,7 +160,7 @@ async function main() {
         await initTracing(argv.otelEndpoint, argv.otelServiceName || 'ssh-mcp');
     }
     const registry = new ConnectionRegistry(config, hostKeyMode);
-    const policy = new PolicyEngine(DEFAULT_RULES);
+    const policy = new PolicyEngine(resolvePolicyRules(config.profiles, config.policy));
     const audit = new AuditStore(undefined, entropyScan, tamperEvident);
     if (argv.opaUrl) {
         policy.setOpaUrl(argv.opaUrl);

package/build/policy/engine.js

@@ -20,6 +20,144 @@ export const DEFAULT_RULES = {
         },
     },
 };
+/**
+ * Layer an operator's `[policy]` section over the compiled-in defaults.
+ *
+ * The merge is at role → group depth, not role depth. Replacing a whole role's
+ * bindings from a partial table is the trap here: a config naming only
+ * `admin.prod` would otherwise wipe `admin.staging` and `admin.dev` back to
+ * nothing, widening or narrowing two tiers the operator never mentioned.
+ *
+ * Roles and groups absent from the override keep their defaults, and a role or
+ * tier the defaults have never heard of is added rather than rejected. That is
+ * what makes a custom `group = "tier-1"` resolve to real bindings.
+ *
+ * `denylist` replaces rather than appends, because the defaults carry none and
+ * FORBIDDEN_PATTERNS is applied on top by the engine regardless.
+ *
+ * With nothing to layer, `base` is returned as-is rather than copied. The
+ * result is read-only either way — PolicyEngine only reads `rules`, and the
+ * copying below exists so a *later* merge cannot reach DEFAULT_RULES through a
+ * shared tier object, not because callers are expected to mutate what they get.
+ */
+export function mergePolicyRules(base, override) {
+    if (!override?.roleBindings && !override?.denylist)
+        return base;
+    // Copy every tier map: assigning base's objects straight through would let a
+    // later merge mutate DEFAULT_RULES, which is a module-level singleton.
+    const roleBindings = {};
+    for (const [role, groups] of Object.entries(base.roleBindings)) {
+        roleBindings[role] = { ...groups };
+    }
+    for (const [role, groups] of Object.entries(override.roleBindings ?? {})) {
+        roleBindings[role] = { ...(roleBindings[role] ?? {}), ...groups };
+    }
+    return {
+        roleBindings,
+        denylist: override.denylist ?? base.denylist,
+    };
+}
+/**
+ * Which tier's role binding applies to this profile.
+ *
+ * `profile.group` is authoritative. Without it we still infer from the name
+ * for convenience, but an unrecognised name resolves to the most restrictive
+ * tier: the previous default sent every unrecognised profile to `dev`, so a
+ * production host merely named "web-01" silently received the loosest
+ * permissions in the matrix.
+ *
+ * Exported rather than kept private because startup validation has to reach the
+ * same answer the engine will reach, inference included. Checking only the
+ * explicit `group` would pass every profile that never set one, which is where
+ * the widening below actually happens.
+ */
+export function resolveProfileGroup(profile) {
+    if (profile.group)
+        return profile.group;
+    const name = profile.name.toLowerCase();
+    if (name.includes('prod'))
+        return 'prod';
+    if (name.includes('staging'))
+        return 'staging';
+    if (/\b(dev|local|test|sandbox)\b/.test(name) || /(^|[-_])(dev|local|test|sandbox)([-_]|$)/.test(name)) {
+        return 'dev';
+    }
+    return HOST_GROUPS[0];
+}
+/**
+ * Every way a config's policy can mean something other than what it says.
+ *
+ * Checked in both directions, because a silent no-op is reachable from either:
+ * a profile can name a role or tier that nothing defines, and a `[policy]`
+ * block can define a role or tier that no profile can reach. #95 was the second
+ * kind (written, parsed, dropped), and the first kind lands on `['read-only']`,
+ * which at runtime is indistinguishable from a deliberate policy decision.
+ *
+ * The `[policy]` side is checked against `override`, never the merged table:
+ * the merge carries the three compiled-in roles, and no real config references
+ * all of them.
+ *
+ * Returns every problem rather than the first, matching the config validation
+ * error in loader.ts. An operator fixing a config file wants the whole list.
+ */
+export function findPolicyProblems(merged, profiles, override) {
+    const problems = [];
+    for (const profile of profiles) {
+        const roleBinding = merged.roleBindings[profile.role];
+        if (!roleBinding) {
+            problems.push(`profile "${profile.name}": role "${profile.role}" has no role bindings, so it can only ever ` +
+                `run read-only commands. Define [policy.roleBindings.${profile.role}], or set role to one of: ` +
+                `${Object.keys(merged.roleBindings).join(', ')}.`);
+            continue;
+        }
+        const group = resolveProfileGroup(profile);
+        if (roleBinding[group])
+            continue;
+        const tiers = Object.keys(roleBinding).join(', ');
+        problems.push(profile.group
+            ? `profile "${profile.name}": role "${profile.role}" has no bindings for group "${group}". ` +
+                `Add a "${group}" key under [policy.roleBindings.${profile.role}], or set group to one of: ${tiers}.`
+            : `profile "${profile.name}": no group is set, so the tier is inferred from the name as "${group}", ` +
+                `and role "${profile.role}" has no bindings for it. Set group explicitly to one of: ${tiers}, ` +
+                `or add a "${group}" key under [policy.roleBindings.${profile.role}].`);
+    }
+    const rolesInUse = [...new Set(profiles.map((p) => p.role))];
+    for (const [role, tiers] of Object.entries(override?.roleBindings ?? {})) {
+        if (!rolesInUse.includes(role)) {
+            problems.push(`[policy.roleBindings.${role}]: no profile uses role "${role}", so this block changes nothing. ` +
+                `Roles in use: ${rolesInUse.join(', ')}.`);
+        }
+        for (const tier of Object.keys(tiers)) {
+            if (HOST_GROUPS.includes(tier))
+                continue;
+            if (profiles.some((p) => p.group === tier))
+                continue;
+            problems.push(`[policy.roleBindings.${role}]: key "${tier}" matches no profile's group and is not a built-in ` +
+                `tier (${HOST_GROUPS.join(', ')}), so it changes nothing. Set group = "${tier}" on a profile, ` +
+                `or remove the key.`);
+        }
+    }
+    return problems;
+}
+/**
+ * The rules main() runs on: the compiled-in defaults, the operator's overrides
+ * layered on top, and a refusal to start when the two do not describe the same
+ * world.
+ *
+ * Refusing rather than warning. A warning here goes to stderr, which for a
+ * stdio MCP server means a log file the operator is not reading, and "written,
+ * ignored, nothing said" is the whole of #95.
+ */
+export function resolvePolicyRules(profiles, override) {
+    const merged = mergePolicyRules(DEFAULT_RULES, override);
+    const problems = findPolicyProblems(merged, profiles, override);
+    if (problems.length > 0) {
+        throw new Error('Policy configuration error:\n' +
+            problems.map((p) => `  ${p}`).join('\n') +
+            '\nSee the "Configuring the matrix" section of the README.');
+    }
+    return merged;
+}
 export class PolicyEngine {
     rules;
     opaUrl = null;
@@ -161,24 +299,29 @@ export class PolicyEngine {
      * 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.
+     * The inferred case matters most: a profile with no group set has its tier
+     * guessed from its name, 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 group = resolveProfileGroup(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) {
+            // Not "defaulted to the most restrictive tier": the name is matched
+            // against prod/staging/dev first, so a profile called "staging-web" lands
+            // on staging and the old wording described a fallback that did not
+            // happen. What the operator needs to know is that nothing they wrote
+            // chose this tier.
             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.`;
+                ` No group is set for profile "${profile.name}", so the tier was inferred from its name as "${group}".` +
+                    ` Set group explicitly on the profile, or pass --group, if that is not where this host belongs.`;
         }
         else {
             reason += ` Change the profile's group, or grant the class to this role in the policy's roleBindings.`;
@@ -193,31 +336,19 @@ export class PolicyEngine {
         if (!roleBinding) {
             return ['read-only'];
         }
-        const hostGroup = this.resolveHostGroup(profile);
-        // Falls back to the most restrictive tier, never to the loosest one.
-        return roleBinding[hostGroup] || roleBinding[HOST_GROUPS[0]] || ['read-only'];
-    }
-    /**
-     * Which tier's role binding applies to this profile.
-     *
-     * `profile.group` is authoritative. Without it we still infer from the name
-     * for convenience, but an unrecognised name resolves to the most restrictive
-     * tier: the previous default sent every unrecognised profile to `dev`, so a
-     * production host merely named "web-01" silently received the loosest
-     * permissions in the matrix.
-     */
-    resolveHostGroup(profile) {
-        if (profile.group)
-            return profile.group;
-        const name = profile.name.toLowerCase();
-        if (name.includes('prod'))
-            return 'prod';
-        if (name.includes('staging'))
-            return 'staging';
-        if (/\b(dev|local|test|sandbox)\b/.test(name) || /(^|[-_])(dev|local|test|sandbox)([-_]|$)/.test(name)) {
-            return 'dev';
-        }
-        return HOST_GROUPS[0];
+        // No hop to another tier when this one has no bindings. While roleBindings
+        // were compiled in, falling back to HOST_GROUPS[0] meant falling back to
+        // that role's *strictest* cell, so the old comment here was true. Once a
+        // [policy] block can write the prod cell, the same hop hands an unresolved
+        // tier whatever prod was granted. That is a widening, and a silent one.
+        //
+        // An unresolved tier is a startup error now (resolvePolicyRules), so
+        // reaching this line means the engine was constructed directly rather than
+        // from a config file. Fail closed.
+        //
+        // `??` rather than `||`: an empty class list is a deliberate lockdown, and
+        // whether it survives should not rest on `[]` being truthy.
+        return roleBinding[resolveProfileGroup(profile)] ?? ['read-only'];
     }
     /**
      * Whether this command trips the profile's approval gate. What happens at the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
   "type": "module",
   "bin": {
@@ -41,17 +41,14 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.31.0",
-    "@types/node": "^24.5.2",
+    "@types/node": "^26.2.0",
     "@types/ssh2": "^1.15.5",
-    "@vitest/coverage-v8": "^3.2.7",
-    "cross-env": "^7.0.3",
-    "fast-check": "^3.23.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    "cross-env": "^10.1.0",
+    "fast-check": "^4.9.0",
     "shx": "^0.4.0",
-    "testcontainers": "^11.7.0",
-    "ts-node": "^10.9.2",
-    "tsx": "^4.20.6",
     "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.10"
   },
   "homepage": "https://github.com/tufantunc/ssh-mcp#readme",
   "repository": {