residoo 0.9.0 → 0.11.0

package/README.md

@@ -51,8 +51,10 @@ into the conversation at all — which also means a long session compacting
 away the exact value you pasted days ago can't force you to paste it
 again, since there's nothing to lose. `residoo guard` blocks an obviously
 sensitive file read before it happens (100% recall, 0% false positives on
-its own [scored 81-case corpus](bench/guard/RESULTS.md)). All four are
-covered in [docs/features.md](docs/features.md).
+its own [scored 81-case corpus](bench/guard/RESULTS.md)) and, via a second
+hook, a secret typed directly into the prompt itself — confirmed against
+Claude Code's own docs to block before the model ever processes it. All
+four are covered in [docs/features.md](docs/features.md).
 
 > [!NOTE]
 > gitleaks and trufflehog scan **commits**. residoo scans the **conversation
@@ -121,6 +123,11 @@ while losing rows, then fixed in public against the classes it was losing
   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.
@@ -133,7 +140,8 @@ while losing rows, then fixed in public against the classes it was losing
   for CI and pre-commit. See [docs/ci.md](docs/ci.md).
 - `residoo watch` / `residoo mcp` / `residoo cred` / `residoo guard`:
   continuous scanning, conversational queries, credential injection
-  without pasting, and pre-read blocking. See [docs/features.md](docs/features.md).
+  without pasting, and blocking a sensitive file read or a sensitive
+  prompt before either happens. See [docs/features.md](docs/features.md).
 
 ## What it does not do
 
@@ -203,6 +211,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.9.0",
+  "version": "0.11.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

@@ -138,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:
@@ -206,24 +218,47 @@ Cred:
   tool, present only when RESIDOO_CRED_ALLOWED_COMMANDS is configured.
 
 Guard:
-  residoo guard             a Claude Code PreToolUse hook that blocks an
-                          obviously-sensitive file read (.env, id_rsa,
-                          .aws/credentials, and similar) before it can be
-                          written to the session transcript at all --
-                          prevention, not just detection. Reads one hook
-                          payload from stdin, writes a deny decision to
-                          stdout only when it matches; never blocks on
-                          anything it doesn't recognize. This is narrower
-                          than it sounds: Claude Code's hooks API can see a
-                          proposed Bash command or Read path before it
-                          runs, but never the command's OUTPUT, so this
-                          cannot catch a secret typed into a prompt or one
-                          arriving through an unrelated command's output --
-                          scan/watch/mcp remain the real safety net. Add to
+  residoo guard             one binary, two Claude Code hooks, dispatched on
+                          the payload's own hook_event_name:
+
+                          PreToolUse blocks an obviously-sensitive file read
+                          (.env, id_rsa, .aws/credentials, and similar)
+                          before it can be written to the session
+                          transcript at all. Narrower than it sounds:
+                          Claude Code's hooks API can see a proposed Bash
+                          command or Read path before it runs, but never
+                          the command's OUTPUT, so this alone cannot catch
+                          a secret typed into a prompt or one arriving
+                          through an unrelated command's output.
+
+                          UserPromptSubmit closes exactly that gap: it
+                          checks the user's own typed prompt against
+                          residoo's 79 high-confidence rules (never
+                          --verify, never --ocr -- this hook has no matcher
+                          and fires on every single prompt, so it must stay
+                          fast) and can block it before Claude processes it
+                          at all -- confirmed directly against Claude
+                          Code's own docs, not assumed. A block ERASES the
+                          user's whole typed message, so this path is
+                          extra-conservative: a documented vendor-example
+                          key or an obvious placeholder is suppressed, same
+                          as residoo scan itself. Best-effort, not a
+                          guarantee: per Claude Code's own docs, a slow
+                          hook here fails OPEN (the prompt goes through
+                          unscanned) rather than stalling the session,
+                          consistent with this hook never blocking on
+                          anything it doesn't recognize.
+
+                          scan/watch/mcp remain the real safety net either
+                          way -- this is prevention on top of detection,
+                          not a replacement for it. Add both to
                           .claude/settings.json:
-                            {"hooks":{"PreToolUse":[{"matcher":"Bash|Read",
-                            "hooks":[{"type":"command",
-                            "command":"residoo guard"}]}]}}
+                            {"hooks":{
+                              "PreToolUse":[{"matcher":"Bash|Read",
+                                "hooks":[{"type":"command",
+                                "command":"residoo guard"}]}],
+                              "UserPromptSubmit":[{"hooks":[{"type":"command",
+                                "command":"residoo guard"}]}]}}
 
 Rotation:
   residoo explain <rule-id>     full rotation runbook for one detection rule
