ssh-mcp 2.3.4 → 2.4.1

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)
@@ -23,6 +24,10 @@ npm install -g ssh-mcp
 
 ### 2. Configure
 
+Without a config the server still starts, so a client or directory can complete the MCP
+handshake and read `tools/list` — but **every tool call is refused** until you configure it,
+with a message naming the path below. Nothing runs on a host until this step is done.
+
 Create the config file at the path for your platform:
 
 | Platform | Path |
@@ -98,6 +103,12 @@ nothing. Neither combination leaves you without an exit, which is the lesson of
 A supervisor that treats any non-zero status as a failure needs no change. One
 that matched on `1` to detect a startup problem should match on `2` as well.
 
+Starting with nothing configured is **not** an exit-2 condition, as of the release that
+added introspection without a config: the server starts so it can be described, and
+refuses each tool call instead. A supervisor that used a non-zero exit to catch an
+unconfigured deployment should watch for `starting unconfigured` on stderr, or read
+`configured` from `GET /health` when running the HTTP transport.
+
 ### 3. Set credentials via environment variables
 
 ```bash
@@ -513,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
@@ -565,6 +615,12 @@ ssh-mcp --transport=http --httpPort=3000 --bearerToken=secret --rateLimit=60
 
 Endpoints: `POST /` (MCP Streamable HTTP), `GET /status`, `GET /health`
 
+`GET /health` answers `{"healthy": true, "configured": <bool>}`. It stays `200` either way —
+`healthy` is liveness — while `configured` is false when no profile is set, which is the
+case of a config bind mount that silently did not attach: the server binds the port and
+refuses every tool call. `GET /status` carries the profile list itself and stays behind the
+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.
 
 **Always terminate TLS at a reverse proxy** (Caddy/nginx). The server listens on `127.0.0.1` only.
@@ -719,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/cli.js

@@ -14,8 +14,23 @@
  * escape the boot gate to be testable.
  */
 import { loadConfig, getConfigPath } from './config/loader.js';
-import { OperatorError, ConfigNotFoundError } from './errors.js';
+import { OperatorError, ConfigNotFoundError, UnconfiguredError } from './errors.js';
 import { HOST_GROUPS } from './policy/engine.js';
+/**
+ * Whether the operator asked for a quick start at all.
+ *
+ * Presence, not truthiness — the same #91 trap `flagEnabled` was written for. `parseArgv`
+ * stores `null` for a flag written without `=` and drops bare words, so all three of
+ * `--host example.com --user root` (space instead of `=`, the commonest slip), `--host`
+ * alone, and `--host= --user=` (a wrapper interpolating unset env vars) produce falsy
+ * values while the flags were plainly given. Testing truthiness sent every one of them
+ * down the soft path: a server that starts and looks healthy, with the explanation only
+ * on a stderr stream an MCP client typically swallows. Only "asked for nothing" softens;
+ * a half-given or empty-valued quick start is a typo and still refuses.
+ */
+function nothingRequested(argv) {
+    return !('host' in argv) && !('user' in argv);
+}
 export function parseArgv(args = process.argv.slice(2)) {
     const config = {};
     for (const arg of args) {
@@ -120,6 +135,26 @@ export function resolveHostGroup(argv) {
     // operator would read the refusal as policy rather than as their own slip.
     throw new OperatorError(`Invalid --group=${group}. Expected one of: ${HOST_GROUPS.join(', ')}.`);
 }
+/**
+ * The defaults a quick-start profile inherits, from flags alone.
+ *
+ * Named because an unconfigured start needs them too — `approvalGrantTtlMs` is read while
+ * wiring the tools, long before any profile exists, so the two paths have to agree.
+ */
+export function defaultsFromArgv(argv) {
+    return {
+        sessionMaxPerConnection: parseInt(argv.sessionMax) || 5,
+        sessionIdleTimeoutMs: parseInt(argv.sessionTtl) || 600_000,
+        sessionBackgroundMaxMs: 3_600_000,
+        commandTimeoutMs: parseInt(argv.timeout) || 60_000,
+        commandMaxChars: parseMaxChars(argv.maxChars),
+        commandMaxOutputBytes: 1_048_576,
+        connectionIdleReapMs: 900_000,
+        commandQuotaPerDay: parseInt(argv.commandQuota) || 0,
+        approvalGrantTtlMs: parseInt(argv.approvalGrantTtl) || 0,
+        approvalMode: 'ask-destructive',
+    };
+}
 export async function buildAppConfig(argv) {
     // The way past an ACL that could not be read, rather than an operator with no
     // exit. See assertPrivateOnWindows.
@@ -176,25 +211,28 @@ export async function buildAppConfig(argv) {
         if (!(err instanceof ConfigNotFoundError))
             throw err;
     }
+    // Nothing configured, and nothing named on the command line either. Start anyway, with
+    // no profiles: an MCP client or directory can then complete the handshake and read
+    // `tools/list`, and every tool call is refused by `ConnectionRegistry` with the message
+    // below — including `list-connections`, which resolves no profile and so had to be told.
+    //
+    // Measured before this: `initialize` and `tools/list` against our own image drew no
+    // JSON-RPC response at all — the process exited on this check first — so every directory
+    // and every "add this server" flow saw a crash. Tool definitions are static metadata and
+    // the config decides what they may *reach*, so coupling the two bought no safety.
+    //
+    // A half-given quick start is not this case: `--host` without `--user` is a typo, and an
+    // explicit `--config` that points nowhere already threw above. Only "configured nothing"
+    // softens — see `nothingRequested`, which tests for the flags being absent rather than
+    // falsy so that a valueless or space-separated one stays a typo.
+    if (nothingRequested(argv)) {
+        console.error(`Warning: starting unconfigured — every tool call will be refused.\n${new UnconfiguredError(getConfigPath()).message}`);
+        return { defaults: defaultsFromArgv(argv), profiles: [] };
+    }
     if (!argv.host || !argv.user) {
-        throw new OperatorError('No config file found and missing required --host/--user.\n' +
-            // Was hardcoded to ~/.config/ssh-mcp/config.toml on every platform, so on
-            // Windows and macOS it named a path this code never reads.
-            `Either create a config file at ${getConfigPath()} or pass --config <path>.\n` +
-            'For quick start: --host=<host> --user=<user> (credentials via env vars).');
+        throw new UnconfiguredError(getConfigPath());
     }
-    const defaults = {
-        sessionMaxPerConnection: parseInt(argv.sessionMax) || 5,
-        sessionIdleTimeoutMs: parseInt(argv.sessionTtl) || 600_000,
-        sessionBackgroundMaxMs: 3_600_000,
-        commandTimeoutMs: parseInt(argv.timeout) || 60_000,
-        commandMaxChars: parseMaxChars(argv.maxChars),
-        commandMaxOutputBytes: 1_048_576,
-        connectionIdleReapMs: 900_000,
-        commandQuotaPerDay: parseInt(argv.commandQuota) || 0,
-        approvalGrantTtlMs: parseInt(argv.approvalGrantTtl) || 0,
-        approvalMode: 'ask-destructive',
-    };
+    const defaults = defaultsFromArgv(argv);
     const profile = {
         name: 'default',
         host: argv.host,

package/build/config/loader.js

@@ -3,7 +3,7 @@ import { homedir, platform } from 'os';
 import { join, dirname } from 'path';
 import { parse as parseTOML } from 'smol-toml';
 import { configSchema } from './schema.js';
-import { OperatorError, ConfigNotFoundError } from '../errors.js';
+import { OperatorError, ConfigNotFoundError, UnconfiguredError } from '../errors.js';
 import { assertPrivateOnWindows } from './windows-acl.js';
 export function getConfigPath(customPath) {
     if (customPath)
@@ -188,6 +188,14 @@ export function getProfile(config, name) {
             throw new OperatorError(`No profile selected and no default configured, but ${config.profiles.length} profiles exist: ${names}. ` +
                 `Pass a "profile" argument, or set defaults.defaultProfile in the config.`);
         }
+        // Defensive: a lookup helper must not hand back `undefined` typed as `Profile`, which
+        // is what `profiles[0]` on an empty list used to do — a TypeError somewhere downstream
+        // rather than an explanation here. This is the invariant, not the product rule. The
+        // decision that an unconfigured server refuses work lives in `ConnectionRegistry`,
+        // which guards this branch AND the named-profile one below; reaching this line means
+        // a caller went around the registry.
+        if (config.profiles.length === 0)
+            throw new UnconfiguredError(getConfigPath());
         return config.profiles[0];
     }
     const profile = config.profiles.find((p) => p.name === targetName);

package/build/errors.js

@@ -65,6 +65,29 @@ export class ConfigNotFoundError extends OperatorError {
         this.name = 'ConfigNotFoundError';
     }
 }
+/**
+ * Nothing is configured: no config file, and no `--host`/`--user` on the command line.
+ *
+ * A type rather than a bare `OperatorError` for the reason `ConfigNotFoundError` is one —
+ * two layers have to agree on this state without agreeing on a string. `cli.ts` prints it
+ * as a startup warning and the server keeps running; `ConnectionRegistry` throws it at
+ * every tool call. Those are different audiences reached through different channels, and
+ * a wording edit in one must not quietly stop matching the other.
+ *
+ * The path is a constructor argument rather than a `getConfigPath()` call inside the
+ * message, so this file stays free of the config layer and the text is testable without
+ * stubbing `os.platform()`.
+ */
+export class UnconfiguredError extends OperatorError {
+    configPath;
+    constructor(configPath) {
+        super('No config file found and missing required --host/--user.\n' +
+            `Either create a config file at ${configPath} or pass --config <path>.\n` +
+            'For quick start: --host=<host> --user=<user> (credentials via env vars).');
+        this.configPath = configPath;
+        this.name = 'UnconfiguredError';
+    }
+}
 /** Exit status for an operator error, so a supervisor can tell it from a crash. */
 export const EXIT_OPERATOR_ERROR = 2;
 /** Exit status for anything else. */

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,41 @@ export function extractBinary(command) {
     const parts = cmd.split(/\s+/);
     return parts[0] || '';
 }
-export function classifyCommand(command) {
+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.

package/build/ssh/connection-registry.js

@@ -1,4 +1,5 @@
-import { getProfile as getConfigProfile } from '../config/loader.js';
+import { getProfile as getConfigProfile, getConfigPath } from '../config/loader.js';
+import { UnconfiguredError } from '../errors.js';
 import { resolveCredentials } from '../config/credential-resolver.js';
 import { SSHConnection } from './connection.js';
 export class ConnectionRegistry {
@@ -69,7 +70,25 @@ export class ConnectionRegistry {
         const profile = this.getProfile(profileName);
         return this.connections.get(profile.name);
     }
+    /**
+     * Refuse everything while nothing is configured.
+     *
+     * The server now starts with `profiles: []` so a directory or a client's "add server"
+     * flow can read `tools/list` (see cli.ts). This is where that state stops being
+     * readable and starts being refused, and it sits here rather than in the loader's
+     * `getProfile` for one measured reason: the loader's empty check can only live in the
+     * no-profile-named branch, so a client calling `run-command` with `profile: "prod"`
+     * against an unconfigured server got `Profile "prod" not found` — a message telling the
+     * operator they mistyped a name when in fact they have no config at all, and omitting
+     * the config path this whole change exists to deliver. Checking before the lookup
+     * covers both.
+     */
+    assertConfigured() {
+        if (this.config.profiles.length === 0)
+            throw new UnconfiguredError(getConfigPath());
+    }
     getProfile(profileName) {
+        this.assertConfigured();
         return getConfigProfile(this.config, profileName);
     }
     listConnections() {

package/build/tools/command-tools.js

@@ -42,7 +42,6 @@ export function registerCommandTools({ server, registry, policy }, pipeline) {
         command: z.string().describe('Command to execute with sudo'),
         profile: z.string().optional().describe('Profile name'),
     }, { destructiveHint: true }, async ({ command, profile }, extra) => {
-        const profileName = defaultProfileName(profile);
         return runAudited(command, {
             toolName: 'privileged-command',
             failureClass: 'privileged',
@@ -51,7 +50,11 @@ export function registerCommandTools({ server, registry, policy }, pipeline) {
             // Evaluate the bare command too: the sudo wrapper would otherwise
             // hide a forbidden command inside a quoted `sh -c` argument.
             preCheck: (cleanCmd) => {
-                const rawEval = policy.evaluate(cleanCmd, registry.getProfile(profileName), 'privileged-command');
+                // Resolved here rather than before `runAudited`: `defaultProfileName` reaches
+                // `registry.getProfile()`, which refuses on an unconfigured server, and outside
+                // the pipeline's try that refusal escaped without an audit record. `preCheck`
+                // runs inside it.
+                const rawEval = policy.evaluate(cleanCmd, registry.getProfile(defaultProfileName(profile)), 'privileged-command');
                 if (rawEval.decision === 'deny') {
                     throw new PolicyRefusedError(`POLICY_DENIED: ${rawEval.reason || 'Command not allowed'}`, rawEval);
                 }

package/build/tools/pipeline.js

@@ -75,7 +75,12 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
         await audit.record({
             mcpRequestId: ctx.requestId,
             profile: profileName,
-            user: registry.getProfile(profileName).user,
+            // Looked up without throwing. This used to be `registry.getProfile(profileName).user`,
+            // which throws for exactly the reason the tool call is being audited as a failure —
+            // an unconfigured server, or a profile name that does not exist — and `auditFailure`
+            // swallows that by design. The record the operator most needs was the one record that
+            // could not be written.
+            user: profileUser(profileName),
             command,
             commandClass: evaluation.commandClass,
             binary: evaluation.binary,
@@ -113,6 +118,10 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
     function defaultProfileName(profile) {
         return profile || registry.getProfile().name;
     }
+    /** The profile's SSH user, or a placeholder — never throws, so an audit write cannot fail. */
+    function profileUser(profileName) {
+        return registry.listAllProfiles().find((p) => p.name === profileName)?.user ?? '(unresolved)';
+    }
     function makeProgressSender(extra) {
         const token = extra?._meta?.progressToken;
         if (token === undefined)
@@ -135,15 +144,21 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
      */
     async function runAudited(command, opts, run) {
         const ctx = makeCtx(opts.extra, opts.profile, opts.session);
-        const profileName = defaultProfileName(opts.profile);
-        const profile = registry.getProfile(profileName);
         const onProgress = makeProgressSender(opts.extra);
         const abortSignal = opts.extra?.signal;
-        // Sanitization runs inside the try so a rejected (empty, control-char-only,
-        // over-length) command still leaves an audit trail — a client probing with
-        // malformed payloads used to leave none.
+        // Named before the try because `auditFailure` needs something to file the record
+        // under even when resolution itself is what failed. Reassigned to the resolved name as
+        // the first statement inside, so the quota key and the audit record are unchanged on
+        // every path that gets that far.
+        let profileName = opts.profile ?? '(default)';
+        // Profile resolution and sanitization both run inside the try, so a rejected call
+        // still leaves an audit trail — a client probing with malformed payloads, or probing
+        // a server that has no config at all, used to leave none. The unconfigured refusal
+        // reaches this the same way a bad command does.
         const state = { command };
         try {
+            profileName = defaultProfileName(opts.profile);
+            const profile = registry.getProfile(profileName);
             let effective = opts.synthetic ? command : sanitizeCommand(command, profile.maxChars);
             state.command = effective;
             opts.preCheck?.(effective);

package/build/tools/session-tools.js

@@ -38,6 +38,14 @@ export function registerSessionTools({ server, registry }, pipeline) {
     const { runAudited, resolveConn, auditResult, auditFailure, makeCtx, defaultProfileName } = pipeline;
     // ─── list-connections ──────────────────────────────────────────────────
     server.tool('list-connections', D["list-connections"], {}, { readOnlyHint: true }, async () => {
+        // The one tool that reads only `listAllProfiles()` and so never touches
+        // `getProfile`. Without this it answered an unconfigured server with a
+        // zero-length success — on the tool whose own description sends an agent here
+        // first ("discover available hosts before running commands"), and on the one
+        // channel where the startup stderr warning is not visible. The agent saw "no
+        // hosts" rather than "not configured". Refusing here is what makes the claim in
+        // the README, the changeset and the startup warning true of all eleven tools.
+        registry.assertConfigured();
         const connections = registry.listConnections();
         const profiles = registry.listAllProfiles();
         const lines = profiles.map((p) => {
@@ -104,19 +112,27 @@ export function registerSessionTools({ server, registry }, pipeline) {
         profile: z.string().optional().describe('Profile name'),
     }, { destructiveHint: true }, async ({ name, profile }, extra) => {
         const cleanName = sanitizeSessionName(name);
-        const profileName = defaultProfileName(profile);
+        // Both the profile name and the connection are resolved inside the try below. They
+        // used to be resolved above it, so a refusal — an unconfigured server, an unknown
+        // profile name — escaped before `auditFailure` could record that a release was
+        // attempted. The placeholders are what the record is filed under if resolution is
+        // itself what failed.
+        let profileName = profile ?? '(default)';
         const ctx = makeCtx(extra, profileName, cleanName);
-        const conn = await resolveConn(profile);
-        // Recorded with the session's kind, so a remote SIGKILL is greppable in the log and
-        // distinguishable from ending a local shell — `open-session` encodes its type the
-        // same way.
-        // Through `toInfo()` rather than an `instanceof` check: the type is public API, and a
-        // tool handler reaching for a constructor identity is the layer leak this repo's own
-        // rules call out.
-        const kind = conn.getSession(cleanName)?.toInfo().type ?? 'unknown';
-        const command = `session:close ${kind} ${cleanName}`;
+        let command = `session:close unknown ${cleanName}`;
         const startedAt = Date.now();
         try {
+            profileName = defaultProfileName(profile);
+            ctx.profile = profileName;
+            const conn = await resolveConn(profile);
+            // Recorded with the session's kind, so a remote SIGKILL is greppable in the log and
+            // distinguishable from ending a local shell — `open-session` encodes its type the
+            // same way.
+            // Through `toInfo()` rather than an `instanceof` check: the type is public API, and a
+            // tool handler reaching for a constructor identity is the layer leak this repo's own
+            // rules call out.
+            const kind = conn.getSession(cleanName)?.toInfo().type ?? 'unknown';
+            command = `session:close ${kind} ${cleanName}`;
             const outcome = await conn.closeSession(cleanName);
             await auditResult(ctx, profileName, command, RELEASE, {
                 stdout: '',

package/build/transport/http.js

@@ -98,7 +98,8 @@ export async function startHttpServer(createMcpServer, opts) {
     const httpServer = createServer(async (req, res) => {
         const url = new URL(req.url || '/', `http://${req.headers.host}`);
         // Liveness probes are conventionally unauthenticated, and the README lists
