ssh-mcp 2.5.1 → 2.7.0

package/README.md

@@ -152,8 +152,8 @@ claude mcp add --transport stdio ssh-mcp -- ssh-mcp
 | `close-session` | Close a session. A background session's command is signalled (INT/TERM/KILL) before its channel is dropped | — | ✅ |
 | `read-session-output` | Read output from background sessions (e.g., `tail -f`) | ✅ | — |
 | `read-command` | Execute allowlisted read-only commands (`ls`, `cat`, `grep`, ...) | ✅ | — |
-| `run-command` | Execute arbitrary commands (destructive ones need approval) | — | — |
-| `privileged-command` | Execute with sudo (always requires approval) | — | ✅ |
+| `run-command` | Execute arbitrary commands (destructive/privileged need approval, unless `approvalPolicy = "auto"`) | — | — |
+| `privileged-command` | Execute with sudo (needs approval, unless `approvalPolicy = "auto"`) | — | ✅ |
 | `sftp-upload` | Upload a file via SFTP | — | ✅ |
 | `sftp-download` | Download a file via SFTP | ✅ | — |
 | `signal-process` | Send INT/TERM/KILL to a remote PID | — | ✅ |
@@ -422,7 +422,13 @@ denylist; an invalid pattern fails at startup rather than degrading silently.
 ### Approval Modes
 
 - `auto` — no prompts (dev only!)
-- `ask-destructive` — prompt for destructive/privileged (default)
+- `ask-destructive` — prompt for destructive/privileged (default). Narrower than it sounds:
+  outside the never-allowed list, `destructive` is one `rm -rf /path` pattern, `find` with a
+  write/exec flag, an unresolvable command word, a program handed to an interpreter this
+  server cannot read (`python3 -c`, `perl -e`, `node -e`, a program arriving on a pipe —
+  but not `awk`, whose program is not read), and `sftp-upload`/interactive `open-session` — elevation classifies `privileged`, which also
+  prompts. Ordinary writes, service control and signals do not. See
+  [SECURITY.md](./SECURITY.md) before relying on this in production.
 - `ask-all` — prompt for every command
 - `deny` — reject destructive/privileged commands outright (no prompt)
 
@@ -481,7 +487,17 @@ 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:
+widen, edit `[policy]`.
+
+An outage falls back to the local decision and logs one warning per minute. That is the
+default because OPA is an *additional* deny layer and stopping all work would be the worse
+failure — but an operator who deployed OPA *as* the authorization gate loses that gate
+during the outage, and the only signal is a stderr line MCP clients usually discard.
+`--opaFailClosed` makes the gate being down mean no; the refusal carries `ruleId:
+"opa-unavailable"` so the audit record says the gate was down rather than implying a policy
+refused the command.
+
+The request shape follows the AuthZEN Access Evaluation contract:
 
 ```json
 {
@@ -494,7 +510,7 @@ widen, edit `[policy]`. The request shape follows the AuthZEN Access Evaluation
 }
 ```
 