@@ -876,6 +911,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.
@@ -987,7 +1029,7 @@ async function main(argv) {
 
   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
@@ -998,6 +1040,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

package/src/guard.js

@@ -1,9 +1,11 @@
 "use strict";
 
 /**
- * `residoo guard`: a Claude Code PreToolUse hook that blocks an obviously-
- * sensitive file read before it happens, instead of finding the leak in the
- * transcript afterward.
+ * `residoo guard`: two Claude Code hooks in one binary, dispatched on the
+ * payload's own `hook_event_name` field.
+ *
+ * PreToolUse blocks an obviously-sensitive file read before it happens,
+ * instead of finding the leak in the transcript afterward.
  *
  * Scope, stated plainly because it is much narrower than "prevent secrets
  * from leaking": Claude Code's hooks API gives a PreToolUse hook the
@@ -17,17 +19,53 @@
  * and similar) -- it cannot catch a secret typed directly into a prompt, a
  * secret arriving in the output of an otherwise-unremarkable command
  * (curl, a build log), or any file path this pattern list does not name.
- * `residoo scan`/`watch`/`mcp` remain the actual safety net; this is a
- * narrower, best-effort tripwire on top, not a replacement for them.
+ *
+ * UserPromptSubmit closes exactly the "typed directly into a prompt" gap
+ * named above: Claude Code's own docs (code.claude.com/docs/en/hooks,
+ * fetched and read directly, not summarized secondhand) confirm this hook
+ * "runs before every prompt and blocks model processing until it
+ * completes" -- a real prevention point, not an after-the-fact alert.
+ * Verified precisely, not assumed: the payload's `prompt` field carries the
+ * exact submitted text (the field is `prompt`, NOT `user_prompt` -- a
+ * specific claim to the contrary did not survive this session's own
+ * adversarial verification pass), and a JSON response with
+ * `"decision": "block"` "prevents the prompt from being processed and
+ * erases it from context." Checked against residoo's existing 79
+ * high-confidence PATTERNS.js rules ONLY -- never NOISY_PATTERNS, never
+ * --verify (a network call), never --ocr (tesseract, and irrelevant to a
+ * text prompt anyway) -- because this hook has NO matcher support (it
+ * fires on every single prompt in every session, confirmed in the same
+ * docs) and must stay fast: Claude Code's own default timeout for this
+ * event's command hooks is 30s, down from 600s elsewhere, specifically
+ * because "a stuck hook stalls the session." A false positive here also
+ * costs more than a PreToolUse block: it erases the user's entire typed
+ * message, not one denied tool call, which is why this path additionally
+ * runs the same vendor-example/placeholder suppression `residoo scan`
+ * itself uses (see scan.js's VENDOR_EXAMPLE_VALUES/zeroEntropyTail) before
+ * ever blocking -- a documented AWS example key or an obvious placeholder
+ * must never eat a real prompt.
+ *
+ * Same fail-open timeout reality as scan.js's whole 30-vendor --verify
+ * surface, disclosed rather than hidden: per Claude Code's own docs, a
+ * command/http/mcp_tool hook (this one) that times out on UserPromptSubmit
+ * has its output discarded and "the prompt still reaches Claude" unblocked
+ * -- a genuinely slow scan cannot stall the session, but that also means
+ * this is best-effort, additive coverage, not an absolute guarantee, the
+ * same honesty already applied to --ocr.
  *
  * Fails safe in the direction of NOT blocking on any uncertainty: a
  * malformed hook payload, an unrecognized tool name, or a parse error all
  * fall through to "allow" (no stdout, exit 0) rather than denying a call
  * this module does not understand. The one thing this module must never do
- * is silently hang or crash the agent's turn over a tool call that was
- * always going to be fine.
+ * is silently hang or crash the agent's turn over a tool call -- or a
+ * prompt -- that was always going to be fine. `residoo scan`/`watch`/`mcp`
+ * remain the actual safety net; this is a narrower, best-effort tripwire on
+ * top, not a replacement for them.
  */
 
+const { PATTERNS, redact } = require("./patterns");
+const { VENDOR_EXAMPLE_VALUES, zeroEntropyTail } = require("./scan");
+
 // 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
@@ -127,12 +165,49 @@ function evaluateToolInput(toolName, toolInput) {
   };
 }
 
