@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/collectors/mcp.js

@@ -1,25 +1,8 @@
 "use strict";
 
 /**
- * lib/collectors/mcp.js
- *
- * Companion collector for the `mcp` playbook. Reads MCP client
- * config files (Cursor, Claude Code, Windsurf, VS Code Copilot,
- * Gemini CLI) and tool-response logs, flipping deterministic
- * indicators related to:
- *   - mcp-version-without-integrity (pinned version without
- *     sha256 / sri-integrity sibling)
- *   - copilot-yolo-mode-flag (chat.tools.autoApprove true)
- *   - mcp-response-ansi-escape (0x1B in tool response)
- *   - mcp-response-unicode-tag-smuggling (U+E0000..U+E007F)
- *
- * Defers:
- *   - unsigned-mcp-manifest (needs npm/pip package directory walk
- *     + sigstore lookup; out of stdlib scope)
- *   - vulnerable-windsurf-version (needs Windsurf install detection)
- *   - mcp-server-running-as-root (needs ps + capabilities)
- *   - mcp-server-invoked-from-ci-pipeline (needs process-tree
- *     env-var inspection)
+ * Companion collector for the `mcp` playbook: reads MCP client configs and
+ * tool-response logs, flipping only the indicators decidable from those.
  *
  * Interface: see lib/collectors/README.md
  */
@@ -36,10 +19,8 @@ function readSafe(full, max = 1024 * 1024) {
     fd = fs.openSync(full, "r");
     const s = fs.fstatSync(fd);
     if (s.size > max) return null;
-    // readFileSync(fd) loops read() to EOF — a single readSync may return
-    // fewer than s.size bytes on network/FUSE/sync-backed fds, which would
-    // leave the buffer tail NUL-filled and silently drop trailing content.
-    // Reading via the already-open fd keeps the fstat-then-read TOCTOU-free.
+    // readFileSync(fd) loops read() to EOF, where one readSync can return short on
+    // a network/FUSE fd and NUL-fill the tail; via the fd it is also TOCTOU-free.
     return fs.readFileSync(fd, "utf8");
   } catch { return null; }
   finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } } }
@@ -55,9 +36,8 @@ function fileExists(full) {
   try { return fs.statSync(full).isFile(); } catch { return false; }
 }
 