-        // /health without an auth caveat. It exposes nothing beyond "process is up".
+        // /health without an auth caveat. It exposes "process is up" and whether any profile
+        // is configured — see the handler below for why that second bit is not a secret.
         const isHealthProbe = req.method === 'GET' && url.pathname === '/health';
         if (!isHealthProbe) {
             const auth = req.headers.authorization || '';
@@ -210,8 +211,18 @@ export async function startHttpServer(createMcpServer, opts) {
             return;
         }
         if (req.method === 'GET' && url.pathname === '/health') {
+            // `configured` is liveness telling the truth about readiness. Since the server
+            // learned to start with nothing configured, an HTTP deployment whose config bind
+            // mount silently did not attach comes up, binds the port, and fails 100% of tool
+            // calls — while this probe said `healthy: true` and the explaining stderr warning
+            // scrolled past at boot. The status stays 200 so an existing probe does not start
+            // failing on upgrade; the field is what an operator can alert on.
+            //
+            // It widens what this unauthenticated route discloses by exactly one bit, and that
+            // bit is worth little to anyone: a server with no profile is one that cannot reach
+            // any host. `/status` carries the profile list itself and stays behind the token.
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ healthy: true }));
+            res.end(JSON.stringify({ healthy: true, configured: registry.listAllProfiles().length > 0 }));
             return;
         }
         res.writeHead(404, { 'Content-Type': 'application/json' });

package/package.json

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