residoo 0.17.0 → 0.18.0

package/README.md

@@ -72,14 +72,24 @@ observed, not just documented. All 8, not just the closest one:
 | tool | distinct credentials found | precision | egress during the scan |
 |---|---|---|---|
 | **residoo** | **45/45 (100%)** | **100%** | **none-observed** |
-| agentsweep | 33/42 (79%) | 100% | none-observed |
+| agentsweep | 33/42 (79%) | 89% | none-observed |
 | gitleaks | 32/45 (71%) | 100% | none-observed |
-| betterleaks | 32/45 (71%) | 100% | none-observed |
+| betterleaks | 32/45 (71%) | 95% | none-observed |
 | whatileaked | 28/42 (67%) | 100% | none-observed |
-| kingfisher | 29/45 (64%) | 100% | attempts calls in default mode |
+| kingfisher | 29/45 (64%) | 97% | attempts calls in default mode |
 | trufflehog | 29/45 (64%) | 97% | attempts calls in default mode |
 | detect-secrets | 25/45 (56%) | 2% | attempts calls in default mode |
 
+Precision here counts a flagged vendor-documented example key (a real,
+deliberate suppress-placeholder in the corpus) as a false positive, the
+stricter of the two measures `bench/RESULTS.md` reports throughout —
+several tools above score better on the looser "excluding suppress flags"
+measure (e.g. agentsweep and betterleaks both reach 100% there), but this
+is the one that matches what a user actually experiences: a tool that
+flags AWS's own published example key on every run trains people to
+ignore its output. residoo and gitleaks are the only two tools that hit
+100% either way.
+
 "none-observed" is a measured result, not a default assumption: every run
 sits under a live proxy trap and process-tree polling, and a deliberate
 canary connection is fired and confirmed caught *before* each real

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.17.0",
+  "version": "0.18.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

@@ -2,6 +2,7 @@
 
 const path = require("path");
 const fs = require("fs");
+const os = require("os");
 const crypto = require("crypto");
 const { availableSources, ALL_SOURCES } = require("./sources");
 const { scan, emptyResult } = require("./scan");
