residoo 0.1.0 → 0.3.0

package/src/cli.js

@@ -3,30 +3,100 @@
 const path = require("path");
 const { availableSources, ALL_SOURCES } = require("./sources");
 const { scan, emptyResult } = require("./scan");
-const { render, renderJson } = require("./report");
+const { render, renderIntegrity, renderJson } = require("./report");
+const { checkIntegrity } = require("./integrity");
+const {
+  ROTATION_GUIDANCE, guidanceFor, loadAcks, ackFinding, renderRotation,
+} = require("./rotation");
 
-const HELP = `residoo — find secrets leaking through your AI agent's session history
+/**
+ * A source is unavailable for the ordinary reason (not installed — nothing
+ * more to say) far more often than for a reason worth surfacing. A handful
+ * of sources — the SQLite-backed ones gated on the built-in `node:sqlite`
+ * module (cursor.js, crush.js, cody.js, devin-cli.js, hermes.js, kiro-cli.js,
+ * llm.js, trae.js, void.js, warp.js, zed.js) — export the optional
+ * `unavailableReason()` for the one case worth calling out: the tool IS
+ * installed but this Node runtime is too old to read its database. Every
+ * other source can safely omit this export entirely; this stays a no-op for
+ * those rather than requiring every adapter to implement it.
+ */
+function sourceStatusLabel(source) {
+  const reason = typeof source.unavailableReason === "function" ? source.unavailableReason() : null;
+  return reason ? `${source.label()} (${reason})` : source.label();
+}
+function sourceStatusList() {
+  return ALL_SOURCES.map(sourceStatusLabel).join(", ");
+}
+
+const HELP = `residoo: find secrets leaking through your AI agent's session history
 
   Coding agents (Claude Code, Cursor, Copilot, ...) write everything you do
-  to a local transcript, including file contents your prompts touch — which
+  to a local transcript, including file contents your prompts touch. That
   means real credentials sitting in plaintext on disk, indefinitely, in a
   place nobody thinks to check. residoo scans those transcripts for them.
 
+  A scan also runs integrity checks over agent config locations, the 2026
+  supply-chain campaigns planted persistence exactly there: SessionStart
+  hooks, dropper scripts, folder-open tasks, zero-width Unicode instructions
+  hidden in memory/rules files. Every auto-executing hook found in the
+  checked locations is listed for your review; only published campaign IOCs
+  and campaign-shaped behaviors escalate to warnings.
+
+  Every finding comes with a rotation hint: the vendor's real revocation
+  path, verified against their docs, because a leaked key that is found but
+  never rotated is still leaked (64% of leaked secrets stay valid for years).
+  "residoo explain <rule-id>" prints the full runbook for one credential
+  type; "residoo ack <fingerprint>" records that you rotated one, in
+  ~/.residoo/rotations.json, the only file residoo ever writes outside an
+  explicit --seal.
+
   Scanning makes NO network calls and changes nothing on disk. Findings are
   redacted in every output format. Sealing (--seal) writes NEW encrypted
-  files only — it never modifies or deletes anything that already exists.
+  files only. It never modifies or deletes anything that already exists.
 
 Usage:
   residoo scan [options]
+  residoo explain <rule-id>   (or: residoo explain --list)
+  residoo ack <fingerprint> [--note <text>]
   residoo unseal <vault-dir> [--restore <n> --out <path>]
 
 Scan options:
   --json                  machine-readable output (full detail, still redacted)
+  --project [dir]         scan a repository checkout instead of this machine
+                          (default dir: current directory). Covers committed
+                          agent transcripts, agent config/rules files, and
+                          root-level .env files inside the checkout, plus
+                          integrity checks anchored at that directory. The
+                          home-level transcript and config sources are NOT
+                          scanned in this mode, deliberately: in CI they
+                          would scan the runner's home and say nothing about
+                          the repo, and a clean project scan must never be
+                          mistaken for a clean machine. Run residoo scan
+                          without --project for the machine itself.
   --include-noisy         also run broad, false-positive-prone rules
   --include-suppressed    also show matches that looked like placeholder/example text
-  --fail-on-find          exit code 1 if anything is found (for CI)
+  --fail-on-find          exit code 1 if anything is found (for CI): secret
+                          findings and integrity WARNINGS count; integrity
+                          info-level review items do not
+  --allow-acked           with --fail-on-find: findings whose fingerprint was
+                          acknowledged via "residoo ack" no longer fail the
+                          run; pending findings and integrity warnings still
+                          do. Without this flag, --fail-on-find fails on
+                          every finding, acknowledged or not.
+  --no-integrity          skip the integrity checks (planted hooks, dropper
+                          files, auto-run tasks, hidden Unicode)
   --no-color              disable ANSI colour
 
