residoo 0.2.0 → 0.3.0

package/README.md

@@ -103,6 +103,14 @@ won't be built into the tool that writes it.
   files), and checks the places the 2026 supply-chain campaigns planted
   persistence: hooks, dropper scripts, auto-run tasks, invisible Unicode.
   See the next section.
+- Attaches a **rotation runbook** to every finding: the vendor's real
+  revocation path, verified against their own docs, plus a local
+  acknowledgement ledger so "found it" can become "closed it". See
+  [Rotation](#rotation-from-found-to-closed).
+- Scans a **repository checkout** instead of the machine with
+  `--project <dir>`: committed transcripts, agent configs, and root `.env`
+  files, built for CI and pre-commit. See
+  [CI and pre-commit](#ci-and-pre-commit).
 
 ## Beyond transcripts: configs and planted persistence
 
@@ -159,6 +167,7 @@ counted as clean.
   │                                                               │
   │   42 transcript sources           agent config files          │
   │   ~/.claude, Cursor, Codex…       settings · MCP · memory     │
+  │   (--project <dir>: a repo checkout instead of the machine)   │
   │            │                              │                   │
   │            ├──────────────┬───────────────┤                   │
   │            ▼              │               ▼                   │
@@ -168,6 +177,9 @@ counted as clean.
   │            ▼              ▼               │                   │
   │        redacted report (first/last 4 chars only) ◀────────────┤
   │            │                                                  │
+  │            ├─▶ rotation hints per finding · explain / ack     │
+  │            │   ledger: ~/.residoo/rotations.json              │
+  │            │                                                  │
   │            ▼  --seal (only if you ask)                        │
   │        AES-256-GCM vault · scrypt key · encrypted manifest    │
   │            │                              │                   │
@@ -179,7 +191,9 @@ counted as clean.
 
 The `--seal` and `--upload-cloudroam` legs never run unless you pass their
 flag. Everything above the vault happens on every scan; nothing in the
-diagram ever modifies or deletes an existing file.
+diagram ever modifies or deletes an existing file. The one exception, stated
+in the open: `residoo ack` writes residoo's own rotation ledger at
+`~/.residoo/rotations.json` (atomic, redacted, never a user file).
 
 ## Sealing what it finds
 
@@ -207,6 +221,76 @@ touches the network, it never runs unless you pass the flag, and only
 ciphertext is transmitted.** The vault is sealed before upload code ever
 executes.
 
+## Rotation: from found to closed
+
+Detection without rotation is theater, and the field's own numbers say so:
+64% of secrets leaked publicly in 2022 were still valid years later, 88% of
+re-verified leaked AWS keys still authenticated, and the median time to
+remediate a GitHub-leaked secret is 94 days. A scanner that stops at "found
+it" leaves all of that untouched. So every finding in a residoo report comes
+with the way out:
+
+- **A rotation hint per finding**, from a per-rule guidance map covering all
+  35 detection rules (plus the opt-in noisy ones). Where a rotation URL is
+  shown, that exact URL was fetched and confirmed to document rotating or
+  revoking that credential type; where a vendor's docs are login-walled or
+  unfetchable, the report gives the console path in words instead of a link
+  it could not verify. Generic shapes (a JWT, a bearer header) get honest
+  generic guidance that says how to identify the issuer, never a pretend
+  vendor.
+- **`residoo explain <rule-id>`** prints the full runbook for one credential
+  type: where to revoke, the steps, and what revocation actually does at
+  that vendor. `residoo explain --list` shows the whole catalogue.
+- **`residoo ack <fingerprint>`** records that you rotated one finding.
+  Every finding carries a stable fingerprint (derived only from
+  already-redacted material, so the ledger can never leak), shown in the
+  report and in `--json`. Acknowledged findings are reported as such on the
+  next scan instead of re-alarming forever. The ledger lives at
+  `~/.residoo/rotations.json`: residoo's own file, written atomically, ack
+  notes redacted through the same pipeline as previews.
+- **Order matters, and the report says so when it does.** The ChainDrop
+  campaign (Aug 2026) shipped a token monitor that fires an attacker payload
+  the moment the stolen GitHub token is revoked. When one scan finds both
+  integrity warnings and leaked credentials, the report tells you to remove
+  the planted persistence first and rotate second, because "rotate
+  everything now" advice can itself trigger the damage.
+
+Acks change what the report says, never what CI does: `--fail-on-find`
+fails on every finding, acknowledged or not, unless you explicitly pass
+`--allow-acked` (integrity warnings always fail either way).
+
+## CI and pre-commit
+
+`residoo scan --project <dir>` scans a repository checkout instead of the
+machine it runs on: committed agent transcripts (Claude Code `.jsonl`
+trees, Codex `rollout-*.jsonl`, SpecStory histories), agent config and
+rules files at any depth, and root-level `.env` files, plus the integrity
+checks anchored at that directory. It deliberately does not touch the
+machine's home-level sources, so a clean CI run means the checkout is
+clean and claims nothing about anyone's laptop.
+
+As a GitHub Action (this repository doubles as a composite action):
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: dandovdub/residoo@v0.3.0
+```
+
+As a pre-commit hook:
+
+```yaml
+repos:
+  - repo: https://github.com/dandovdub/residoo
+    rev: v0.3.0
+    hooks:
+      - id: residoo
+```
+
+Or with no integration at all: `npx --yes residoo scan --project . --fail-on-find`.
+Exit codes, inputs, and exactly what project mode does and does not see are
+documented in [docs/ci.md](docs/ci.md).
+
 ## What it does not do
 
 - **No network calls in the default path, and none at all unless you
@@ -232,6 +316,20 @@ npm install -g residoo
 residoo scan
 ```
 
+A Homebrew formula ships in this repo at `packaging/homebrew/`. It installs
+the exact tarball published to npm (same bits, sha256 verified), so Homebrew
+is a second door to the same release, not a second build. Once the tap
+repository (`dandovdub/homebrew-residoo`) is published, installation is:
+
+```bash
+brew tap dandovdub/residoo
+brew install residoo
+```
+
+Until the tap is up, npm above is the way in. The formula always points at
+the latest *published* npm release (its sha256 is computed from the real
+tarball), so it can lag a fresh tag by one publish cycle.
+
 Requires Node.js 18+. The SQLite-backed sources listed below additionally
 need 22.5+; residoo still runs and scans every line-delimited/JSON source,
 including Claude Code, fine without it. Zero runtime dependencies, and you
@@ -243,10 +341,14 @@ can check `package.json` rather than take that on faith.
 residoo scan [options]
 
   --json                  machine-readable output (full detail, still redacted)
+  --project [dir]         scan a repository checkout instead of this machine
+                          (committed transcripts, agent configs, root .env)
   --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): secret
                           findings and integrity warnings count, review items don't
+  --allow-acked           with --fail-on-find: acknowledged findings no longer
+                          fail the run (pending ones and warnings still do)
   --no-integrity          skip the integrity checks
   --no-color              disable ANSI colour
 
@@ -255,6 +357,10 @@ residoo scan [options]
   --upload-cloudroam      also upload the sealed vault (needs CLOUDROAM_API_KEY,
                           --connector <id>, --bucket <name>; ciphertext only)
 
+residoo explain <rule-id>                           full rotation runbook for one rule
+residoo explain --list                              every rule id and label
+residoo ack <fingerprint> [--note <text>]           mark one finding rotated
+
 residoo unseal <vault-dir>                          list a vault's contents
 residoo unseal <vault-dir> --restore <n> --out <p>  restore one file, hash-verified
 ```
@@ -266,7 +372,10 @@ so pick one you keep.
 ## Sources supported today
 
 43 sources as of this writing (42 transcript stores plus the agent-config
-source described above), in two honestly-distinct tiers. See
+source described above), in two honestly-distinct tiers. Project mode
+(`--project`) adds one more, opt-in source (`src/sources/project-artifacts.js`)
+that scans a repository checkout rather than the machine and never
+participates in a default scan. See
 `src/sources/index.js` for the full list and grouping, and each source file's
 own header for exactly what was and wasn't checked.
 

package/package.json

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

@@ -5,6 +5,9 @@ const { availableSources, ALL_SOURCES } = require("./sources");
 const { scan, emptyResult } = require("./scan");
 const { render, renderIntegrity, renderJson } = require("./report");
 const { checkIntegrity } = require("./integrity");
+const {
+  ROTATION_GUIDANCE, guidanceFor, loadAcks, ackFinding, renderRotation,
+} = require("./rotation");
 
 /**
  * A source is unavailable for the ordinary reason (not installed — nothing
@@ -39,25 +42,61 @@ const HELP = `residoo: find secrets leaking through your AI agent's session hist
   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.
 
 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): 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,
@@ -186,6 +225,78 @@ async function runUnseal(args) {
   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) {
@@ -195,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;
@@ -204,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
@@ -226,8 +349,26 @@ async function main(argv) {
   // 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 { return checkIntegrity(); }
+    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 {
@@ -241,7 +382,23 @@ async function main(argv) {
     }
   };
 
-  const sources = availableSources();
+  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;
@@ -249,7 +406,7 @@ async function main(argv) {
       // 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, integrity) + "\n");
+      process.stdout.write(renderJson(empty, integrity, renderRotation([], acks)) + "\n");
     } else {
       process.stderr.write(
         "No known transcript sources found on this machine.\n" +
@@ -264,14 +421,23 @@ async function main(argv) {
 
   const result = await scan({ sources, includeNoisy, includeSuppressed });
   const integrity = wantsIntegrity ? runIntegrity() : null;
-  process.stdout.write((wantsJson ? renderJson(result, integrity) : render(result, { noColor, integrity })) + "\n");
+  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 || integrityWarnCount(integrity) > 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 };