ssh-mcp 2.3.1 → 2.3.2

package/README.md

@@ -60,18 +60,32 @@ which is why `chmod 700` is in that command, since `mkdir -p` under the default
 leaves the directory 0755. The server refuses to start otherwise. "Only the owner" is
 unambiguous here and `chmod` is a one-line fix.
 
-**Windows: reported.** There are no mode bits, so it reads the ACL and tells you what it
-grants — a config under `%APPDATA%` inherits access for you, `SYSTEM` and `Administrators`
-and needs nothing done to it, while one created elsewhere does not: a file under `C:\`
-inherits read for every local account and modify for every authenticated one. The message
-names the two `icacls` commands that fix it, and then the config loads anyway.
-
-Advisory rather than enforced because enforced was tried first: 2.3.0 refused, and it
-blocked a config at the documented `%APPDATA%` location whose ACL carried a principal the
-allowlist had never seen ([#138](https://github.com/tufantunc/ssh-mcp/issues/138)). A check
-whose worst outcome is locking you out of your own config is not worth that. Pass
-`--strictConfigAcl` to refuse instead; under it, `--allowUncheckedConfigAcl` still loads a
-config whose ACL could not be determined at all.
+**Windows: split by what the ACL actually allows.** There are no mode bits, so the ACL is
+read instead — and read exposure and write exposure are not treated alike, because Windows
+is much clearer about one of them than the other.
+
+| The ACL lets another account… | Default |
+|---|---|
+| only **read** the config | reported, and the server starts |
+| **change** the config | refused |
+| nothing (no ACL at all) | refused — that is full control for everyone |
+| …and if the ACL could not be read | refused, except when `icacls` is absent or the check timed out |
+
+A config under `%APPDATA%` inherits access for you, `SYSTEM` and `Administrators` and needs
+nothing done to it. One created elsewhere does not: a file under `C:\` inherits *read* for
+every local account and *modify* for every authenticated one. The message names the two
+`icacls` commands that fix it either way.
+
+Read exposure is reported rather than refused because that is where Windows is genuinely
+muddier than POSIX, and refusing over it blocked a config at the documented location
+([#138](https://github.com/tufantunc/ssh-mcp/issues/138)). Write exposure is refused
+because it is not muddy at all: another account being able to rewrite the file that decides
+which hosts, roles and approval policy this server honours is an authorization bypass, not
+a disclosure.
+
+Two flags move the whole thing: `--strictConfigAcl` refuses everything the check objects
+to, read-only grants included; `--allowUncheckedConfigAcl` reports everything and refuses
+nothing. Neither combination leaves you without an exit, which is the lesson of #138.
 
 ### Exit statuses
 
@@ -604,8 +618,8 @@ Secrets are **never** passed as CLI arguments.
 | `--rateLimit` | 0 | HTTP requests per minute on the MCP route (0 = unlimited) |
 | `--allowedHosts` | bind address + localhost | Comma-separated Host headers accepted by the DNS-rebinding guard |
 | `--insecureHostKey` | false | Disable host key verification (test only!) |
-| `--allowUncheckedConfigAcl` | false | Windows: load the config even if its ACL could not be read |
-| `--strictConfigAcl` | Windows: refuse to start on a broad or unreadable config ACL instead of reporting it |
+| `--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 |
 | `--commandQuota` | 0 (off) | Max commands per rolling 24h per profile |

package/build/config/loader.js