+Rotation:
+  residoo explain <rule-id>   full rotation runbook for one detection rule
+                              (where to revoke, steps, what revocation does)
+  residoo explain --list      every rule id with its credential label
+  residoo ack <fingerprint>   mark one finding's rotation done; fingerprints
+                              appear next to findings in the report and in
+                              --json. Optional --note <text> is stored with
+                              the acknowledgement (redacted if it matches a
+                              secret pattern).
+
 Seal options (used with scan):
   --seal                  after scanning, encrypt every transcript that carried a
                           finding into a local vault directory (AES-256-GCM,
@@ -49,7 +119,7 @@ Unseal:
 
 The passphrase is read from RESIDOO_PASSPHRASE, or prompted (hidden) on a TTY.
 
-Sources checked on this machine: ${ALL_SOURCES.map((s) => s.label()).join(", ")}
+Sources checked on this machine: ${sourceStatusList()}
 `;
 
 function argValue(args, flag) {
@@ -73,7 +143,7 @@ async function runSeal(result, args) {
 
   const filesWithFindings = [...new Set(result.findings.map((f) => f.file))];
   if (filesWithFindings.length === 0) {
-    process.stdout.write("Nothing to seal — no findings.\n");
+    process.stdout.write("Nothing to seal: no findings.\n");
     return 0;
   }
 
@@ -93,7 +163,7 @@ async function runSeal(result, args) {
     `${(totalSealed / 1024 / 1024).toFixed(1)}MB encrypted.\n` +
     `Originals were NOT touched. Once you've verified a restore works\n` +
     `(residoo unseal ${path.basename(vaultDir)} --restore 0001.sealed --out /tmp/check), removing the\n` +
-    `plaintext originals is your call — residoo never deletes anything itself.\n`
+    `plaintext originals is your call; residoo never deletes anything itself.\n`
   );
 
   if (args.includes("--upload-cloudroam")) {
@@ -104,7 +174,7 @@ async function runSeal(result, args) {
       process.stderr.write("--upload-cloudroam needs CLOUDROAM_API_KEY (env), --connector and --bucket.\n");
       return 2;
     }
-    process.stdout.write(`\nUploading sealed vault to CloudRoam (${bucket}) — ciphertext only:\n`);
+    process.stdout.write(`\nUploading sealed vault to CloudRoam (${bucket}), ciphertext only:\n`);
     const uploaded = await uploadVaultToCloudRoam({
       vaultDir,
       baseUrl: process.env.CLOUDROAM_BASE_URL || "https://cloudroam.io",
@@ -127,7 +197,7 @@ async function runUnseal(args) {
   try {
     manifest = openManifest(vaultDir, passphrase);
   } catch {
-    process.stderr.write("Could not open vault — wrong passphrase, or the vault is corrupted.\n");
+    process.stderr.write("Could not open vault: wrong passphrase, or the vault is corrupted.\n");
     return 1;
   }
 
@@ -151,10 +221,82 @@ async function runUnseal(args) {
       `verified byte-identical to the original (SHA-256 match).\n`);
     return 0;
   }
-  process.stderr.write(`Restored, but verification FAILED — content does not match what was sealed. Do not trust this copy.\n`);
+  process.stderr.write(`Restored, but verification FAILED: content does not match what was sealed. Do not trust this copy.\n`);
   return 1;
 }
 
+/**
+ * Full rotation runbook for one rule id, or the whole catalogue via --list.
+ * Prints for a HUMAN about to revoke a credential, so it stays plain text
+ * and never assumes the finding is still on screen.
+ */
+function runExplain(args) {
+  const ids = Object.keys(ROTATION_GUIDANCE);
+  const ruleId = args[1] && !args[1].startsWith("--") ? args[1] : null;
+
+  if (args.includes("--list") || ruleId === null) {
+    process.stdout.write("Rotation runbooks available (residoo explain <rule-id>):\n");
+    const width = Math.max(...ids.map((i) => i.length)) + 2;
+    for (const id of ids) {
+      process.stdout.write(`  ${id.padEnd(width)}${ROTATION_GUIDANCE[id].label}\n`);
+    }
+    return 0;
+  }
+
+  const known = Object.prototype.hasOwnProperty.call(ROTATION_GUIDANCE, ruleId);
+  const g = guidanceFor(ruleId);
+  const out = [];
+  out.push(`${g.label} (rule: ${ruleId})`);
+  if (g.rotateUrl) out.push(`  rotate/revoke docs: ${g.rotateUrl}`);
+  if (g.consolePath) out.push(`  where: ${g.consolePath}`);
+  out.push("  steps:");
+  g.steps.forEach((s, i) => out.push(`    ${i + 1}. ${s}`));
+  out.push(`  note: ${g.revokeNote}`);
+  if (g.generic) {
+    out.push("  (generic guidance: this rule matches a shape, not a single vendor,");
+    out.push("   so the issuing service has to be identified from the finding's context)");
+  }
+  process.stdout.write(out.join("\n") + "\n");
+  if (!known) {
+    process.stderr.write(`residoo: "${ruleId}" is not a known rule id; the guidance above is the generic fallback. residoo explain --list shows every known id.\n`);
+    return 2;
+  }
+  return 0;
+}
+
+/**
+ * Record that one finding's credential was rotated. Takes the fingerprint
+ * exactly as the report and --json print it; acks change what the report
+ * SAYS (pending vs acknowledged) but never what --fail-on-find DOES unless
+ * --allow-acked is also passed to the scan, which keeps a CI gate honest by
+ * default.
+ */
+function runAck(args) {
+  const fp = args[1] && !args[1].startsWith("--") ? args[1] : null;
+  if (!fp) {
+    process.stderr.write("usage: residoo ack <fingerprint> [--note <text>]\n" +
+      "Fingerprints (rf1-...) are shown next to findings in the scan report and in --json.\n");
+    return 2;
+  }
+  let res;
+  try {
+    res = ackFinding(fp, argValue(args, "--note"));
+  } catch (err) {
+    process.stderr.write(`residoo: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 2;
+  }
+  process.stdout.write(
+    `Acknowledged ${res.fingerprint} at ${res.at}` +
+    (res.note ? ` with note: ${res.note}` : "") + "\n" +
+    "The next scan reports this finding as acknowledged. It still counts toward\n" +
+    "--fail-on-find unless the scan is run with --allow-acked.\n" +
+    "(ack is stateless: it cannot check this fingerprint against a scan, so a\n" +
+    "mistyped one is recorded too; the intended finding would then still show\n" +
+    "as pending on the next scan.)\n"
+  );
+  return 0;
+}
+
 async function main(argv) {
   const args = argv.slice(2);
   if (args.includes("-h") || args.includes("--help") || args.length === 0) {
@@ -164,6 +306,8 @@ async function main(argv) {
 
   const cmd = args[0];
   if (cmd === "unseal") return runUnseal(args);
+  if (cmd === "explain") return runExplain(args);
+  if (cmd === "ack") return runAck(args);
   if (cmd !== "scan") {
     process.stderr.write(`Unknown command "${cmd}". Try "residoo --help".\n`);
     return 2;
@@ -173,6 +317,16 @@ async function main(argv) {
   const includeNoisy = args.includes("--include-noisy");
   const includeSuppressed = args.includes("--include-suppressed");
   const failOnFind = args.includes("--fail-on-find");
+  const allowAcked = args.includes("--allow-acked");
+
+  // --project [dir]: the dir is optional (CI passes ".", a bare --project
+  // means the current directory). null means machine mode.
+  let projectRoot = null;
+  const projectIdx = args.indexOf("--project");
+  if (projectIdx >= 0) {
+    const next = args[projectIdx + 1];
+    projectRoot = path.resolve(next && !next.startsWith("--") ? next : ".");
+  }
   // Passed through explicitly to render() rather than mutating
   // process.env.NO_COLOR — main() is an exported function a host process can
   // legitimately call more than once (a wrapper CLI, a test runner), and a
@@ -180,32 +334,110 @@ async function main(argv) {
   // color for a later call that never asked for that.
   const noColor = args.includes("--no-color");
 
-  const sources = availableSources();
+  // Integrity runs by default: a scan that reports "no secrets leaked" while
+  // a planted SessionStart hook sits ready to re-leak them next session is
+  // an incomplete answer. Only warn-severity findings (verified campaign
+  // signatures, unverifiable configs) gate --fail-on-find — info items are
+  // the user's own hooks listed for review, and failing CI on those would
+  // train people to pass --no-integrity, which is worse than not checking.
+  const wantsIntegrity = !args.includes("--no-integrity");
+  const integrityWarnCount = (integ) =>
+    integ ? integ.findings.filter((f) => f.severity === "warn").length : 0;
+  // The integrity checker's inputs are, by its own threat model, attacker-
+  // plantable files — a hostile config must not be able to suppress the
+  // secrets report by crashing the checker after the scan already ran. A
+  // throw degrades to a warn-severity finding: the run stays alive, the
+  // failure stays loud (it still gates --fail-on-find), and it is never a
+  // silent all-clear.
+  // In project mode both anchors point at the project root: the transcript
+  // sources are already project-only, and letting the integrity pass read the
+  // invoking machine's home would fail a CI/pre-commit run on a developer's
+  // own home-level hooks — a verdict about the wrong thing. The root's own
+  // .claude/, .gemini/, .cursor/, .vscode/, CLAUDE.md and .cursorrules are
+  // exactly the committed plant sites the campaigns used.
+  const runIntegrity = () => {
+    try {
+      // projectMode additionally makes checkIntegrity ignore the machine's
+      // GEMINI_CLI_HOME override and suppress the home-anchored hook
+      // demotion — both are statements about this machine, and a committed
+      // repo config is not this user's standing config (see integrity.js).
+      const integ = checkIntegrity(projectRoot ? { home: projectRoot, cwd: projectRoot, projectMode: true } : {});
+      // checkIntegrity's stock scope note says "current working directory";
+      // in project mode that would misdescribe what was checked.
+      if (projectRoot) {
+        integ.scopeNote = "Integrity checks cover the --project directory only (paths shown relative to it); this machine's home-level agent configs were not examined on this run.";
+      }
+      return integ;
+    }
+    catch (e) {
+      const why = String((e && e.message) || e).replace(/[\x00-\x1f\x7f]/g, "").slice(0, 200);
+      return {
+        findings: [{
+          severity: "warn", kind: "integrity-crashed", file: "(integrity checker)",
+          detail: `integrity checks crashed (${why}). Config locations are UNVERIFIED, not clean; the secret-scan results are unaffected`,
+        }],
+        filesChecked: [],
+        scopeNote: "Integrity checks did not complete on this run.",
+      };
+    }
+  };
+
+  let sources;
+  if (projectRoot) {
+    const projectArtifacts = require("./sources/project-artifacts");
+    const src = projectArtifacts.withRoot(projectRoot);
+    if (!src.available()) {
+      process.stderr.write(`--project: "${projectRoot}" is not a readable directory.\n`);
+      return 2;
+    }
+    sources = [src];
+  } else {
+    sources = availableSources();
+  }
+
+  // loadAcks degrades to {} (loudly, on stderr) if the state file is corrupt,
+  // so a broken ack ledger can never block or distort a scan.
+  const acks = loadAcks();
+
   if (sources.length === 0) {
     const empty = emptyResult();
+    const integrity = wantsIntegrity ? runIntegrity() : null;
     if (wantsJson) {
       // A --json caller (CI, a script piping into jq) must always get valid JSON
       // on stdout, even on the "nothing to scan" path — a plain-text message on
       // stderr with exit 0 silently breaks that contract.
-      process.stdout.write(renderJson(empty) + "\n");
+      process.stdout.write(renderJson(empty, integrity, renderRotation([], acks)) + "\n");
     } else {
       process.stderr.write(
         "No known transcript sources found on this machine.\n" +
-        `Checked: ${ALL_SOURCES.map((s) => s.label()).join(", ")}.\n`
+        `Checked: ${sourceStatusList()}.\n`
       );
+      // The integrity checks are not gated on transcript sources existing —
+      // a planted repo-level hook in the CWD is exactly as dangerous here.
+      if (integrity) process.stdout.write(renderIntegrity(integrity, { noColor }) + "\n");
     }
-    return 0;
+    return failOnFind && integrityWarnCount(integrity) > 0 ? 1 : 0;
   }
 
   const result = await scan({ sources, includeNoisy, includeSuppressed });
-  process.stdout.write((wantsJson ? renderJson(result) : render(result, { noColor })) + "\n");
+  const integrity = wantsIntegrity ? runIntegrity() : null;
+  const rotation = renderRotation(result.findings, acks);
+  process.stdout.write((wantsJson
+    ? renderJson(result, integrity, rotation)
+    : render(result, { noColor, integrity, rotation })) + "\n");
 
   if (args.includes("--seal")) {
     const sealExit = await runSeal(result, args);
     if (sealExit !== 0) return sealExit;
   }
 
-  return failOnFind && result.findings.length > 0 ? 1 : 0;
+  // --allow-acked narrows the SECRET gate only: an acknowledged rotation says
+  // nothing about a planted hook, so integrity warnings always fail. Without
+  // the flag, acks change what the report says, never what CI does — a gate
+  // that silently honored local ack state would let one developer's ledger
+  // green-light everyone's pipeline.
+  const secretGate = allowAcked ? rotation.counts.pending > 0 : result.findings.length > 0;
+  return failOnFind && (secretGate || integrityWarnCount(integrity) > 0) ? 1 : 0;
 }
 
 module.exports = { main };