-// Per-vendor config locations. We try each and capture which were
-// present so the artifact field tells the operator what scope the
-// collector actually exercised.
+// Per-vendor config locations; presence is recorded so the artifact shows the
+// scope the collector actually exercised.
 function vendorConfigPaths(home) {
   return {
     cursor: [path.join(home, ".cursor", "mcp.json")],
@@ -67,7 +47,6 @@ function vendorConfigPaths(home) {
     ],
     windsurf: [path.join(home, ".codeium", "windsurf", "mcp_config.json")],
     "vscode-copilot": [
-      // user-global locations
       path.join(home, ".config", "Code", "User", "settings.json"),
       path.join(home, "Library", "Application Support", "Code", "User", "settings.json"),
       path.join(home, "AppData", "Roaming", "Code", "User", "settings.json"),
@@ -85,9 +64,8 @@ function collectMcpServers(configsByVendor) {
     for (const f of files) {
       const j = readJson(f);
       if (!j) continue;
-      // Cursor / Claude Code / Windsurf: { mcpServers: { <name>: {...} } }
-      // VS Code Copilot: { chat: { mcp: { servers: { <name>: {...} } } } }
-      // Gemini: { mcpServers: { <name>: {...} } }
+      // Cursor / Claude Code / Windsurf / Gemini nest servers under
+      // `mcpServers`; VS Code Copilot under `chat.mcp.servers`, flat or nested.
       const containers = [
         j.mcpServers,
         j["chat.mcp.servers"],
@@ -109,10 +87,8 @@ function collectMcpServers(configsByVendor) {
   return out;
 }
 
-// A pinned version is the @1.2.3 / @v1.2.3 / =1.2.3 trailer on a
-// package spec in args[] or command. We look for shapes that
-// downstream operators care about: `npx -y @vendor/pkg@1.2.3`,
-// `uvx pkg==1.2.3`, `pip install pkg==1.2.3`, etc.
+// A pinned version is the `@1.2.3` / `==1.2.3` trailer on a package spec in
+// args[] or command — `npx -y @vendor/pkg@1.2.3`, `uvx pkg==1.2.3`.
 function isPinnedNoIntegrity(server) {
   if (server.integrity) return false;
   const tokens = [server.command, ...server.args].filter(Boolean);
@@ -120,20 +96,14 @@ function isPinnedNoIntegrity(server) {
     if (typeof tok !== "string") continue;
     // npm package@version (excluding scope name@version)
     if (/@[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+@\d+\.\d+\.\d+\b/.test(tok)) return true;
-    // A `==X.Y.Z` pin (pip/uvx/poetry) with no integrity is the python analog
-    // of the npm pin above. A single-token launch command like
-    // `sh -c "pip install some-mcp==1.2.3"` carries the whole pip invocation in
-    // one token, so testing the token for `pip install` and `continue`-ing here
-    // skipped the `==version` check below for exactly the shape the comment
-    // says operators care about. A bare `pip install requests` (no `==`) can't
-    // match the pin regex, so checking every token is safe.
+    // The pip / uvx analog. Every token is tested rather than pre-filtering on
+    // `pip install`, since `sh -c "pip install some-mcp==1.2.3"` is one token.
     if (/==\d+\.\d+\.\d+/.test(tok)) return true;
   }
   return false;
 }
 
-// VS Code yolo-mode flag: chat.tools.autoApprove === true OR any
-// per-tool autoApprove === true.
+// VS Code yolo mode: chat.tools.autoApprove, or any per-tool autoApprove.
 function hasYoloMode(j) {
   if (!j || typeof j !== "object") return false;
   if (j["chat.tools.autoApprove"] === true) return true;
@@ -153,9 +123,8 @@ function hasAnsiEscape(content) {
   return content.indexOf("\x1b") !== -1;
 }
 
-// Unicode tag smuggling: codepoints in U+E0000..U+E007F. These are
-// invisible in normal renders but carry instruction-coercion
-// payloads through MCP responses.
+// Unicode tag smuggling: U+E0000..U+E007F are invisible in a normal render but
+// carry instruction-coercion payloads through MCP responses.
 function hasUnicodeTagSmuggling(content) {
   for (let i = 0; i < content.length; i++) {
     const code = content.codePointAt(i);
@@ -167,11 +136,8 @@ function hasUnicodeTagSmuggling(content) {
 }
 
 function findMcpLogs(home) {
-  // Candidate log directories per vendor. Caller scans each for
-  // *.jsonl / *.log files. Directories like ~/.claude/logs/mcp/ are
-  // already MCP-scoped by path; we accept every log file inside.
-  // Generic log directories (~/.cursor/logs/) are filtered to
-  // filenames containing "mcp".
+  // A path already MCP-scoped (~/.claude/logs/mcp/) accepts every log file
+  // inside; a generic one (~/.cursor/logs/) is filtered to names holding "mcp".
   const dirs = [
     { path: path.join(home, ".claude", "logs", "mcp"), filterByName: false },
     { path: path.join(home, ".cursor", "logs"), filterByName: true },
@@ -197,26 +163,22 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const root = path.resolve(cwd);
   const home = (env && env.HOME) || (env && env.USERPROFILE) || os.homedir();
 
-  // Vendor MCP configs.
   const configsByVendor = vendorConfigPaths(home);
   const servers = collectMcpServers(configsByVendor);
   const pinnedNoIntegrity = servers.filter(isPinnedNoIntegrity);
 
-  // VS Code yolo-mode across the candidate VS Code settings files.
   let yoloHit = false;
   let yoloFile = null;
   for (const f of configsByVendor["vscode-copilot"]) {
     const j = readJson(f);
     if (j && hasYoloMode(j)) { yoloHit = true; yoloFile = f; break; }
   }
-  // Project-level .vscode/settings.json under cwd
   if (!yoloHit) {
     const projVsc = path.join(root, ".vscode", "settings.json");
     const j = readJson(projVsc);
     if (j && hasYoloMode(j)) { yoloHit = true; yoloFile = projVsc; }
   }
 
-  // MCP response log scan for ANSI / unicode-tag smuggling.
   const logFiles = findMcpLogs(home);
   let ansiHit = false;
   let unicodeTagHit = false;
@@ -239,10 +201,8 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     "mcp-version-without-integrity": pinnedNoIntegrity.length > 0 ? "hit" : "miss",
     "copilot-yolo-mode-flag": yoloHit ? "hit" : "miss",
   };
-  // ANSI / unicode-tag indicators: only emit when we actually
-  // scanned at least one log file. If no logs exist, leave the
-  // indicators unflipped (the operator may not have enabled MCP
-  // logging — the runner returns inconclusive).
+  // Emitted only when a log file was actually scanned: with none, the indicators
+  // stay unflipped and the runner returns inconclusive.
   if (logsScanned) {
     signal_overrides["mcp-response-ansi-escape"] = ansiHit ? "hit" : "miss";
     signal_overrides["mcp-response-unicode-tag-smuggling"] = unicodeTagHit ? "hit" : "miss";
@@ -298,17 +258,11 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     },
   };
 
-  // Attest any-ai-coding-assistant-installed (skip_phase gate) ONLY when a
-  // client is confirmed present — an install directory the precondition itself
-  // recognises (exists($HOME/.cursor)||.codeium/windsurf||.config/claude||
-  // .config/Code||.gemini), OR a vendor config file we found. The runner can't
-  // resolve the exists() DSL against the scanned home, so without this a host
-  // that clearly has a client surfaces a spurious precondition_unverified.
-  // Crucially we NEVER submit false: the gate is skip_phase, so a false on a
-  // config-file-only absence would wrongly skip the detect phase even when an
-  // installed client directory or a project-level signal (e.g. a .vscode
-  // Copilot config) exists. When presence can't be confirmed, leave the gate
-  // unsubmitted and let the host-side resolver decide.
+  // Attest the any-ai-coding-assistant-installed skip_phase gate ONLY when a
+  // client is confirmed present; unconfirmed leaves it for the host-side
+  // resolver. Never submit false: the gate is skip_phase, so a false on a
+  // config-file absence would skip detect on a host that has an installed client
+  // directory or a project-level Copilot config.
   const assistantInstallDirs = [
     ".cursor",
     path.join(".codeium", "windsurf"),

package/lib/collectors/runtime.js

@@ -1,17 +1,9 @@
 "use strict";
 
 /**
- * lib/collectors/runtime.js
- *
- * Companion collector for the `runtime` playbook. Linux-only:
- * walks /etc/sudoers + /etc/sudoers.d/*, parses /etc/passwd for
- * duplicate UID 0 entries, scans well-known trusted-path
- * directories for world-writable files, and inspects /proc/<pid>
- * for orphan-privileged processes. Defers non-deterministic
- * indicators (non-baseline-suid, listening-socket-unknown-bind,
- * cron-or-timer-outside-policy) so the runner returns inconclusive.
- *
- * Interface: see lib/collectors/README.md
+ * Companion collector for the `runtime` playbook. Linux-only, deterministic
+ * indicators only — anything it cannot settle stays unflipped for the runner to
+ * call inconclusive. Interface: see lib/collectors/README.md
  */
 
 const fs = require("node:fs");
@@ -25,10 +17,8 @@ function readFileSafe(p, max = 512 * 1024) {
     fd = fs.openSync(p, "r");
     const s = fs.fstatSync(fd);
     if (s.size > max) return null;
-    // readFileSync(fd) loops read() to EOF — a single readSync may return
-    // fewer than s.size bytes on network/FUSE/sync-backed fds, which would
-    // leave the buffer tail NUL-filled and silently drop trailing content.
-    // Reading via the already-open fd keeps the fstat-then-read TOCTOU-free.
+    // readFileSync(fd) loops to EOF; a single readSync can short-read a network
+    // fd. Reading through the open fd also keeps the fstat-then-read TOCTOU-free.
     return fs.readFileSync(fd, "utf8");
   } catch { return null; }
   finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } } }
@@ -36,10 +26,7 @@ function readFileSafe(p, max = 512 * 1024) {
 
 const NOPASSWD_WILDCARD_RE = /\bNOPASSWD:\s*(?:ALL|\/[^,\n]*\*)/;
 
-// Trusted-path roots scanned for world-writable files. The
-// playbook explicitly lists /etc, /usr/local/bin, /usr/local/sbin,
-// /opt. We add /usr/bin and /usr/sbin as common variants but stay
-// shallow (depth 2) so we don't walk arbitrarily deep filesystems.
+// World-writable scan roots; the depth cap keeps the walk off deep filesystems.
 const TRUSTED_PATHS = ["/etc", "/usr/local/bin", "/usr/local/sbin", "/opt", "/usr/bin", "/usr/sbin"];
 const TRUSTED_PATH_MAX_DEPTH = 2;
 
@@ -56,11 +43,8 @@ function parseSudoersForWildcards(content) {
     const line = raw.replace(/#.*$/, "").trim();
     if (!line) continue;
     if (!NOPASSWD_WILDCARD_RE.test(line)) continue;
-    // Sudoers entries lead with a comma-separated user/group list:
-    //   `<user1>,<user2>,%group  host = (runas) NOPASSWD: cmd*`
-    // Skip ONLY when the user list is exactly `root` (no other
-    // principals). A line like `root,deploy ALL=(ALL) NOPASSWD: ALL`
-    // still grants wildcard sudo to `deploy` and counts as a hit.
+    // Skip only when the principal list is exactly `root` — `root,deploy ALL=(ALL)
+    // NOPASSWD: ALL` still grants wildcard sudo to deploy and counts as a hit.
     const userListMatch = line.match(/^([^\s]+)\s/);
     if (userListMatch) {
       const principals = userListMatch[1].split(",").map(s => s.trim()).filter(Boolean);
@@ -113,12 +97,8 @@ function isWorldWritable(p) {
   } catch { return false; }
 }
 
-// Classify a world-writable hit against the two deterministic
-// false_positive_checks_required entries for world-writable-in-trusted-path:
-//   [0] sticky-bit (1777-style) dirs/files intentionally permit per-user write
-//   [1] 0-byte stamp / unix-socket / FIFO documented for the application
-// Returns { stickyBit, special } so the caller can both keep only genuine
-// hits and attest exactly the checks it ran.
+// The two deterministic FP checks on world-writable-in-trusted-path: [0] sticky-bit
+// per-user-write, [1] 0-byte stamp / socket / FIFO. The caller drops carriers.
 function classifyWorldWritable(p) {
   try {
     const s = fs.lstatSync(p);
@@ -150,33 +130,21 @@ function readProcPid(pid, procRoot) {
 }
 
 function scanOrphanPrivileged(procRoot) {
-  // Returns { hits, exeReadable }. exeReadable is false when at
-  // least one candidate PID (UID 0, PPID 1) had an unreadable
-  // /proc/<pid>/exe symlink AND PID 1's exe was also unreadable —
-  // in that case the indicator MUST stay unflipped (the caller
-  // converts that to inconclusive). hidepid / ptrace-restrict /
-  // non-root scope all collapse exe readability to zero, and
-  // emitting "miss" there would mask real privileged orphans.
+  // Returns { hits, exeReadable }. exeReadable false means no exe-link visibility
+  // and the caller must leave the indicator unflipped — a "miss" masks real orphans.
   let entries;
   try { entries = fs.readdirSync(procRoot); } catch { return { hits: [], exeReadable: false }; }
   const hits = [];
 
-  // PID 1's exe is the canonical anchor. If we can't read it, we
-  // can't tell whether the parent is canonical init or a hijacked
-  // PID 1. That's an inconclusive condition.
+  // PID 1's exe is the anchor: unreadable, canonical init and a hijacked PID 1 look alike.
   const initProc = readProcPid(1, procRoot);
   const initExeReadable = !!(initProc && initProc.exe);
   if (!initExeReadable) return { hits: [], exeReadable: false };
   if (!PARENT_INIT_BINARIES.has(initProc.exe)) {
-    // PID 1's exe is readable but isn't a canonical init. Treat
-    // as inconclusive — the playbook predicate explicitly says
-    // "parent != systemd/init" is the orphan condition, but
-    // distinguishing a legitimate non-systemd init (e.g. SysV,
-    // BusyBox init) from a hijacked PID 1 needs operator review.
+    // Not a canonical init: SysV / BusyBox vs a hijacked PID 1 needs operator review.
     return { hits: [], exeReadable: false };
   }
 
-  // PID 1's exe is canonical init. Now scan candidate PIDs.
   let anyExeReadable = false;
   let anyExeUnreadable = false;
   for (const name of entries) {
@@ -194,12 +162,7 @@ function scanOrphanPrivileged(procRoot) {
       anyExeUnreadable = true;
     }
   }
-  // If we couldn't read ANY candidate's exe (typical non-root /
-  // hidepid scope), the indicator stays unflipped. If we read at
-  // least one and saw zero risky-path orphans, the miss is
-  // honest. If we saw mixed (some readable, some not), still
-  // report what we found — but only emit a verdict when at least
-  // one exe was readable so we have evidence to back it.
+  // A verdict needs at least one readable exe behind it; with none, it stays unflipped.
   const exeReadable = anyExeReadable || (!anyExeUnreadable && entries.length > 0);
   return { hits, exeReadable };
 }
@@ -240,14 +203,12 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     };
   }
 
-  // Sudo rules: /etc/sudoers + /etc/sudoers.d/*
   const sudoersBase = readFileSafe(P.sudoers);
   let sudoersContent = sudoersBase || "";
   let sudoersReadable = sudoersBase != null;
   try {
     const dEntries = fs.readdirSync(P.sudoersD);
     for (const e of dEntries) {
-      // skip editor backup files (~, .bak, .swp)
       if (/[~]$/.test(e) || /\.(bak|swp|orig)$/.test(e)) continue;
       const c = readFileSafe(path.join(P.sudoersD, e));
       if (c != null) {
@@ -258,16 +219,10 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   } catch { /* .d not present */ }
   const sudoersHits = parseSudoersForWildcards(sudoersContent);
 
-  // /etc/passwd UID-zero count
   const passwdContent = readFileSafe(P.passwd);
   const uid0 = passwdContent ? parsePasswdUidZero(passwdContent) : null;
 
-  // World-writable files under trusted paths. Split into genuine hits
-  // (regular non-empty files without the sticky bit) and benign carriers
-  // the two false_positive_checks_required entries demote (sticky-bit
-  // per-user-write dirs; 0-byte stamps / sockets / FIFOs). Only the
-  // genuine hits flip the indicator; the split records which FP checks
-  // the collector deterministically ran.
+  // Genuine hits are regular non-empty files without the sticky bit; carriers are demoted.
   const worldWritableFiles = [];
   let sawStickyBitCarrier = false;
   let sawSpecialCarrier = false;
@@ -281,8 +236,6 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     }
   }
 
-  // Orphan-privileged process scan. Only meaningful on a real
-  // /proc; on a synthetic tempdir we still walk it the same way.
   const orphanScan = scanOrphanPrivileged(P.procRoot);
 
   const signal_overrides = {};
@@ -292,29 +245,21 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   if (uid0 !== null) {
     signal_overrides["duplicate-uid-zero"] = uid0.length > 1 ? "hit" : "miss";
   }
-  // world-writable-in-trusted-path: only emit a verdict if at least
-  // one trusted path was readable. If every TP was unreadable
-  // (chroot / restricted container), leave the indicator unflipped.
+  // A verdict needs one readable trusted path; an all-unreadable scope stays unflipped.
   const anyTpReadable = P.trustedPaths.some(tp => {
     try { fs.readdirSync(tp); return true; } catch { return false; }
   });
   if (anyTpReadable) {
     const wwHit = worldWritableFiles.length > 0;
     signal_overrides["world-writable-in-trusted-path"] = wwHit ? "hit" : "miss";
-    // Attest the false_positive_checks_required entries the collector
-    // ran against every flagged file: [0] sticky-bit carriers and [1]
-    // 0-byte/socket/FIFO carriers were both stat-inspected and excluded,
-    // so a surviving hit satisfies both. Without this attestation the
-    // runner downgrades a real world-writable hit to inconclusive.
+    // Both FP checks ran against every flagged file, so a surviving hit satisfies
+    // them; without this attestation the runner downgrades the hit to inconclusive.
     if (wwHit) {
       signal_overrides["world-writable-in-trusted-path__fp_checks"] = { "0": true, "1": true };
     }
   }
-  // orphan-privileged-process: only emit when /proc was walkable
-  // AND the scan had enough exe-link visibility to reach a verdict.
-  // hidepid / ptrace-restrict / non-root scope leaves
-  // exeReadable=false; the indicator stays unflipped so the runner
-  // returns inconclusive (codex P1 #80).
+  // A verdict needs a walkable /proc and exe-link visibility; otherwise exeReadable
+  // is false and the indicator stays unflipped.
   let procWalkable = false;
   try { fs.readdirSync(P.procRoot); procWalkable = true; } catch { /* not present */ }
   if (procWalkable && orphanScan.exeReadable) {
@@ -341,16 +286,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   return {
     precondition_checks: {
       "linux-platform": true,
-      // The collector performs a read-only inventory directly via fs (reads
-      // /etc/sudoers, /etc/passwd, /proc/<pid>/status) and execs no commands,
-      // so the `exec-allowed` precondition ('permitted to execute read-only
-      // inventory commands') is satisfied by construction once the collection
-      // reaches at least one inventory source. The runner cannot mechanically
-      // resolve `agent_has_command_exec == true`, so without this attestation
-      // the on_fail=halt preflight blocked the canonical `collect runtime | run
-      // runtime` pipe even with valid evidence — the sibling fs-only cred-stores
-      // collector attests its own halt precondition the same way. Gated on
-      // readability so a fully-masked /proc+/etc scope reports it false.
+      // The collector execs nothing, so `exec-allowed` holds by construction; the
+      // runner cannot resolve `agent_has_command_exec` mechanically and its
+      // on_fail=halt preflight would block `collect runtime | run runtime`.
       "exec-allowed": Boolean(sudoersReadable || passwdContent != null || procWalkable || anyTpReadable),
     },
     artifacts,