@@ -20,19 +20,21 @@ export function getConfigPath(customPath) {
     return join(xdgConfig, 'ssh-mcp', 'config.toml');
 }
 /**
- * Refuse a config file that anyone but its owner can read, because it holds the
- * hosts, roles and policy rules that decide what this server will run.
+ * Check that nobody but the owner can reach a config file, because it holds the hosts,
+ * roles and policy rules that decide what this server will run.
  *
- * One question, asked of two different access-control systems. Mode bits are
- * POSIX's answer and are meaningless on Windows, which is the whole of #138:
- * Node synthesises `0o666` for every readable file there, so `& 0o077` was
- * non-zero unconditionally and every Windows config that has ever existed was
- * rejected. The `chmod 600` it prescribed could not lift that rejection —
- * measured on Windows 11, `chmod(path, 0o600)` leaves the mode at `0o666`,
- * because `fs.chmod` there only toggles the read-only bit. Following the
- * instruction exactly returned the operator to where they started.
+ * The two platforms answer differently on purpose. POSIX refuses: "only the owner" is
+ * unambiguous there and `chmod` is a one-line fix. Windows refuses a config another
+ * account can *change* and reports one it can only *read*, because read exposure is where
+ * the platform is genuinely muddier — see `waived` in windows-acl.ts.
  *
- * Windows reads the ACL instead; see assertPrivateOnWindows.
+ * Mode bits are POSIX's answer and are meaningless on Windows, which is the whole of #138:
+ * Node synthesises `0o666` for every readable file there, so `& 0o077` was non-zero
+ * unconditionally and every Windows config that has ever existed was rejected. The
+ * `chmod 600` it prescribed could not lift that rejection — measured on Windows 11,
+ * `chmod(path, 0o600)` leaves the mode at `0o666`, because `fs.chmod` there only toggles
+ * the read-only bit. Following the instruction exactly returned the operator to where
+ * they started.
  */
 export async function checkPermissions(filePath, opts = {}) {
     return platform() === 'win32'

package/build/config/windows-acl.js

@@ -68,7 +68,7 @@ const CHILD_ENV = { SystemRoot: join(SYSTEM32, '..'), Path: SYSTEM32 };
  *
  * Generous, because running out is not evidence about the file: five seconds across
  * three process creations plus two temp-directory round trips, so that on-access
- * virus scanning or a loaded host does not turn a private config into a refusal.
+ * virus scanning or a loaded host does not turn a private config into a finding.
  * Expiry gets its own verdict for the same reason — see `timed-out`.
  */
 const ACL_TIMEOUT_MS = 5_000;
@@ -202,6 +202,56 @@ const DACL_CONTROL_FLAGS = /^(?:P|AI|AR)*$/;
 const ACE_FLAG_CODES = new Set([
     'CI', 'OI', 'IO', 'NP', 'ID', 'SA', 'FA', 'TP', 'CR',
 ]);
+/**
+ * Rights that let a trustee change the object, as SDDL letter codes. `WD` here is
+ * WRITE_DAC, not Everyone — the rights field and the trustee field have separate
+ * vocabularies that happen to share spellings.
+ */
+const WRITE_RIGHT_CODES = new Set([
+    'FA', 'FW', 'KA', 'KW', 'GA', 'GW', 'SD', 'WD', 'WO', 'CC', 'DC', 'SW', 'WP', 'DT',
+]);
+/** Rights that only let a trustee look. Anything unrecognised counts as write. */
+const READ_RIGHT_CODES = new Set([
+    'FR', 'FX', 'GR', 'GX', 'KR', 'RC', 'RP', 'LC', 'LO',
+]);
+/**
+ * FILE_WRITE_DATA, FILE_APPEND_DATA, FILE_WRITE_EA, FILE_WRITE_ATTRIBUTES, DELETE,
+ * WRITE_DAC, WRITE_OWNER, GENERIC_WRITE, GENERIC_ALL.
+ */
+const WRITE_MASK = 0x2 | 0x4 | 0x10 | 0x100 | 0x10000 | 0x40000 | 0x80000 | 0x40000000 | 0x10000000;
+/**
+ * Whether a rights field lets its trustee *change* the object rather than only read it.
+ *
+ * This distinction is the basis of the default posture, and the field used to be parsed
+ * and discarded. Read exposure on Windows is genuinely muddier than under POSIX — a
+ * shared volume grants `BUILTIN\Users` read, and refusing over that stranded the reporter
+ * of #138 — but write exposure is not muddy at all: "an ACE grants a non-owner
+ * FILE_WRITE_DATA or WRITE_DAC" is exactly as unambiguous as `0o022`, and a config another
+ * account can rewrite decides which hosts, roles and approval policy this server honours.
+ * That is an authorization bypass, not a disclosure, and it was being reported as one.
+ *
+ * Measured from real inheritance: `0x1200a9` is read-and-execute, `0x1301bf` is modify.
+ * Anything this cannot classify counts as write, because refusing is the safe direction.
+ */
+function grantsWrite(rights) {
+    const field = rights.trim().toUpperCase();
+    if (field === '')
+        return true;
+    if (/^0X[0-9A-F]+$/.test(field))
+        return (Number.parseInt(field.slice(2), 16) & WRITE_MASK) !== 0;
+    if (/^[0-9]+$/.test(field))
+        return (Number.parseInt(field, 10) & WRITE_MASK) !== 0;
+    if (field.length % 2 !== 0)
+        return true;
+    for (let i = 0; i < field.length; i += 2) {
+        const code = field.slice(i, i + 2);
+        if (WRITE_RIGHT_CODES.has(code))
+            return true;
+        if (!READ_RIGHT_CODES.has(code))
+            return true;
+    }
+    return false;
+}
 /**
  * The SID of the account this process runs as.
  *
@@ -265,7 +315,8 @@ async function currentUserSid(signal) {
  * executed by nothing.
  *
  * Two failures say nothing about the file — icacls being absent from the machine, and
- * the check running out of time — and those are the two the caller loads anyway.
+ * the check running out of time — and those are the two the caller loads anyway even
+ * under `--strictConfigAcl`.
  * Everything else (a non-zero exit, output we could not read) is about this path.
  *
  * Which makes "absent" worth being sure of: absent *here* is not enough, because a
@@ -520,7 +571,9 @@ export function parseDacl(descriptor, identity) {
         const sid = resolveTrustee(trustee, accountDomain);
         if (sid !== null && allowedSids.has(sid))
             continue;
-        grants.set(sid ?? trustee, { name: nameFor(trustee), trustee, sid });
+        grants.set(sid ?? trustee, {
+            name: nameFor(trustee), trustee, sid, writes: grantsWrite(fields[2]),
+        });
     }
     return grants.size === 0 ? { status: 'restricted' } : { status: 'broad', grants: [...grants.values()] };
 }
@@ -567,7 +620,7 @@ export function aclIdentity(sid) {
     // RID 500 is the built-in Administrator. In a default configuration it belongs
     // to the Administrators group, which is already allowed, so naming the account
     // directly grants nobody new access — while refusing it is a false positive,
-    // and here that means refusing to start a server whose config is fine. (On a
+    // and here that means refusing, or at best warning, about a config that is fine. (On a
     // domain-joined host the account domain is the domain, so this authorises
     // DOMAIN\Administrator, whose local-admin status comes from Domain Admins
     // nesting — a GPO default rather than a law.)
@@ -699,7 +752,26 @@ function remediation(path, kind, grants = []) {
     // reaches icacls literally, which reports "Failed processing 1 files" and
     // changes nothing. Measured. An instruction that only works in one shell is
     // the same defect as the `chmod 600` this whole change replaced.
-    const account = userInfo().username;
+    //
+    // Guarded because this is now on the *reporting* path, not only the throwing one. A
+    // Windows service under a virtual account, or a container with no loaded profile, makes
+    // `userInfo()` throw ENOENT — which escaped as a raw stack and cost the operator their
+    // config, which is #138 one environment over. A message that cannot name the account is
+    // still worth printing.
+    //
+    // A visible placeholder rather than `process.env.USERNAME`, which was the first spelling
+    // of this fallback. In the environments where `userInfo()` actually throws the env var is
+    // either unset or holds something icacls will not accept — a virtual service account, or
+    // `MACHINE$` — so it would print a command that fails, which is the defect class this
+    // whole change exists to remove. A placeholder the operator has to fill in cannot be
+    // followed by mistake.
+    let account;
+    try {
+        account = userInfo().username;
+    }
+    catch {
+        account = '<your account>';
+    }
     return ('Restrict it with these two commands, in this order:\n' +
         `  icacls "${path}" /inheritance:d\n` +
         `  icacls "${path}" /grant:r "${account}:${rights}"${removals}\n` +
@@ -729,15 +801,91 @@ function relocation(path, kind, grants) {
         remediation(path, kind, grants));
 }
 /**
- * Refuse a config the owner is not alone in being able to read — the Windows
- * half of `checkPermissions`.
- *
- * Both the file and its directory are examined. An unreadable ACL is refused rather
- * than waved through, with two exceptions: `icacls` absent from the machine, and the
- * check running out of time. Both are statements about the machine rather than about
- * the file, and refusing over a question that cannot be asked here is what #138 was.
- * `--allowUncheckedConfigAcl` is the way past the rest, so an operator is never stuck
- * with no exit.
+ * What a verdict means for one subject, as text and as data — and nothing else.
+ *
+ * Pure, so every message is assertable without a subprocess or a `console.error` spy, and
+ * so the refusal and the report cannot drift apart: they sat fifteen lines apart and had
+ * already diverged, one calling the same condition "was not checked" and the other "could
+ * not be checked".
+ */
+function describe(path, kind, verdict) {
+    if (verdict.status === 'restricted')
+        return null;
+    if (verdict.status === 'unknown') {
+        return {
+            path,
+            kind,
+            status: 'unchecked',
+            reason: verdict.reason,
+            detail: verdict.detail,
+            message: `Config ${kind} ${path} could not be checked for access by other accounts ` +
+                `(${verdict.reason}: ${verdict.detail}).\n` +
+                'Either fix the cause, move the config under %APPDATA%\\ssh-mcp, or pass ' +
+                '--allowUncheckedConfigAcl to accept it unverified.',
+        };
+    }
+    // An empty grants list for a NULL DACL is deliberate: there is nothing to `/remove:g`,
+    // and the fix is to give the object an ACL at all. `remediation` reads that emptiness.
+    const grants = verdict.status === 'broad' ? verdict.grants : [];
+    const writers = grants.filter((g) => g.writes);
+    const readers = grants.filter((g) => !g.writes);
+    const what = verdict.status === 'no-dacl'
+        ? 'has no access control list at all, which on Windows means full control for every ' +
+            'account on the machine.'
+        : writers.length > 0
+            // Named as modifiable, not "readable". Calling a modify grant readable understated an
+            // integrity failure as a disclosure — and the two now decide different postures, so
+            // the wording has to tell them apart.
+            ? `can be modified by accounts other than its owner: ${writers.map((g) => g.name).join(', ')}` +
+                `${readers.length ? `, and read by ${readers.map((g) => g.name).join(', ')}` : ''}. ` +
+                'Required: this account, SYSTEM and Administrators only.'
+            : `is readable beyond its owner: access is granted to ${grants.map((g) => g.name).join(', ')}. ` +
+                'Required: this account, SYSTEM and Administrators only.';
+    return {
+        path,
+        kind,
+        status: verdict.status,
+        grants,
+        message: `Config ${kind} ${path} ${what}\n` +
+            (isTightenable(path, kind) ? remediation(path, kind, grants) : relocation(path, kind, grants)),
+    };
+}
+/**
+ * Whether a finding is reported rather than refused.
+ *
+ * Three postures, two flags, and deliberately no combination that leaves an operator with
+ * no exit — the lesson of #138, and why this is a function rather than one boolean.
+ *
+ * By default: a grant that only lets another account *read* is reported, because that is
+ * where Windows is muddier than POSIX and refusing over it stranded a real operator. A
+ * grant that lets another account *change* the config is refused, because that is an
+ * authorization bypass and Windows is not muddy about it. An ACL that could not be
+ * determined is refused too — #138 was a known-bad verdict, never an undeterminable one,
+ * and flipping those open would let an attacker swap a loud finding for a vague one for
+ * free. The two exceptions stay: `icacls` absent, and the check running out of time, both
+ * statements about the machine rather than about the file.
+ *
+ * `--allowUncheckedConfigAcl` reports everything and refuses nothing — the single exit.
+ * `--strictConfigAcl` refuses everything the check objects to, read-only grants included.
+ */
+function waived(finding, opts) {
+    if (opts.allowUnchecked)
+        return true;
+    if (opts.enforce)
+        return false;
+    if (finding.status === 'unchecked') {
+        return finding.reason === 'tool-missing' || finding.reason === 'timed-out';
+    }
+    // A NULL DACL is full control for everyone, so it is never read-only.
+    return finding.status === 'broad' && !finding.grants.some((g) => g.writes);
+}
+/**
+ * Report what a config's ACL grants beyond its owner, and refuse when it is not merely
+ * readable — the Windows half of `checkPermissions`.
+ *
+ * Both the file and its directory are examined. What happens to a finding is
+ * `waived`'s decision; see it for the three postures and why the default is not to refuse
+ * a read-only over-grant.
  */
 export async function assertPrivateOnWindows(filePath, opts = {}, inspect) {
     // One deadline for the whole check, shared by every subprocess it starts.
@@ -748,44 +896,20 @@ export async function assertPrivateOnWindows(filePath, opts = {}, inspect) {
         const signal = AbortSignal.timeout(ACL_TIMEOUT_MS);
         return raceDeadline(inspectAcl(p, signal), signal);
     });
-    const report = opts.onUnverified ?? ((e) => {
-        console.error(`Warning: the ACL of ${e.path} was not checked (${e.reason}: ${e.detail}), so whether ` +
-            'other accounts can read your config is unverified. Loading it anyway.');
-    });
+    const report = opts.onFinding ?? ((f) => console.error(`Warning: ${f.message}`));
     const subjects = [
         { path: filePath, kind: 'file' },
         { path: parsePath(filePath).dir || '.', kind: 'directory' },
     ];
     for (const { path, kind } of subjects) {
-        const verdict = await look(path);
-        if (verdict.status === 'restricted')
+        const finding = describe(path, kind, await look(path));
+        if (finding === null)
             continue;
-        if (verdict.status === 'broad' || verdict.status === 'no-dacl') {
-            const grants = verdict.status === 'broad' ? verdict.grants : [];
-            const what = verdict.status === 'broad'
-                ? `is readable beyond its owner: access is granted to ${grants.map((g) => g.name).join(', ')}. ` +
-                    'Required: this account, SYSTEM and Administrators only.'
-                : 'has no access control list at all, which on Windows means full control for ' +
-                    'every account on the machine.';
-            const message = `Config ${kind} ${path} ${what}\n` +
-                (isTightenable(path, kind) ? remediation(path, kind, grants) : relocation(path, kind, grants));
-            if (opts.strict)
-                throw new OperatorError(message);
-            // Advisory by default; see AclOptions.strict for why.
-            console.error(`Warning: ${message}`);
-            continue;
-        }
-        // status === 'unknown'
-        if (!opts.strict || verdict.reason === 'tool-missing' || verdict.reason === 'timed-out'
-            || opts.allowUnchecked) {
-            report({ path, reason: verdict.reason, detail: verdict.detail });
-            continue;
-        }
-        throw new OperatorError(`Config ${kind} ${path} could not be checked for access by other accounts ` +
-            `(${verdict.reason}: ${verdict.detail}).\n` +
-            'Refused because --strictConfigAcl was given, and the config decides which hosts, ' +
-            'roles and policy rules this server honours.\n' +
-            'Either fix the cause, move the config under %APPDATA%\\ssh-mcp, or pass ' +
-            '--allowUncheckedConfigAcl to load it unverified.');
+        // One decision, read once. Refusing and reporting used to be decided in three places —
+        // twice on the same flag for the same question — with two `continue`s and two throw
+        // sites, and the advisory path wrote to stderr directly rather than through the sink.
+        if (!waived(finding, opts))
+            throw new OperatorError(finding.message);
+        report(finding);
     }
 }