-OPA responds with `{ "result": true/false }`. If OPA denies (`result: false`), the command is blocked even if the built-in engine allows it. If OPA is unreachable, the built-in engine's decision stands (fail-open to avoid locking out access).
+OPA responds with `{ "result": true/false }`. If OPA denies (`result: false`), the command is blocked even if the built-in engine allows it. If OPA is unreachable, the built-in engine's decision stands by default (fail-open, to avoid locking out access); `--opaFailClosed` refuses instead. A 200 that carries no boolean `result` counts as unreachable — that is what OPA answers for an undefined document, so a misnamed package or an unactivated bundle is an outage rather than consent.
 
 Example Rego policy (`ssh-mcp.rego`):
 ```rego
@@ -566,7 +582,7 @@ level number.
 ### Safe Defaults
 
 - **Non-root** user in all examples
-- **TOFU** host key verification (accept on first connect, verify after)
+- **TOFU** host key verification (accept on first connect, verify after — within one process; see [SECURITY.md](./SECURITY.md#host-key-trust-does-not-survive-a-restart))
 - **RFC 9142** algorithm allow-list (no SHA-1, no CBC, no ssh-rsa)
 - **exec()-only** (no persistent su shells — fixes PTY leak)
 - **Sudo via stdin** (not argv — fixes process list leak)
@@ -612,6 +628,9 @@ ssh-mcp --transport=http --httpPort=3000 --bearerToken=secret --rateLimit=60
 | `--httpPort` | 3000 | HTTP listen port |
 | `--httpHost` | 127.0.0.1 | Bind address |
 | `--rateLimit` | 0 (off) | Max requests per minute (0 = unlimited) |
+| `--authFailureLimit` | 10 | Failed bearer-auth attempts allowed per client per minute (0 = off) |
+| `--trustProxy` | false | Read the client address from `X-Forwarded-For`, but only when the peer is the proxy — bare means a loopback peer |
+| `--trustedProxies` | — | Comma-separated peer addresses allowed to send `X-Forwarded-For`. Empty means loopback only |
 
 Endpoints: `POST /` (MCP Streamable HTTP), `GET /status`, `GET /health`
 
@@ -623,6 +642,25 @@ bearer token.
 
 When rate limit is exceeded, the server returns HTTP 429 with `Retry-After` header and a JSON-RPC error body so MCP clients can handle it gracefully.
 
+Failed authentication is throttled separately, and on by default. `--rateLimit` never saw a
+wrong bearer token, because the auth check answers before the limiter is reached — so
+guessing ran at network speed. `--authFailureLimit` gives each client its own small budget,
+spent only on a 401; a correct token never consumes from it, so a working client never
+throttles itself. Once an address has spent its budget every request from it waits,
+including one with the right token — that is deliberate, since answering the guess would
+otherwise tell the caller which token was right. Clients are told apart by socket address. **Behind a
+reverse proxy that means every client shares one budget**, so set `--trustProxy` when the
+proxy is yours — the server prints a warning the first time it sees `X-Forwarded-For`
+without it. `--trustProxy` takes the *rightmost* `X-Forwarded-For` entry, which is the hop
+the proxy itself appended; everything to its left came from the client, so reading the
+leftmost would let a client choose its own budget or spend a victim's. That only holds if a
+proxy actually appended the entry, so the header is read **only when the peer is the
+proxy** — bare `--trustProxy` means a loopback peer, which is the deployment above; name a
+proxy elsewhere with `--trustedProxies`. When the header cannot be read as an address, or
+the peer is not trusted, the server falls back to the socket address and says so once, so
+a flag that is not taking effect is not silent. One trusted hop is assumed. A malformed `--authFailureLimit` is refused at startup rather than silently
+disabling the check; only `0` turns it off.
+
 **Always terminate TLS at a reverse proxy** (Caddy/nginx). The server listens on `127.0.0.1` only.
 
 ---
@@ -672,12 +710,18 @@ Secrets are **never** passed as CLI arguments.
 | `--httpHost` | 127.0.0.1 | HTTP bind address |
 | `--bearerToken` | — | Bearer token for HTTP transport auth (required for `--transport=http`) |
 | `--rateLimit` | 0 | HTTP requests per minute on the MCP route (0 = unlimited) |
+| `--authFailureLimit` | 10 | Failed bearer-auth attempts allowed per client per minute (0 = off) |
+| `--trustProxy` | false | Read the client address from `X-Forwarded-For`, but only when the peer is the proxy — bare means a loopback peer |
+| `--trustedProxies` | — | Comma-separated peer addresses allowed to send `X-Forwarded-For`. Empty means loopback only |
 | `--allowedHosts` | bind address + localhost | Comma-separated Host headers accepted by the DNS-rebinding guard |
+| `--hostKeyMode` | `tofu` | `tofu \| strict \| insecure`. See [SECURITY.md](./SECURITY.md#host-key-trust-does-not-survive-a-restart) — `strict` currently refuses every host |
 | `--insecureHostKey` | false | Disable host key verification (test only!) |
 | `--allowUncheckedConfigAcl` | false | Windows: report every ACL finding and refuse none |
 | `--strictConfigAcl` | false | Windows: refuse on every ACL finding, including a read-only over-grant |
 | `--disableApproval` | false | Skip the approval gate (quick start profile only) |
 | `--opaUrl` | — | OPA sidecar URL for external policy |
+| `--opaFailClosed` | false | Refuse every command while OPA is unreachable, instead of falling back to local policy |
+| `--opaTimeoutMs` | 10000 | How long to wait for the OPA sidecar. Lower makes the fail-open cheaper to reach; higher makes an outage slower to notice |
 | `--commandQuota` | 0 (off) | Max commands per rolling 24h per profile |
 | `--approvalGrantTtl` | 0 (off) | Auto-approve an identical command for this many ms after approval |
 | `--auditEntropyScan` | false | Enable entropy-based secret scanning in audit |
@@ -698,8 +742,8 @@ replacement, rather than failing later as a confusing auth error.
 | v1 | v2 | Notes |
 |----|----|-------|
 | `exec` | `read-command` | Allowlisted read-only commands. Prefer this for reads. |
-| `exec` | `run-command` | Arbitrary commands. Destructive ones go through the approval gate. |
-| `sudo-exec` | `privileged-command` | Always requires approval. Password is piped via stdin. |
+| `exec` | `run-command` | Arbitrary commands. Destructive and privileged ones go through the approval gate, unless `approvalPolicy = "auto"`. |
+| `sudo-exec` | `privileged-command` | Requires approval unless `approvalPolicy = "auto"`. Password is piped via stdin. |
 | `description` parameter | — | Removed. It was an injection vector (#44) and never reached the host. |
 
 **Command results now carry status.** In v1 a failed command rejected with
@@ -739,8 +783,12 @@ and pass `--config <path>`; profiles carry per-host roles and approval policy.
 ### Host key verification
 
 v1 did not verify host keys. v2 defaults to trust-on-first-use and records the
-key; a later mismatch fails the connection. Pin explicitly with `trustedHostKey`
-in a profile, or pass `--insecureHostKey` to opt out (test environments only).
+key **in memory, for the life of the process**; a later mismatch in that same
+process fails the connection. Nothing is written to disk and `~/.ssh/known_hosts`
+is not consulted, so a restart accepts afresh — see
+[SECURITY.md](./SECURITY.md#host-key-trust-does-not-survive-a-restart). Pin
+explicitly with `trustedHostKey` in a profile, which is the only control here that
+survives a restart, or pass `--insecureHostKey` to opt out (test environments only).
 
 ---
 

package/build/cli.js

@@ -59,6 +59,35 @@ export function parseArgv(args = process.argv.slice(2)) {
  * `--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.
  */
