residoo 0.8.8 → 0.10.0

package/README.md

@@ -116,8 +116,16 @@ while losing rows, then fixed in public against the classes it was losing
 - Redacts everything in its own output, including `--json`: you get a
   shape and a first/last-4 preview, never the real value.
 - `--sarif` emits SARIF 2.1.0 for GitHub code scanning.
+- `--html [path]` writes a self-contained, filterable HTML report with a
+  rotation guide per finding — same redaction guarantee as every other
+  output, no external CSS/JS, nothing to open it needs the network.
 - `--seal --keychain` encrypts every transcript with a finding into a
   local vault. See [docs/architecture.md](docs/architecture.md#sealing-what-it-finds).
+- `--ocr` reads secrets out of a pasted or tool-returned screenshot, too —
+  a real, verified-unclaimed gap: nobody else in this space has shipped
+  this. Opt-in, needs `tesseract` installed, 100% local, best-effort (OCR
+  can misread a character and miss an exact-format match). See
+  [docs/architecture.md](docs/architecture.md#reading-secrets-out-of-pasted-screenshots).
 - Tells you how many **distinct** secrets it found versus how many times
   one got echoed back across tool calls, so the headline number reflects
   real exposure, not repetition.
@@ -186,6 +194,8 @@ faith.
 residoo scan [options]
 
   --json                  machine-readable output (full detail, still redacted)
+  --html [path]           also write a self-contained HTML report (default:
+                          residoo-report-<stamp>.html); combines with --json
   --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
@@ -198,6 +208,8 @@ residoo scan [options]
   --no-color              disable ANSI colour
   --verify                ask each credential's own vendor if it still authenticates
                           (real network call; see docs/architecture.md)
+  --ocr                   also OCR pasted/tool-returned images and scan the text
+                          (needs tesseract installed; no network call; best-effort)
 
   --seal                  encrypt every transcript with findings into a local vault
   --vault-dir <dir>       vault location (default ./residoo-vault-<stamp>)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.8.8",
+  "version": "0.10.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,7 +5,7 @@ const fs = require("fs");
 const crypto = require("crypto");
 const { availableSources, ALL_SOURCES } = require("./sources");
 const { scan, emptyResult } = require("./scan");
-const { render, renderIntegrity, renderJson, renderSarif, makeProgressReporter, printIntro } = require("./report");
+const { render, renderIntegrity, renderJson, renderSarif, renderHtml, makeProgressReporter, printIntro } = require("./report");
 const { checkIntegrity } = require("./integrity");
 const {
   ROTATION_GUIDANCE, guidanceFor, loadAcks, loadDismissed, ackFinding, dismissFinding, renderRotation,
@@ -78,6 +78,15 @@ Scan options:
                           GitHub code scanning's Security tab and inline PR
                           annotations. Use --json for the full picture
                           (findings + integrity + rotation) instead.
+  --html [path]           also write a self-contained HTML report (default:
+                          residoo-report-<timestamp>.html in the current
+                          directory) -- a filterable table with a rotation
+                          guide per finding, safe to screenshot or share:
+                          same redacted preview as every other output, no
+                          raw value in any code path, no external CSS/JS/
+                          fonts, no network access needed to open it.
+                          Independent of --json/--sarif; can combine with
+                          either.
   --project [dir]         scan a repository checkout instead of this machine
                           (default dir: current directory). Covers committed
                           agent transcripts, agent config/rules files, and
@@ -129,6 +138,18 @@ Scan options:
                           JWT's own signed exp claim is checked locally
                           with no network call at all, on by default, not
                           part of --verify.
+  --ocr                   also OCR every pasted or tool-returned image found
+                          in a transcript (a screenshot of a .env file or a
+                          cloud console, for example) and scan the extracted
+                          text the same way. Off by default: needs
+                          tesseract installed (e.g. brew install tesseract;
+                          residoo does not bundle it), and it is real CPU
+                          work per image. No network call -- OCR runs
+                          100% locally, same as everything else. OCR is
+                          lossy by nature: a real test found visually
+                          similar characters (0/O, Y/*) can be misread,
+                          which breaks an exact-format match, so this is
+                          best-effort additional coverage, not a guarantee.
 
 Watch:
   residoo watch            continuous scanning instead of one snapshot:
@@ -340,6 +361,23 @@ async function resolveUnsealSecret(args, vaultDir) {
   }
 }
 
+// --html [path]: writes the self-contained HTML report to disk (default
+// residoo-report-<timestamp>.html in the cwd, same naming convention as
+// --seal's default vault dir) and prints where it went. Independent of
+// which stdout format was chosen (text/--json/--sarif), same relationship
+// --seal already has to those — this is a side effect, not another
+// mutually-exclusive output mode.
+function writeHtmlReport(result, integrity, rotation, args) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  // Bare --html is valid (auto-named), so the next token is only taken as a
+  // path when it doesn't itself look like another flag — same guard --project
+  // uses for the same reason.
+  const next = argValue(args, "--html");
+  const out = next && !next.startsWith("--") ? path.resolve(next) : path.resolve(`residoo-report-${stamp}.html`);
+  fs.writeFileSync(out, renderHtml(result, integrity, rotation));
+  process.stdout.write(`HTML report written to ${out}\n`);
+}
+
 async function runSeal(result, args) {
   const { sealFindings, uploadVaultToCloudRoam } = require("./sealvault");
 
@@ -850,6 +888,13 @@ async function main(argv) {
   // API call; see verify.js). Off by default; every other flag here only
   // changes what is READ or how it is DISPLAYED.
   const verify = args.includes("--verify");
+  // --ocr: no network call (tesseract runs 100% locally), but it does shell
+  // out to a binary this project doesn't ship and do real per-image CPU
+  // work, unlike every other flag here — same "off by default, opt in for
+  // a reason" posture as --verify, different reason. See ocr.js for the
+  // exact confirmed image shape this looks for and its honest accuracy
+  // limitations.
+  const wantsOcr = args.includes("--ocr");
 
   // --project [dir]: the dir is optional (CI passes ".", a bare --project
   // means the current directory). null means machine mode.
@@ -955,12 +1000,13 @@ async function main(argv) {
       // a planted repo-level hook in the CWD is exactly as dangerous here.
       if (integrity) process.stdout.write(renderIntegrity(integrity, { noColor }) + "\n");
     }
+    if (args.includes("--html")) writeHtmlReport(empty, integrity, renderRotation([], acks, dismissed), args);
     return failOnFind && integrityWarnCount(integrity) > 0 ? 1 : 0;
   }
 
   const progress = makeProgressReporter(noColor);
   const result = await scan({
-    sources, includeNoisy, includeSuppressed, verify, noColor,
+    sources, includeNoisy, includeSuppressed, verify, noColor, ocr: wantsOcr,
     onProgress: progress.onProgress,
     // Clears the spinner's last frame before --verify's own stderr lines
     // print; without this the last spinner line sits uncleared on screen
@@ -971,6 +1017,13 @@ async function main(argv) {
     onBeforeVerify: progress.stop,
   });
   progress.stop();
+  // Always stderr, never gated on --json/--sarif: those formats' stdout
+  // contract is machine-readable output only, but a user who asked for
+  // --ocr and got silently zero image findings because tesseract isn't
+  // installed needs to know that, not infer it from an empty result.
+  if (result.ocrRequestedButMissing) {
+    process.stderr.write("--ocr was requested but tesseract is not installed or not on PATH; no images were scanned. Install it (e.g. \"brew install tesseract\") and rerun.\n");
+  }
   const integrity = wantsIntegrity ? runIntegrity() : null;
   const rotation = renderRotation(result.findings, acks, dismissed);
   process.stdout.write((wantsSarif
@@ -984,6 +1037,8 @@ async function main(argv) {
     if (sealExit !== 0) return sealExit;
   }
 
+  if (args.includes("--html")) writeHtmlReport(result, integrity, rotation, args);
+
   // --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

package/src/ocr.js

@@ -0,0 +1,172 @@
+"use strict";
+
+/**
+ * Opt-in OCR of pasted-screenshot images inside a transcript (--ocr).
+ *
+ * Everything else in residoo detects secrets in TEXT already sitting in a
+ * transcript line. This module covers a real, verified-unclaimed gap: a
+ * user pastes a screenshot of a .env file, a cloud console page, or a
+ * terminal into their AI agent, and the credential in that image is
+ * invisible to every text-based rule in patterns.js. Real, ground-truth
+ * inspection of this machine's own Claude Code session files confirms the
+ * exact shape a pasted or tool-returned image takes in the JSONL transcript
+ * (both as a direct message content block and nested inside a tool_result):
+ *   {"type":"image","source":{"type":"base64","media_type":"image/png","data":"<base64>"}}
+ * This module's job stops at extracting that data and turning it into text;
+ * the text then flows through the exact same PATTERNS rules and redact()
+ * every other line in a transcript does — no new detection logic, no new
+ * false-positive surface, just a new place text can come from.
+ *
+ * Same shell-out posture as verify.js's AWS check, for the same reason:
+ * residoo ships zero runtime dependencies, and a correct from-scratch OCR
+ * engine is not something this project could build or verify. tesseract is
+ * the mature, widely-packaged, offline OCR engine every major distro and
+ * Homebrew ships; shelling out to an already-installed copy costs nothing
+ * at install time and adds no dependency residoo itself carries. Off by
+ * default: it requires tesseract to be installed, and it is real CPU work
+ * per image, unlike every other rule in this file which is a regex over
+ * text already in memory.
+ *
+ * Image bytes go to tesseract over stdin and its output is read back over
+ * stdout -- never written to a file, matching every other credential-
+ * bearing value in this codebase never touching disk unless --seal is
+ * explicitly asked for. Nothing here makes a network call; tesseract's own
+ * OCR is 100% local.
+ *
+ * HONEST LIMITATION, found by testing this module against a real rendered
+ * image before shipping it (not assumed): OCR is lossy. A real test against
+ * a clean, large, monospace "AKIASM0KETESTFAKEKEY"-shaped string produced
+ * "AKIASM@KETESTFAKEKE*" at low resolution and "AKIASMOKETESTFAKEKE*" (0
+ * misread as O, trailing Y misread as *) even at 2x resolution -- visually
+ * similar characters (0/O, Y/*) are a real, inherent tesseract failure
+ * mode, not a bug in how this module invokes it. A single misread character
+ * breaks an exact-format regex match. This means --ocr is best-effort
+ * additive coverage on a previously-zero-coverage surface, not a guarantee
+ * every credential in every screenshot will be caught -- documented here so
+ * that claim is never overstated in the CLI help text or README either.
+ */
+
+const { spawnSync } = require("child_process");
+
+// Test-only escape hatch, same pattern as verify.js's RESIDOO_TEST_AWS_CLI:
+// when set, every spawnSync call below runs that path instead of
+// "tesseract" on PATH, so tests exercise the real spawnSync + stdin/stdout
+// plumbing against a small fixture script rather than requiring the real
+// tesseract binary (or the network) on every machine that runs `npm test`.
+function tesseractBinary() {
+  return process.env.RESIDOO_TEST_TESSERACT || "tesseract";
+}
+
+function isTesseractAvailable(spawnFn = spawnSync) {
+  try {
+    const r = spawnFn(tesseractBinary(), ["--version"], {
+      timeout: 5000,
+      env: { PATH: process.env.PATH || "" },
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    return !r.error && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// A real screenshot is rarely more than a few MB; this is a generous
+// ceiling against a maliciously or accidentally huge "image" field in an
+// attacker-plantable transcript, not a real-world limit. Base64 is ~4/3
+// the decoded size, hence the larger character-count bound.
+const MAX_BASE64_CHARS = 30_000_000; // ~22 MB decoded
+// A single line with hundreds of embedded images (crafted or corrupted)
+// must not turn --ocr into a hang; cap how many this module will even
+// attempt per line. Real transcripts have at most a handful of images per
+// message.
+const MAX_BLOCKS_PER_LINE = 8;
+const MAX_WALK_DEPTH = 12; // defensive bound against pathological nesting
+
+const KNOWN_IMAGE_MEDIA_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
+
+/**
+ * Find every {type:"image", source:{type:"base64", data, media_type}}
+ * block in a transcript line, at any nesting depth (a direct message
+ * content block and a tool_result's nested content block are both real,
+ * confirmed shapes -- see this file's own docstring). Returns
+ * [{ data, mediaType }], capped at MAX_BLOCKS_PER_LINE.
+ *
+ * Not every source's lines are JSON (or valid JSON) -- a malformed or
+ * partial line fails JSON.parse and this returns [] rather than throwing,
+ * the same fail-quiet-on-this-one-line posture decode.js's contentProjection
+ * already has for the exact same reason.
+ */
+function extractImageBlocks(line) {
+  const t = typeof line === "string" ? line.trim() : "";
+  if (t[0] !== "{" && t[0] !== "[") return [];
+  let parsed;
+  try { parsed = JSON.parse(t); } catch { return []; }
+
+  const out = [];
+  const walk = (node, depth) => {
+    if (out.length >= MAX_BLOCKS_PER_LINE || depth > MAX_WALK_DEPTH || node == null || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const item of node) { if (out.length >= MAX_BLOCKS_PER_LINE) return; walk(item, depth + 1); }
+      return;
+    }
+    const source = node.source;
+    if (
+      node.type === "image" && source && typeof source === "object" &&
+      source.type === "base64" && typeof source.data === "string" && source.data.length > 0 &&
+      source.data.length <= MAX_BASE64_CHARS &&
+      KNOWN_IMAGE_MEDIA_TYPES.has(source.media_type)
+    ) {
+      out.push({ data: source.data, mediaType: source.media_type });
+      return; // an image block's own fields are never themselves nested image blocks
+    }
+    for (const key of Object.keys(node)) { if (out.length >= MAX_BLOCKS_PER_LINE) return; walk(node[key], depth + 1); }
+  };
+  walk(parsed, 0);
+  return out;
+}
+
+const DEFAULT_TIMEOUT_MS = 20_000;
+
+/** Strip control bytes: OCR output flows into the exact same matching/redaction path as any other text, but must never carry a raw control byte into a terminal. */
+function stripControlChars(s) { return String(s || "").replace(/[\x00-\x1f\x7f]/g, ""); }
+
+/**
+ * OCR one image's base64 data via tesseract over stdin/stdout. Returns
+ * { text, error }: text is "" (never null) on any failure, so a caller
+ * never needs a null check before feeding it through the pattern-matching
+ * loop; error names why when text is empty, for --ocr's own diagnostics,
+ * never surfaced as a scan failure (an unreadable or corrupt image is not
+ * a reason to fail the whole scan).
+ */
+function ocrImageBase64(base64Data, { spawnFn = spawnSync, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  let buf;
+  try {
+    buf = Buffer.from(base64Data, "base64");
+  } catch (e) {
+    return { text: "", error: `could not decode base64 image data (${e && e.message})` };
+  }
+  if (buf.length === 0) return { text: "", error: "decoded image was empty" };
+
+  let r;
+  try {
+    r = spawnFn(tesseractBinary(), ["stdin", "stdout"], {
+      input: buf,
+      timeout: timeoutMs,
+      maxBuffer: 10 * 1024 * 1024,
+      env: { PATH: process.env.PATH || "" },
+    });
+  } catch (e) {
+    return { text: "", error: `tesseract failed to run (${e && e.message})` };
+  }
+  if (r.error) {
+    if (r.error.code === "ENOENT") return { text: "", error: "tesseract not found on PATH" };
+    if (r.error.code === "ETIMEDOUT") return { text: "", error: `tesseract timed out after ${timeoutMs}ms` };
+    return { text: "", error: `tesseract failed to run (${r.error.code || r.error.message})` };
+  }
+  if (r.status !== 0) {
+    return { text: "", error: `tesseract exited ${r.status}` };
+  }
+  return { text: stripControlChars((r.stdout || "").toString("utf-8")), error: null };
+}
+
+module.exports = { isTesseractAvailable, extractImageBlocks, ocrImageBase64, tesseractBinary };

package/src/report.js

@@ -466,9 +466,11 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
     // so the reader should know the value was hidden.
     const encoded = items.filter((f) => f.encoding).length;
     const split = items.filter((f) => f.spanLines).length;
+    const ocrd = items.filter((f) => f.ocr).length;
     const marks = [];
     if (encoded) marks.push(`${encoded} base64-wrapped`);
     if (split) marks.push(`${split} split across lines`);
+    if (ocrd) marks.push(`${ocrd} read from a pasted image (--ocr)`);
     const markNote = marks.length ? paint(c.yellow, `  [${marks.join(", ")}]`) : "";
     const paddedLabel = label.length <= labelWidth ? label.padEnd(labelWidth) : label;
     push(`  ${paint(color + c.bold, String(items.length).padStart(4))}  [${tag}]  ${paddedLabel}${distinctNote}${markNote}`);
@@ -526,17 +528,21 @@ function renderJson(result, integrity = null, rotation = null) {
         bytesScanned: result.bytesScanned,
         suppressedCount: result.suppressedCount || 0,
         unreadableFiles: result.unreadableFiles || [],
+        ocrRequestedButMissing: result.ocrRequestedButMissing || false,
       },
       findings: result.findings.map((f) => ({
         rule: f.ruleId, label: f.label, confidence: f.confidence,
         source: f.source, file: f.relFile, line: f.line, preview: f.preview,
         fileMTimeMs: f.fileMTimeMs,
-        // Markers for the two decode/reconstruct passes (absent on ordinary
+        // Markers for the decode/reconstruct/OCR passes (absent on ordinary
         // findings). `encoding` names how the value was wrapped ("base64" /
         // "base64url"); `spanLines` names the adjacent line pair a split value
-        // was reconstructed across.
+        // was reconstructed across; `ocr` means the value was never plain
+        // text at all -- it was read out of a pasted or tool-returned image
+        // (see ocr.js).
         ...(f.encoding ? { encoding: f.encoding } : {}),
         ...(f.spanLines ? { spanLines: f.spanLines } : {}),
+        ...(f.ocr ? { ocr: true } : {}),
         fingerprint: fingerprintFinding(f),
         // Only present on an --include-suppressed run: says WHY this finding
         // is low-confidence, so a JSON consumer doesn't have to guess.
@@ -643,4 +649,202 @@ function renderSarif(result) {
   }, null, 2);
 }
 
-module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif, makeProgressReporter, printIntro };
+function escapeHtml(s) {
+  return String(s == null ? "" : s)
+    .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+const HTML_REPORT_STYLE = `
+:root { color-scheme: dark; --bg:#0d1117; --panel:#161b22; --border:#30363d; --text:#c9d1d9;
+  --dim:#8b949e; --red:#f85149; --yellow:#d29922; --green:#3fb950; --cyan:#58a6ff; --accent:#238636; }
+* { box-sizing: border-box; }
+body { margin:0; padding:32px; background:var(--bg); color:var(--text);
+  font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif; }
+.wrap { max-width: 1100px; margin: 0 auto; }
+h1 { font-size:20px; margin:0 0 4px; }
+.meta { color:var(--dim); font-size:12px; margin-bottom:24px; }
+.cards { display:flex; gap:12px; flex-wrap:wrap; margin-bottom:24px; }
+.card { background:var(--panel); border:1px solid var(--border); border-radius:8px;
+  padding:14px 18px; min-width:140px; }
+.card .n { font-size:24px; font-weight:700; }
+.card .l { color:var(--dim); font-size:12px; margin-top:2px; }
+.clean { background:var(--panel); border:1px solid var(--accent); border-radius:8px;
+  padding:20px; color:var(--green); font-weight:600; }
+input#filter { width:100%; padding:10px 12px; margin-bottom:14px; background:var(--panel);
+  border:1px solid var(--border); border-radius:8px; color:var(--text); font-size:14px; }
+input#filter:focus { outline:1px solid var(--cyan); }
+table { width:100%; border-collapse:collapse; background:var(--panel); border:1px solid var(--border);
+  border-radius:8px; overflow:hidden; margin-bottom:24px; }
+th, td { text-align:left; padding:10px 12px; border-bottom:1px solid var(--border); font-size:13px; }
+th { color:var(--dim); font-weight:600; font-size:11px; text-transform:uppercase; letter-spacing:.03em; }
+tr:last-child td { border-bottom:none; }
+tr.row:hover { background:#1c232c; cursor:pointer; }
+.conf-high { color:var(--red); font-weight:600; } .conf-medium { color:var(--yellow); font-weight:600; }
+.conf-low { color:var(--dim); }
+.status-pending { color:var(--yellow); } .status-acked { color:var(--green); } .status-dismissed { color:var(--dim); }
+code.preview { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; background:#0000004d;
+  padding:1px 6px; border-radius:4px; }
+.guide { display:none; background:#0000004d; padding:12px 16px; }
+.guide.open { display:table-row; }
+.guide td { border-bottom:1px solid var(--border); }
+.guide ol { margin:6px 0; padding-left:20px; }
+.guide a { color:var(--cyan); }
+.note { color:var(--dim); font-size:12px; margin-top:2px; }
+.section-title { font-size:15px; font-weight:600; margin:24px 0 10px; }
+.warn-badge { display:inline-block; background:#f8514922; color:var(--red); border:1px solid var(--red);
+  border-radius:4px; padding:1px 8px; font-size:11px; font-weight:600; margin-left:8px; }
+.footer { color:var(--dim); font-size:12px; margin-top:32px; border-top:1px solid var(--border); padding-top:16px; }
+`;
+
+const HTML_REPORT_SCRIPT = `
+document.getElementById("filter")?.addEventListener("input", function (e) {
+  var q = e.target.value.toLowerCase();
+  document.querySelectorAll("tr.row").forEach(function (row) {
+    var hit = row.getAttribute("data-search").includes(q);
+    row.style.display = hit ? "" : "none";
+    var g = row.nextElementSibling;
+    if (g && g.classList.contains("guide") && !hit) g.classList.remove("open");
+  });
+});
+document.querySelectorAll("tr.row").forEach(function (row) {
+  row.addEventListener("click", function () {
+    var g = row.nextElementSibling;
+    if (g && g.classList.contains("guide")) g.classList.toggle("open");
+  });
+});
+`;
+
+/**
+ * Self-contained, single-file HTML report (residoo scan --html). Same data
+ * as renderJson (findings deduped by rotation.js into distinct-value rows,
+ * plus integrity), presented for the audience --json/--sarif don't serve
+ * well: a screenshot for an incident channel, or a non-CLI teammate.
+ *
+ * Every value shown is `f.preview`/`entry.preview` — already redacted by
+ * patterns.js's redact() before it ever reaches this function, the same
+ * guarantee every other output format has. Unlike a competitor's own HTML
+ * report (which explicitly notes only its HTML mode masks values, and its
+ * JSON mode ships full raw secrets "for incident response"), residoo has
+ * no output mode, in any format, that ever writes a raw value — this
+ * function has no code path that could regress that, since it never
+ * receives the raw value in the first place.
+ *
+ * No external CSS/JS/fonts/images: everything is inlined below, so the
+ * file opens correctly with no network access, matching residoo's own
+ * "no network calls in the default path" posture for the report itself,
+ * not just the scan that produced it.
+ */
+function renderHtml(result, integrity = null, rotation = null) {
+  const { version } = require("../package.json");
+  const findings = result.findings || [];
+  const scannedAt = localTimestamp(new Date());
+  const distinct = rotation && rotation.counts ? rotation.counts.distinct : 0;
+  const pending = rotation && rotation.counts ? rotation.counts.pending : 0;
+  const confirmedDead = rotation && rotation.counts ? rotation.counts.confirmedDead || 0 : 0;
+  const needsReview = Math.max(0, pending - confirmedDead);
+  const byFile = new Set(findings.map((f) => f.file)).size;
+  const integrityWarns = integrity ? integrity.findings.filter((f) => f.severity === "warn").length : 0;
+
+  const head =
+    `<!doctype html><html><head><meta charset="utf-8">` +
+    `<meta name="viewport" content="width=device-width, initial-scale=1">` +
+    `<meta name="robots" content="noindex">` +
+    `<title>residoo report -- ${escapeHtml(scannedAt)}</title>` +
+    `<style>${HTML_REPORT_STYLE}</style></head><body><div class="wrap">` +
+    `<h1>residoo report</h1>` +
+    `<div class="meta">v${escapeHtml(version)} &middot; scanned ${escapeHtml(scannedAt)} &middot; ` +
+    `generated locally, never uploaded &mdash; safe to share, values below are redacted</div>`;
+
+  if (findings.length === 0) {
+    const body =
+      `<div class="clean">&#10003; No exposed secrets found: ${filesScannedLine(result)}</div>` +
+      (integrity ? renderIntegrityHtml(integrity) : "") +
+      `</div></body></html>`;
+    return head + body;
+  }
+
+  const cards =
+    `<div class="cards">` +
+    card(String(findings.length), `finding${findings.length === 1 ? "" : "s"} across ${byFile} file${byFile === 1 ? "" : "s"}`) +
+    card(String(distinct), `distinct value${distinct === 1 ? "" : "s"}`) +
+    card(String(needsReview), `need${needsReview === 1 ? "s" : ""} review`) +
+    card(String(result.filesScanned), "files scanned") +
+    `</div>`;
+
+  const rows = (rotation && rotation.entries ? [...rotation.entries] : [])
+    .sort((a, b) => b.occurrences - a.occurrences)
+    .map((e) => rotationRowHtml(e))
+    .join("");
+
+  const table =
+    `<input id="filter" type="text" placeholder="Filter by rule, file, or preview...">` +
+    `<table><thead><tr><th>Rule</th><th>Status</th><th>Preview</th><th>Seen</th><th>Files</th></tr></thead>` +
+    `<tbody>${rows}</tbody></table>`;
+
+  const integritySection = integrity
+    ? `<div class="section-title">Integrity checks${integrityWarns > 0 ? `<span class="warn-badge">${integrityWarns} warning${integrityWarns === 1 ? "" : "s"}</span>` : ""}</div>` +
+      renderIntegrityHtml(integrity)
+    : "";
+
+  const footer =
+    `<div class="footer">Values are redacted (first/last 4 characters only). Nothing in this file, or in the scan` +
+    ` that produced it, ever left this machine. Generated by <code class="preview">residoo scan --html</code> --` +
+    ` github.com/dandovdub/residoo</div>`;
+
+  return head + cards + table + integritySection + footer + `<script>${HTML_REPORT_SCRIPT}</script></div></body></html>`;
+}
+
+function card(n, label) {
+  return `<div class="card"><div class="n">${escapeHtml(n)}</div><div class="l">${escapeHtml(label)}</div></div>`;
+}
+
+function filesScannedLine(result) {
+  return `${result.filesScanned} file${result.filesScanned === 1 ? "" : "s"} scanned across ${(result.sourcesScanned || []).join(", ") || "no sources"}`;
+}
+
+const HTML_STATUS_LABEL = { pending: "pending", acked: "rotated", dismissed: "dismissed" };
+
+function rotationRowHtml(e) {
+  const search = escapeHtml(`${e.label} ${e.ruleId} ${e.preview} ${(e.files || []).join(" ")}`.toLowerCase());
+  const filesShown = (e.files || []).slice(0, 3).map((f) => safeBasename(f));
+  const moreFiles = (e.files || []).length - filesShown.length;
+  const g = e.guidance || {};
+  const link = g.rotateUrl
+    ? `<a href="${escapeHtml(g.rotateUrl)}" target="_blank" rel="noopener">${escapeHtml(g.rotateUrl)}</a>`
+    : escapeHtml(g.consolePath || "");
+  const steps = (g.steps || []).map((s) => `<li>${escapeHtml(s)}</li>`).join("");
+  return (
+    `<tr class="row" data-search="${search}">` +
+    `<td>${escapeHtml(e.label)}</td>` +
+    `<td class="status-${escapeHtml(e.status)}">${escapeHtml(HTML_STATUS_LABEL[e.status] || e.status)}</td>` +
+    `<td><code class="preview">${escapeHtml(e.preview)}</code></td>` +
+    `<td>${e.occurrences}&times;</td>` +
+    `<td>${escapeHtml(filesShown.join(", "))}${moreFiles > 0 ? ` +${moreFiles} more` : ""}</td>` +
+    `</tr>` +
+    `<tr class="guide"><td colspan="5">` +
+    `<div><strong>${escapeHtml(g.label || e.label)}</strong></div>` +
+    (link ? `<div class="note">${link}</div>` : "") +
+    (steps ? `<ol>${steps}</ol>` : "") +
+    (g.revokeNote ? `<div class="note">${escapeHtml(g.revokeNote)}</div>` : "") +
+    `</td></tr>`
+  );
+}
+
+function renderIntegrityHtml(integrity) {
+  if (!integrity.findings || integrity.findings.length === 0) {
+    return `<div class="clean" style="margin-bottom:24px">&#10003; No integrity findings.</div>`;
+  }
+  const rows = integrity.findings.map((f) =>
+    `<tr><td class="status-${f.severity === "warn" ? "pending" : "dismissed"}">${escapeHtml(f.severity)}</td>` +
+    `<td>${escapeHtml(f.kind)}</td><td>${escapeHtml(safeBasename(f.file))}</td>` +
+    `<td>${escapeHtml(f.detail || "")}</td></tr>`
+  ).join("");
+  return (
+    `<table><thead><tr><th>Severity</th><th>Kind</th><th>File</th><th>Detail</th></tr></thead>` +
+    `<tbody>${rows}</tbody></table>` +
+    (integrity.scopeNote ? `<div class="note">${escapeHtml(integrity.scopeNote)}</div>` : "")
+  );
+}
+
+module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif, renderHtml, makeProgressReporter, printIntro };

package/src/scan.js

@@ -3,6 +3,7 @@
 const path = require("path");
 const { PATTERNS, NOISY_PATTERNS, redact } = require("./patterns");
 const { findDecodedMatches, findBoundaryMatches, contentProjection } = require("./decode");
+const { isTesseractAvailable, extractImageBlocks, ocrImageBase64 } = require("./ocr");
 const { findPairedSecret, findNearbyCandidate } = require("./pairing");
 const { looksRandom } = require("./rarity");
 const { decodeJwtExpiryMs } = require("./jwtExpiry");
@@ -266,8 +267,15 @@ function localTimestamp(d) {
  * absolute path can itself carry a username or a project name the rest of
  * this report is careful never to print.
  */
-async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null, verify = false, verifyOnlyFingerprint = null, onBeforeVerify = null, noColor = false } = {}) {
+async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null, verify = false, verifyOnlyFingerprint = null, onBeforeVerify = null, noColor = false, ocr = false } = {}) {
   const rules = includeNoisy ? PATTERNS.concat(NOISY_PATTERNS) : PATTERNS;
+  // --ocr: checked once, not per line/image -- isTesseractAvailable shells
+  // out, and this scan can touch thousands of lines. ocrRequestedButMissing
+  // flows back to the caller (see the return value below) so a user who
+  // asked for --ocr without tesseract installed gets a clear, once-per-scan
+  // message, not silence and zero image findings.
+  const ocrReady = ocr && isTesseractAvailable();
+  const ocrRequestedButMissing = ocr && !ocrReady;
   // The decode pass (see decode.js) only applies high-confidence, vendor-
   // prefixed rules to decoded bytes: random binary that decodes to printable
   // text can shape-match a generic rule, but not a vendor prefix. NOISY rules
@@ -559,6 +567,34 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
     }
   };
 
+  // --ocr only: a line whose JSON shape holds a pasted or tool-returned
+  // image (see ocr.js's docstring for the exact confirmed shape) gets each
+  // image block decoded and OCR'd, and the extracted text runs through the
+  // same high-confidence rules the decode pass above uses, for the same
+  // reason -- a step removed from literal transcript text deserves the
+  // higher bar. Every finding carries an `ocr: true` marker so a report can
+  // say where the value actually came from.
+  const ocrLine = (line, file, relFile, lineNo, mtimeMs) => {
+    if (!ocrReady) return;
+    for (const block of extractImageBlocks(line)) {
+      const { text } = ocrImageBase64(block.data);
+      if (!text) continue;
+      for (const rule of highRules) {
+        rule.re.lastIndex = 0;
+        let m;
+        while ((m = rule.re.exec(text)) !== null) {
+          const suppressedReason = suppressionReason(m[0], null, rule.id);
+          if (suppressedReason && !includeSuppressed) {
+            suppressedCount++;
+            continue;
+          }
+          record(rule, m[0], relFile, file, lineNo, mtimeMs,
+            suppressedReason ? "low" : rule.confidence, suppressedReason, { ocr: true });
+        }
+      }
+    }
+  };
+
   // Feature 2: split-line boundary join. A finding here means one credential
   // was split across this line and the next and is contiguous on neither. It
   // is recorded against BOTH contributing lines (each holds a fragment of the
@@ -669,6 +705,13 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
           } catch (err) {
             flagFailed();
           }
+          if (ocrReady) {
+            try {
+              ocrLine(line, file, relFile, i + 1, mtimeMs);
+            } catch (err) {
+              flagFailed();
+            }
+          }
           try {
             const content = contentProjection(line);
             // Boundary join with the previous line (2-way splits only; see
@@ -872,7 +915,7 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
 
   const distinctCounts = {};
   for (const [ruleId, set] of distinctByRule) distinctCounts[ruleId] = set.size;
-  return { findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount, distinctCounts, unreadableFiles };
+  return { findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount, distinctCounts, unreadableFiles, ocrRequestedButMissing };
 }
 
 /**
@@ -884,7 +927,7 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
 function emptyResult() {
   return {
     findings: [], filesScanned: 0, sourcesScanned: [], bytesScanned: 0,
-    suppressedCount: 0, distinctCounts: {}, unreadableFiles: [],
+    suppressedCount: 0, distinctCounts: {}, unreadableFiles: [], ocrRequestedButMissing: false,
   };
 }