package/build/index.js

@@ -115,12 +115,13 @@ export function resolveHostGroup(argv) {
     throw new OperatorError(`Invalid --group=${group}. Expected one of: ${HOST_GROUPS.join(', ')}.`);
 }
 /**
- * ACL checks that could not be performed, in the order they happened.
+ * Every ACL finding, in the order it happened — both "readable beyond its owner" and
+ * "could not be checked".
  *
  * Collected rather than only printed so `main()` can act on them once there is somewhere
  * durable to put them; see the note at the sink below.
  */
-const unverified = [];
+const aclFindings = [];
 async function buildAppConfig(argv) {
     // The way past an ACL that could not be read, rather than an operator with no
     // exit. See assertPrivateOnWindows.
@@ -130,12 +131,11 @@ async function buildAppConfig(argv) {
     // the audit store as well needs an AuditRecord variant for a startup event — that type
     // is hash-chained and tamper-evident, so it is its own change, and it is queued.
     const aclOpts = {
-        strict: flagEnabled(argv, 'strictConfigAcl'),
+        enforce: flagEnabled(argv, 'strictConfigAcl'),
         allowUnchecked: flagEnabled(argv, 'allowUncheckedConfigAcl'),
-        onUnverified: (e) => {
-            unverified.push(e);
-            console.error(`Warning: the ACL of ${e.path} was not checked (${e.reason}: ${e.detail}), so ` +
-                'whether other accounts can read your config is unverified. Loading it anyway.');
+        onFinding: (f) => {
+            aclFindings.push(f);
+            console.error(`Warning: ${f.message}`);
         },
     };
     if (argv.config !== undefined) {

package/package.json

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