residoo 0.9.0 → 0.10.0

package/README.md

@@ -121,6 +121,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.
@@ -203,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.9.0",
+  "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

@@ -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:
@@ -876,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.
@@ -987,7 +1006,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 +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

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,
   };
 }