+// High-confidence only, computed once at module load (PATTERNS is a static
+// array): never NOISY_PATTERNS, matching the same elevated bar decodeLine/
+// ocrLine already use in scan.js for content one step removed from a plain
+// file line -- a user's own live-typed prompt deserves at least that same
+// bar, arguably a higher one given what a wrong block costs here (see this
+// file's own docstring).
+const PROMPT_GUARD_RULES = PATTERNS.filter((r) => r.confidence === "high");
+
+/**
+ * Pure decision function: given a UserPromptSubmit hook payload's raw
+ * `prompt` string, decide whether to block. No I/O, fully unit-testable.
+ * Suppresses the same way `residoo scan` does (a documented vendor-example
+ * key, or an obviously-placeholder zero-entropy tail) before ever blocking
+ * -- a false positive here erases the user's entire typed message, not one
+ * denied tool call, so this path is deliberately more conservative than
+ * evaluateToolInput above, not just a copy of the same bar.
+ */
+function evaluatePromptText(promptText) {
+  if (typeof promptText !== "string" || !promptText) return { block: false, reason: null };
+  for (const rule of PROMPT_GUARD_RULES) {
+    rule.re.lastIndex = 0;
+    const m = rule.re.exec(promptText);
+    if (!m) continue;
+    const value = m[0];
+    if (VENDOR_EXAMPLE_VALUES.has(value) || zeroEntropyTail(value)) continue;
+    return {
+      block: true,
+      reason: `residoo guard: this prompt looks like it contains ${rule.label} (${redact(value)}). ` +
+        `Blocked before it could be sent. If this is a false positive, rephrase or remove it, or disable this hook in .claude/settings.json.`,
+    };
+  }
+  return { block: false, reason: null };
+}
+
 /**
- * Reads one PreToolUse hook payload from `input` (default stdin), decides,
- * and writes the hook's own JSON response protocol to `output` (default
- * stdout) -- exit code is the caller's job (bin/residoo.js), this returns
- * the intended process exit code instead of calling process.exit itself,
- * matching every other run* function in cli.js.
+ * Reads one PreToolUse OR UserPromptSubmit hook payload from `input`
+ * (default stdin) -- distinguished by the payload's own `hook_event_name`
+ * common field, a single binary handling both the way Claude Code's own
+ * hook registration allows -- decides, and writes the hook's own JSON
+ * response protocol to `output` (default stdout) -- exit code is the
+ * caller's job (bin/residoo.js), this returns the intended process exit
+ * code instead of calling process.exit itself, matching every other run*
+ * function in cli.js.
  */
 async function runGuard({ input = process.stdin, output = process.stdout } = {}) {
   const chunks = [];
@@ -146,6 +221,20 @@ async function runGuard({ input = process.stdin, output = process.stdout } = {})
     return 0; // malformed payload: fail open, never block on something we can't parse
   }
 
+  // hook_event_name is a documented COMMON field present on every hook
+  // event's payload (code.claude.com/docs/en/hooks), not specific to one
+  // event -- checked first so a UserPromptSubmit payload (which has no
+  // tool_name/tool_input at all) never falls through to evaluateToolInput
+  // and is instead routed to its own decision function and its own
+  // response shape (decision:"block", not hookSpecificOutput.
+  // permissionDecision -- the two events do not share a response schema).
+  if (payload.hook_event_name === "UserPromptSubmit") {
+    const decision = evaluatePromptText(payload.prompt);
+    if (!decision.block) return 0;
+    output.write(JSON.stringify({ decision: "block", reason: decision.reason }) + "\n");
+    return 0;
+  }
+
   const decision = evaluateToolInput(payload.tool_name, payload.tool_input);
   if (!decision.block) return 0;
 
@@ -159,4 +248,4 @@ async function runGuard({ input = process.stdin, output = process.stdout } = {})
   return 0;
 }
 
-module.exports = { evaluateToolInput, matchSensitivePath, runGuard, SENSITIVE_PATH_PATTERNS };
+module.exports = { evaluateToolInput, matchSensitivePath, evaluatePromptText, runGuard, SENSITIVE_PATH_PATTERNS };

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.

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,
   };
 }
 
@@ -900,4 +943,4 @@ function emptyResult() {
 // so residoo_verify_finding's v1 only supports the single-token vendors below.
 const VERIFIABLE_RULE_IDS = new Set(Object.keys(SIMPLE_VERIFY_FNS));
 
-module.exports = { scan, emptyResult, VENDOR_EXAMPLE_VALUES, VERIFIABLE_RULE_IDS };
+module.exports = { scan, emptyResult, VENDOR_EXAMPLE_VALUES, VERIFIABLE_RULE_IDS, zeroEntropyTail };