residoo 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Find secrets leaking through your AI coding agent's session history. Zero network calls in the scan path, zero dependencies.",
   "license": "MIT",
   "author": "CloudRoam (https://cloudroam.io)",

package/src/cli.js

@@ -175,7 +175,8 @@ Watch:
   --verify                same opt-in vendor check as scan --verify,
                           applied to each newly found credential once,
                           never to one already seen
-  --include-noisy, --include-suppressed, --no-color   same meaning as scan
+  --include-noisy, --include-suppressed, --include-pii, --no-color
+                          same meaning as scan
   Ctrl+C stops cleanly and prints a session summary (skipped with --json,
   where the same information is one final NDJSON event).
 
@@ -663,6 +664,7 @@ async function runWatch(args) {
   const includeSuppressed = args.includes("--include-suppressed");
   const verify = args.includes("--verify");
   const noColor = args.includes("--no-color");
+  const includePii = args.includes("--include-pii");
 
   let intervalSeconds = 5;
   const intervalArg = argValue(args, "--interval");
@@ -688,7 +690,7 @@ async function runWatch(args) {
 
   const { promise, stop } = startWatch({
     sources,
-    options: { includeNoisy, includeSuppressed, verify, noColor, json: wantsJson, pollMs: intervalSeconds * 1000 },
+    options: { includeNoisy, includeSuppressed, verify, noColor, includePii, json: wantsJson, pollMs: intervalSeconds * 1000 },
   });
 
   const printFinalSummary = (stats) => {

package/src/integrity.js

@@ -677,6 +677,79 @@ function checkIntegrity({ home = os.homedir(), cwd = process.cwd(), projectMode
     }
   }
 
+  // ---- 5. credential-vault file permissions (HOME only, POSIX only) ------
+  // GitGuardian's "State of Secrets Sprawl 2026" (blog.gitguardian.com,
+  // published 2026-03-17) found 24,008 unique secrets in MCP-related config
+  // files on public GitHub, 8.8% of them still live -- these files
+  // routinely hold real, working credentials. This does not scan their
+  // CONTENT: the files below are the exact "credential VAULTS ... deliberately
+  // NOT read" set from agent-configs.js's own header comment, files whose
+  // whole documented job is holding the user's own keys/tokens -- reporting
+  // their content re-reports what the user put there on purpose. What's
+  // checked instead is narrower and complementary: whether the file's own OS
+  // permission bits leak that live credential to every other account on the
+  // machine. Anthropic's own docs (code.claude.com/docs/en/authentication,
+  // "Credential management", fetched 2026-09-04) state Claude Code writes
+  // .credentials.json with file mode 0600 on Linux and as the macOS
+  // Keychain-write-failure fallback, and that Windows inherits its user
+  // profile directory's own access controls. Kiro's own security guidance
+  // separately recommends "chmod 600" on its global mcp.json -- the
+  // vendor's own admission it holds secrets (already cited in
+  // agent-configs.js). Nothing here disputes that these tools do the right
+  // thing by default; the point is drift AFTER that -- a WSL DrvFs mount, a
+  // naive backup restore, or a shared-volume container mount can each
+  // silently widen a file's mode without the tool that wrote it ever
+  // knowing, the same way SSH itself checks id_rsa's permissions rather
+  // than trusting whoever created it. Windows is skipped entirely, not
+  // approximated: Node's fs.Stats.mode on Windows does not reflect NTFS
+  // ACLs, so a POSIX-style bit check there would be meaningless rather than
+  // merely imprecise. Project mode is skipped too -- none of these are ever
+  // project-scoped files by any vendor's own design, so there is no
+  // project-relative equivalent to check.
+  if (!projectMode && process.platform !== "win32") {
+    const geminiDir = process.env.GEMINI_CLI_HOME
+      ? path.join(process.env.GEMINI_CLI_HOME, ".gemini")
+      : path.join(home, ".gemini");
+    const credentialVaultFiles = [
+      {
+        file: path.join(process.env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"), ".credentials.json"),
+        note: "Claude Code's OAuth login (code.claude.com/docs/en/authentication documents file mode 0600)",
+      },
+      {
+        file: path.join(process.env.CODEX_HOME || path.join(home, ".codex"), "auth.json"),
+        note: "Codex CLI's own auth store",
+      },
+      { file: path.join(geminiDir, "oauth_creds.json"), note: "Gemini CLI's own OAuth store" },
+      { file: path.join(geminiDir, ".env"), note: "Gemini CLI's own credential env file" },
+      {
+        file: path.join(home, ".kiro", "settings", "mcp.json"),
+        note: "Kiro's own security guidance recommends chmod 600 on this file",
+      },
+    ];
+    for (const { file, note } of credentialVaultFiles) {
+      const r = path.resolve(file);
+      if (seen.has(r)) continue;
+      seen.add(r);
+      let stat;
+      try { stat = fs.statSync(file); }
+      catch (err) {
+        mark(file, err && err.code === "ENOENT" ? "absent" : "unreadable");
+        if (!(err && err.code === "ENOENT")) {
+          add("warn", "unreadable-config", file, "credential file exists but its permissions could not be checked (stat failed): unverified, not clean");
+        }
+        continue;
+      }
+      mark(file, "checked");
+      const openBits = stat.mode & 0o077;
+      if (openBits !== 0) {
+        const octal = (stat.mode & 0o777).toString(8).padStart(3, "0");
+        const shown = display(file);
+        add("warn", "insecure-credential-permissions", file,
+          `${note}; current mode ${octal} grants group and/or other accounts on this machine access to a live credential. Fix: chmod 600 "${shown}"`);
+      }
+    }
+  }
+
   return {
     findings,
     filesChecked,

package/src/mcpTools.js

@@ -50,11 +50,20 @@ function rejectUnknownKeys(args, allowed) {
   return errs;
 }
 
-/** Shared arg shape for residoo_scan/residoo_check: includeNoisy, includeSuppressed, maxEntries. */
+/**
+ * Shared arg shape for residoo_scan/residoo_check: includeNoisy,
+ * includeSuppressed, includePii, maxEntries. includePii is exposed here
+ * (unlike ocr or verify, see this file's own header comment on verify's
+ * exclusion) because it is architecturally identical to includeNoisy --
+ * local-only, no network call, no external process, just a different
+ * detection category (see pii.js) -- not the network/live-secret trust
+ * boundary verify's own exclusion is specifically about.
+ */
 function validateSweepArgs(args, allowedKeys) {
   const errs = rejectUnknownKeys(args, allowedKeys);
   if (args.includeNoisy !== undefined && typeof args.includeNoisy !== "boolean") errs.push("includeNoisy must be a boolean");
   if (args.includeSuppressed !== undefined && typeof args.includeSuppressed !== "boolean") errs.push("includeSuppressed must be a boolean");
+  if (args.includePii !== undefined && typeof args.includePii !== "boolean") errs.push("includePii must be a boolean");
   let maxEntries = 25;
   if (args.maxEntries !== undefined) {
     if (typeof args.maxEntries !== "number" || !Number.isInteger(args.maxEntries) || args.maxEntries < 1 || args.maxEntries > 200) {
@@ -63,7 +72,10 @@ function validateSweepArgs(args, allowedKeys) {
       maxEntries = args.maxEntries;
     }
   }
-  return { errs, includeNoisy: args.includeNoisy === true, includeSuppressed: args.includeSuppressed === true, maxEntries };
+  return {
+    errs, includeNoisy: args.includeNoisy === true, includeSuppressed: args.includeSuppressed === true,
+    includePii: args.includePii === true, maxEntries,
+  };
 }
 
 /** Drop the full step-by-step runbook (redundant once per shared rule id across many entries -- call residoo_explain for that) and any null-valued optional field. */
@@ -122,8 +134,8 @@ function buildTools({ sources }) {
   let checkStarted = false;
 
   async function handleScan(args) {
-    const SCAN_KEYS = new Set(["projectDir", "includeNoisy", "includeSuppressed", "maxEntries"]);
-    const { errs, includeNoisy, includeSuppressed, maxEntries } = validateSweepArgs(args, SCAN_KEYS);
+    const SCAN_KEYS = new Set(["projectDir", "includeNoisy", "includeSuppressed", "includePii", "maxEntries"]);
+    const { errs, includeNoisy, includeSuppressed, includePii, maxEntries } = validateSweepArgs(args, SCAN_KEYS);
     if (args.projectDir !== undefined && typeof args.projectDir !== "string") errs.push("projectDir must be a string");
     if (errs.length) return errorResult(`Invalid arguments: ${errs.join("; ")}`);
 
@@ -140,7 +152,7 @@ function buildTools({ sources }) {
       scanSources = sources;
     }
 
-    const result = await scan({ sources: scanSources, includeNoisy, includeSuppressed, verify: false, noColor: true });
+    const result = await scan({ sources: scanSources, includeNoisy, includeSuppressed, includePii, verify: false, noColor: true });
     const acks = loadAcks();
     const dismissed = loadDismissed();
     const rotation = renderRotation(result.findings, acks, dismissed);
@@ -167,8 +179,8 @@ function buildTools({ sources }) {
   }
 
   async function handleCheck(args) {
-    const CHECK_KEYS = new Set(["includeNoisy", "includeSuppressed", "maxEntries"]);
-    const { errs, includeNoisy, includeSuppressed, maxEntries } = validateSweepArgs(args, CHECK_KEYS);
+    const CHECK_KEYS = new Set(["includeNoisy", "includeSuppressed", "includePii", "maxEntries"]);
+    const { errs, includeNoisy, includeSuppressed, includePii, maxEntries } = validateSweepArgs(args, CHECK_KEYS);
     if (errs.length) return errorResult(`Invalid arguments: ${errs.join("; ")}`);
 
     const firstCheckThisSession = !checkStarted;
@@ -179,7 +191,7 @@ function buildTools({ sources }) {
     const emit = (e) => events.push(e);
     const stats = await sweepOnce({
       sources, tracked: checkTracked, seen: checkSeen, ledger,
-      options: { includeNoisy, includeSuppressed, verify: false, noColor: true }, emit,
+      options: { includeNoisy, includeSuppressed, includePii, verify: false, noColor: true }, emit,
     });
 
     const allNew = events.filter((e) => e.type === "finding");
@@ -353,6 +365,7 @@ function buildTools({ sources }) {
         projectDir: { type: "string", description: "Absolute path to a project/repo directory to scan instead of the machine-wide transcript stores (same as `residoo scan --project <dir>`). Omit for the default machine-wide scan." },
         includeNoisy: { type: "boolean", default: false, description: "Also run residoo's two low-confidence heuristic rules (generic password/secret assignments) -- catches more, false-positives more. Off by default." },
         includeSuppressed: { type: "boolean", default: false, description: "Include matches normally hidden because they look like vendor-documented example values or placeholder text. Off by default." },
+        includePii: { type: "boolean", default: false, description: "Also scan for PII (US Social Security Numbers, Luhn-validated credit card numbers, checksum-validated IBANs) -- a different risk category from a credential, not a lower confidence bar. Off by default; residoo is deliberately credentials-only otherwise." },
         maxEntries: { type: "integer", minimum: 1, maximum: 200, default: 25, description: "Cap on distinct findings returned in full detail, pending-first. Counts in the response are always exact even when the entry list is truncated." },
       },
       required: [],
@@ -368,6 +381,7 @@ function buildTools({ sources }) {
       properties: {
         includeNoisy: { type: "boolean", default: false, description: "Same meaning as residoo_scan." },
         includeSuppressed: { type: "boolean", default: false, description: "Same meaning as residoo_scan." },
+        includePii: { type: "boolean", default: false, description: "Same meaning as residoo_scan." },
         maxEntries: { type: "integer", minimum: 1, maximum: 200, default: 25, description: "Cap on new findings / re-exposures returned in full detail. Counts are always exact even when truncated." },
       },
       required: [],

package/src/watch.js

@@ -266,14 +266,14 @@ function makeSyntheticSource(realId, batchesByFile) {
  * `verify` is always forced off here: seeding a dedup cache must never be
  * the reason a live vendor API gets hit.
  */
-async function baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, includeNoisy, includeSuppressed, noColor) {
+async function baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, includeNoisy, includeSuppressed, noColor, includePii) {
   const batch = await readWholeFile(source, file, sizeBytes, mtimeMs);
   if (!batch) return;
   let result;
   try {
     result = await scan({
       sources: [makeSyntheticSource(sourceId, new Map([[file, batch]]))],
-      includeNoisy, includeSuppressed, verify: false, noColor,
+      includeNoisy, includeSuppressed, verify: false, noColor, includePii,
     });
   } catch {
     return; // best-effort: a failure here just leaves this file's dedup
@@ -299,7 +299,7 @@ async function baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, in
  * `dismiss` takes effect without a restart.
  */
 async function sweepOnce({ sources, tracked, seen, ledger, options, emit }) {
-  const { includeNoisy, includeSuppressed, verify, noColor } = options || {};
+  const { includeNoisy, includeSuppressed, verify, noColor, includePii } = options || {};
   let loud = 0;
   let quiet = 0;
   let suppressedByLedger = 0;
@@ -363,7 +363,7 @@ async function sweepOnce({ sources, tracked, seen, ledger, options, emit }) {
           contentHash: tailable ? null : wholeFileHash(file),
         });
         if (!tailable) {
-          await baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, includeNoisy, includeSuppressed, noColor);
+          await baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, includeNoisy, includeSuppressed, noColor, includePii);
         }
         continue;
       }
@@ -432,7 +432,7 @@ async function sweepOnce({ sources, tracked, seen, ledger, options, emit }) {
     try {
       result = await scan({
         sources: [makeSyntheticSource(sourceId, batchesByFile)],
-        includeNoisy, includeSuppressed, verify, noColor,
+        includeNoisy, includeSuppressed, verify, noColor, includePii,
       });
     } catch (err) {
       emit({ type: "watch-error", at: new Date(), source: sourceId, detail: "scan failed: " + (err && err.message) });