+/**
+ * `--authFailureLimit`, refusing rather than guessing.
+ *
+ * `parseArgv` stores `null` for a flag written without a value, and `null !== undefined`,
+ * so a bare `--authFailureLimit` reached `parseInt` and produced NaN. NaN fails the `> 0`
+ * test the transport uses to decide whether to build the limiter at all, so a typo — or
+ * `--authFailureLimit=off`, which `0 = off` makes a plausible spelling — silently turned
+ * off a control that is on by default, with no line in the startup banner to say so. The
+ * same shape on `--rateLimit` is harmless because that one defaults to off; this one does
+ * not, which is what makes failing open new.
+ */
+export function parseFailureLimit(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === null || !/^\d+$/.test(raw.trim())) {
+        throw new OperatorError(`--authFailureLimit needs a non-negative whole number, got ${JSON.stringify(raw)}. ` +
+            'Use --authFailureLimit=0 to turn the check off deliberately.');
+    }
+    const value = Number(raw.trim());
+    // Bounded, because an unbounded one is the same fail-open this guard exists to stop:
+    // `--authFailureLimit=99999999999999999999` parsed to 1e20, a bucket that never empties
+    // and a `Retry-After` of 1 — configured on, functionally absent.
+    if (!Number.isSafeInteger(value) || value > MAX_AUTH_FAILURE_LIMIT) {
+        throw new OperatorError(`--authFailureLimit must be between 0 and ${MAX_AUTH_FAILURE_LIMIT}, got ${JSON.stringify(raw)}.`);
+    }
+    return value;
+}
+/** Far above any real budget; the point is that there is one. */
+const MAX_AUTH_FAILURE_LIMIT = 10_000;
 export function flagEnabled(argv, name) {
     if (!(name in argv))
         return false;
@@ -99,6 +128,53 @@ export function parseMaxChars(raw) {
         return 5_000;
     return parsed <= 0 ? Number.MAX_SAFE_INTEGER : parsed;
 }
+/**
+ * `--opaTimeoutMs`, bounded on both sides.
+ *
+ * Too low turns an explicit OPA deny into an allow whenever the sidecar is slow, which is
+ * the fail-open this budget exists inside; too high brings back the hang it replaced. One
+ * second is the floor and two minutes the ceiling.
+ */
+export function parseOpaTimeout(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = raw === null ? NaN : Number(raw.trim());
+    if (!Number.isSafeInteger(value) || value < 1_000 || value > 120_000) {
+        throw new OperatorError(`--opaTimeoutMs must be a whole number of milliseconds between 1000 and 120000, got ${JSON.stringify(raw)}.`);
+    }
+    return value;
+}
+/**
+ * `--opaUrl`, refused at startup rather than at every request.
+ *
+ * Only emptiness was checked, so anything `fetch` cannot use reached the engine and failed
+ * on every call — with `OPA sidecar enabled` printed at startup and one stderr line per
+ * minute as the only signal. `--opaUrl=localhost:8181` is a realistic slip, since OPA's own
+ * `--addr` is written `:8181`, and in the default mode it leaves a gate that looks
+ * configured and is never consulted. Credentials in the URL are refused too: `fetch`
+ * rejects such a URL outright, so it would be a gate that cannot work at all.
+ */
+export function parseOpaUrl(raw) {
+    if (!raw) {
+        throw new OperatorError('--opaUrl needs a URL, as --opaUrl=http://localhost:8181.');
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new OperatorError(`--opaUrl=${raw} is not a URL. Include the scheme, as --opaUrl=http://localhost:8181.`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new OperatorError(`--opaUrl must be http or https, got ${parsed.protocol}`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new OperatorError('--opaUrl must not embed credentials — fetch() refuses such a URL, so the gate would ' +
+            'never be consulted. Put the sidecar behind a network boundary instead.');
+    }
+    // A trailing slash would make the request path `//v1/data/...`.
+    return (parsed.origin + parsed.pathname).replace(/\/$/, '');
+}
 /**
  * `strict` was previously unreachable: nothing but test code could select it,
  * yet host-key.ts pointed users at a `--acceptNewHostKey` flag that never

package/build/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { reportFatal } from './errors.js';
+import { reportFatal, OperatorError } from './errors.js';
 import { ConnectionRegistry } from './ssh/connection-registry.js';
 import { PolicyEngine, 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';
 import { SERVER_VERSION } from './version.js';
-import { parseArgv, buildAppConfig, checkRemovedFlags, flagEnabled, resolveHostKeyMode, } from './cli.js';
+import { parseArgv, buildAppConfig, checkRemovedFlags, flagEnabled, parseFailureLimit, parseOpaUrl, parseOpaTimeout, resolveHostKeyMode, } from './cli.js';
 async function main() {
     const argv = parseArgv();
     checkRemovedFlags(argv);
@@ -28,10 +28,16 @@ async function main() {
     const registry = new ConnectionRegistry(config, hostKeyMode);
     const policy = new PolicyEngine(resolvePolicyRules(config.profiles, config.policy));
     const audit = new AuditStore(undefined, entropyScan, tamperEvident);
-    if (argv.opaUrl) {
-        policy.setOpaUrl(argv.opaUrl);
+    if ('opaUrl' in argv) {
+        // Presence, not truthiness — the trap `flagEnabled` was written for. A
+        // space-separated `--opaUrl http://…` stores null, so the old guard dropped it
+        // silently, and dropped any `--opaFailClosed` the operator asked for with it.
+        policy.setOpaUrl(parseOpaUrl(argv.opaUrl), flagEnabled(argv, 'opaFailClosed'), parseOpaTimeout(argv.opaTimeoutMs));
         console.error(`OPA sidecar enabled: ${argv.opaUrl}`);
     }
+    else if (flagEnabled(argv, 'opaFailClosed')) {
+        throw new OperatorError('--opaFailClosed does nothing without --opaUrl.');
+    }
     // An McpServer binds to a single transport, so HTTP needs one per session.
     const createMcpServer = () => {
         // capabilities moved from serverInfo to ServerOptions in SDK 1.30.
@@ -50,6 +56,9 @@ async function main() {
             host: argv.httpHost || '127.0.0.1',
             bearerToken: argv.bearerToken,
             rateLimit: parseInt(argv.rateLimit) || 0,
+            authFailureLimit: parseFailureLimit(argv.authFailureLimit),
+            trustProxy: flagEnabled(argv, 'trustProxy'),
+            trustedProxies: argv.trustedProxies?.split(',').map((h) => h.trim()).filter(Boolean),
             allowedHosts: argv.allowedHosts?.split(',').map((h) => h.trim()).filter(Boolean),
             registry,
         });