residoo 0.1.0 → 0.2.0

package/src/cli.js

@@ -3,18 +3,45 @@
 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 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.
+
   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]
@@ -24,7 +51,11 @@ Scan options:
   --json                  machine-readable output (full detail, still redacted)
   --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
+  --no-integrity          skip the integrity checks (planted hooks, dropper
+                          files, auto-run tasks, hidden Unicode)
   --no-color              disable ANSI colour
 
 Seal options (used with scan):
@@ -49,7 +80,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 +104,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 +124,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 +135,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 +158,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,7 +182,7 @@ 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;
 }
 
@@ -180,32 +211,67 @@ async function main(argv) {
   // color for a later call that never asked for that.
   const noColor = args.includes("--no-color");
 
+  // 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.
+  const runIntegrity = () => {
+    try { return checkIntegrity(); }
+    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.",
+      };
+    }
+  };
+
   const sources = availableSources();
   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) + "\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;
+  process.stdout.write((wantsJson ? renderJson(result, integrity) : render(result, { noColor, integrity })) + "\n");
 
   if (args.includes("--seal")) {
     const sealExit = await runSeal(result, args);
     if (sealExit !== 0) return sealExit;
   }
 
-  return failOnFind && result.findings.length > 0 ? 1 : 0;
+  return failOnFind && (result.findings.length > 0 || integrityWarnCount(integrity) > 0) ? 1 : 0;
 }
 
 module.exports = { main };