@@ -13,7 +14,7 @@ const {
 const { startWatch, isTailable } = require("./watch");
 const { startMcpServer } = require("./mcp");
 const { buildTools } = require("./mcpTools");
-const { runGuard: runGuardEngine } = require("./guard");
+const { runGuard: runGuardEngine, buildHookConfig } = require("./guard");
 
 /**
  * A source is unavailable for the ordinary reason (not installed — nothing
@@ -183,6 +184,15 @@ Watch:
                           never to one already seen
   --include-noisy, --include-suppressed, --include-pii, --no-color
                           same meaning as scan
+  --no-notify             skip the OS desktop notification watch fires for
+                          each genuinely new finding (macOS via osascript,
+                          Linux via notify-send if installed; no built-in
+                          mechanism on Windows -- disclosed, not attempted).
+                          On by default in human-readable mode: watch's own
+                          purpose is alerting you, and a background process
+                          nobody is watching a terminal for needs more than
+                          a printed line. Never fires for a re-exposure of
+                          something already seen, and never in --json mode.
   Ctrl+C stops cleanly and prints a session summary (skipped with --json,
   where the same information is one final NDJSON event).
 
@@ -292,6 +302,19 @@ Guard:
                                 "hooks":[{"type":"command",
                                 "command":"residoo guard"}]}]}}
 
+  residoo guard --print-config
+                          print that same merged JSON to stdout instead of
+                          hand-writing it -- reads your existing
+                          ~/.claude/settings.json if present, adds
+                          whatever residoo guard hooks are missing (never
+                          duplicates one already there), and prints the
+                          result. Writes NOTHING to disk: residoo never
+                          writes any file but its own rotation ledger and
+                          an explicit --seal vault, so save it yourself:
+                            residoo guard --print-config > ~/.claude/settings.json
+                          --project targets ./.claude/settings.json (the
+                          repo-local config) instead of the home-level one.
+
 Rotation:
   residoo explain <rule-id>     full rotation runbook for one detection rule
                                 (where to revoke, steps, what revocation does)
@@ -688,6 +711,7 @@ async function runWatch(args) {
   const verify = args.includes("--verify");
   const noColor = args.includes("--no-color");
   const includePii = args.includes("--include-pii");
+  const noNotify = args.includes("--no-notify");
 
   let intervalSeconds = 5;
   const intervalArg = argValue(args, "--interval");
@@ -713,7 +737,7 @@ async function runWatch(args) {
 
   const { promise, stop } = startWatch({
     sources,
-    options: { includeNoisy, includeSuppressed, verify, noColor, includePii, json: wantsJson, pollMs: intervalSeconds * 1000 },
+    options: { includeNoisy, includeSuppressed, verify, noColor, includePii, noNotify, json: wantsJson, pollMs: intervalSeconds * 1000 },
   });
 
   const printFinalSummary = (stats) => {
@@ -743,6 +767,57 @@ async function runWatch(args) {
   return 0;
 }
 
+/**
+ * `residoo guard --print-config`: print the merged .claude/settings.json
+ * a user would need to register all three guard hooks, without ever
+ * writing it -- see guard.js's own buildHookConfig docstring for why this
+ * is print-only rather than an auto-installer. Reads the existing file
+ * (home-level by default, `--project` for the repo-local one) if present,
+ * merges in whatever hook groups are missing, and writes the result to
+ * STDOUT ONLY -- every instructional line goes to stderr, so
+ * `residoo guard --print-config > ~/.claude/settings.json` redirects
+ * exactly the JSON and nothing else.
+ */
+function runGuardPrintConfig(args) {
+  const wantsProject = args.includes("--project");
+  const targetPath = wantsProject
+    ? path.join(process.cwd(), ".claude", "settings.json")
+    : path.join(os.homedir(), ".claude", "settings.json");
+
+  let existing = {};
+  let existedAlready = false;
+  try {
+    const raw = fs.readFileSync(targetPath, "utf-8");
+    existedAlready = true;
+    try { existing = JSON.parse(raw); }
+    catch {
+      process.stderr.write(
+        `residoo guard --print-config: ${targetPath} exists but is not valid JSON. ` +
+        `Fix it first -- printing a merge against unparseable JSON would risk losing whatever is already there.\n`
+      );
+      return 1;
+    }
+  } catch (err) {
+    if (!(err && err.code === "ENOENT")) {
+      process.stderr.write(`residoo guard --print-config: could not read ${targetPath}: ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  const merged = buildHookConfig(existing);
+  process.stderr.write(
+    (existedAlready
+      ? `residoo guard --print-config: merged residoo's three hooks into your existing ${targetPath} below.\n`
+      : `residoo guard --print-config: ${targetPath} doesn't exist yet -- here's a new one with residoo's three hooks.\n`) +
+    `Nothing was written to disk -- residoo never writes any file but its own rotation ledger and an explicit ` +
+    `--seal vault. Save this yourself, e.g.:\n` +
+    `  residoo guard --print-config${wantsProject ? " --project" : ""} > ${targetPath}\n` +
+    (wantsProject ? "" : "(add --project to target ./.claude/settings.json instead of the home-level one)\n")
+  );
+  process.stdout.write(JSON.stringify(merged, null, 2) + "\n");
+  return 0;
+}
+
 /**
  * `residoo mcp`: run residoo as an MCP server over stdio. See src/mcp.js
  * for the protocol engine and src/mcpTools.js for the tool catalog; this
@@ -925,7 +1000,10 @@ async function main(argv) {
   if (cmd === "watch") return runWatch(args);
   if (cmd === "mcp") return runMcp(args);
   if (cmd === "cred") return runCred(args);
-  if (cmd === "guard") return runGuardEngine();
+  if (cmd === "guard") {
+    if (args.includes("--print-config")) return runGuardPrintConfig(args.slice(1));
+    return runGuardEngine();
+  }
   if (cmd !== "scan") {
     process.stderr.write(`Unknown command "${cmd}". Try "residoo --help".\n`);
     return 2;

package/src/guard.js

@@ -70,6 +70,56 @@
 const { PATTERNS, redact } = require("./patterns");
 const { VENDOR_EXAMPLE_VALUES, zeroEntropyTail } = require("./scan");
 
+const GUARD_COMMAND = "residoo guard";
+
+// matcher: null means Claude Code's own hook-config schema omits the field
+// entirely for an event with no matcher support (UserPromptSubmit) --
+// distinct from an empty string, which would mean "match everything" for
+// an event that DOES support matchers.
+const HOOK_EVENT_SPECS = [
+  { event: "PreToolUse", matcher: "Bash|Read" },
+  { event: "UserPromptSubmit", matcher: null },
+  { event: "PostToolUse", matcher: "Bash" },
+];
+
+/**
+ * Pure function: given a parsed Claude Code settings.json object (or `{}`
+ * for a fresh one), returns a NEW object with a "residoo guard" hook group
+ * appended to each of PreToolUse/UserPromptSubmit/PostToolUse's hook
+ * arrays -- unless a "residoo guard" command already exists ANYWHERE in
+ * that event's groups, in which case that event is left untouched
+ * (idempotent: running this against its own prior output changes
+ * nothing). Never mutates `existing`; every other key, every other tool's
+ * hook, every unrelated setting is carried through byte-for-byte.
+ *
+ * This function only COMPUTES a value -- it never touches a file, on
+ * purpose. CONTRIBUTING.md's own hard rule (rule 3) names
+ * `~/.residoo/rotations.json` as "the only file residoo ever writes
+ * outside an explicit --seal ... nothing else may claim this carve-out."
+ * An auto-installing `guard --install` that edited `.claude/settings.json`
+ * directly would violate that rule outright, so the CLI wraps this in
+ * `--print-config` instead (see cli.js's runGuardPrintConfig): print the
+ * merged JSON to stdout, let the human decide whether and where to save it.
+ */
+function buildHookConfig(existing) {
+  const settings = existing && typeof existing === "object" && !Array.isArray(existing)
+    ? JSON.parse(JSON.stringify(existing)) : {};
+  if (!settings.hooks || typeof settings.hooks !== "object" || Array.isArray(settings.hooks)) settings.hooks = {};
+
+  for (const { event, matcher } of HOOK_EVENT_SPECS) {
+    const groups = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    const alreadyPresent = groups.some((g) =>
+      g && typeof g === "object" && Array.isArray(g.hooks) &&
+      g.hooks.some((h) => h && typeof h === "object" && h.type === "command" && h.command === GUARD_COMMAND));
+    if (alreadyPresent) { settings.hooks[event] = groups; continue; }
+    const newGroup = matcher
+      ? { matcher, hooks: [{ type: "command", command: GUARD_COMMAND }] }
+      : { hooks: [{ type: "command", command: GUARD_COMMAND }] };
+    settings.hooks[event] = [...groups, newGroup];
+  }
+  return settings;
+}
+
 // A matched path fragment must be preceded by a path separator or the start
 // of the string, and followed by either the end of the string (the common
 // case for Read's file_path) or a shell metacharacter/whitespace (the case
@@ -402,5 +452,5 @@ async function runGuard({ input = process.stdin, output = process.stdout, errOut
 
 module.exports = {
   evaluateToolInput, matchSensitivePath, evaluatePromptText, evaluatePostToolUse,
-  runGuard, SENSITIVE_PATH_PATTERNS,
+  runGuard, buildHookConfig, SENSITIVE_PATH_PATTERNS,
 };

package/src/notify.js

@@ -0,0 +1,53 @@
+"use strict";
+
+const cp = require("child_process");
+
+/**
+ * Best-effort OS desktop notification for `residoo watch`. macOS via
+ * `osascript` (always present, no new dependency -- the same shell-out
+ * precedent `keychain.js`'s `security` and `ocr.js`'s `tesseract` already
+ * set), Linux via `notify-send` (commonly present on a desktop session,
+ * NOT guaranteed -- `watch` also runs on headless/server machines with no
+ * notification daemon at all).
+ *
+ * Windows: no built-in, dependency-free mechanism was found that doesn't
+ * either need an external module (BurntToast) or pop a blocking, modal
+ * MessageBox in front of a background process -- a disclosed scope limit,
+ * not silently assumed covered, the same posture `keychain.js` already
+ * takes for its own Windows refusal.
+ *
+ * Decoration, never the report itself: `watch`'s own `emit()` already
+ * writes every finding to stdout/stderr before this is ever called, so a
+ * missing binary, no display server, or a spawn error here must never
+ * throw, block, or affect the caller in any way -- it can only make an
+ * already-reported finding easier to notice sooner.
+ *
+ * `cp.spawn` (not destructured at module load) so a test can monkey-patch
+ * `require("child_process").spawn` directly and restore it after, without
+ * this module needing its own injectable-dependency parameter.
+ */
+function notifyDesktop(title, message) {
+  try {
+    if (process.platform === "darwin") {
+      // osascript's -e takes one AppleScript source string; spawn (no
+      // shell:true) passes it as a single argv entry, so there is no shell
+      // to inject into -- but the string still has to be valid AppleScript
+      // source, so its own quote/backslash characters need escaping or a
+      // stray one just breaks the script into a harmless no-op.
+      const esc = (s) => String(s).replace(/[\\"]/g, "\\$&");
+      const script = `display notification "${esc(message)}" with title "${esc(title)}"`;
+      const child = cp.spawn("osascript", ["-e", script], { stdio: "ignore" });
+      child.on("error", () => {}); // binary missing or spawn failed: never throw
+      child.unref();
+    } else if (process.platform === "linux") {
+      const child = cp.spawn("notify-send", [String(title), String(message)], { stdio: "ignore" });
+      child.on("error", () => {});
+      child.unref();
+    }
+    // Windows and anything else: no-op, disclosed above, not attempted.
+  } catch {
+    // Never let a notification failure affect the caller.
+  }
+}
+
+module.exports = { notifyDesktop };

package/src/watch.js

@@ -6,6 +6,7 @@ const crypto = require("crypto");
 const { scan } = require("./scan");
 const { guidanceFor, fingerprintFinding, loadAcks, loadDismissed, statePath } = require("./rotation");
 const { c, makePaint } = require("./color");
+const { notifyDesktop } = require("./notify");
 
 /**
  * `residoo watch`: continuous, near-real-time scanning of the same
@@ -563,7 +564,7 @@ function reloadLedgerIfChanged(prev) {
  * backstop and nothing riding on top of it. `options.fsWatch` is accepted
  * and ignored, reserved for when a future version adds real hints.
  */
-function startWatch({ sources, options = {}, out = process.stdout, errOut = process.stderr } = {}) {
+function startWatch({ sources, options = {}, out = process.stdout, errOut = process.stderr, notify = notifyDesktop } = {}) {
   const paint = makePaint(options.noColor, out);
   const tracked = new Map();
   const seen = new Map();
@@ -582,6 +583,17 @@ function startWatch({ sources, options = {}, out = process.stdout, errOut = proc
     }
     const line = renderHumanLine(event, paint);
     if (line !== null) out.write(line + "\n");
+    // Desktop notification is decoration on top of the line just written
+    // above, never a substitute for it -- JSON mode is for programmatic
+    // consumption (a pipe, a log shipper), not a human sitting in front of
+    // the terminal, so it's excluded the same way `options.noColor` only
+    // applies to the human-line path. Only a genuinely NEW finding notifies
+    // -- a `reexposure` (the same secret seen again) or a `watch-error`
+    // would otherwise turn a quiet, healthy watch into a notification
+    // spamming machine.
+    if (event.type === "finding" && !options.json && !options.noNotify) {
+      notify("residoo: new secret found", `${event.label} in ${event.relFile}:${event.line} (${event.preview})`);
+    }
   }
 
   async function tick() {