residoo 0.20.0 → 0.22.0

package/README.md

@@ -251,10 +251,11 @@ prompt. There is no recovery if you lose it, so pick one you keep.
 
 ## Sources supported today
 
-44 sources, real-install-verified for Claude Code and its config family,
-multi-source-corroborated for the rest (Cursor, Codex CLI, Cline, Windsurf,
-Gemini CLI, Copilot, and 30+ more). Full list, what "corroborated" means,
-and how to add one: [docs/sources.md](docs/sources.md).
+45 sources, real-install-verified for Claude Code, its config family, and
+bash/Python-REPL shell history, multi-source-corroborated for the rest
+(Cursor, Codex CLI, Cline, Windsurf, Gemini CLI, Copilot, and 30+ more).
+Full list, what "corroborated" means, and how to add one:
+[docs/sources.md](docs/sources.md).
 
 ## License
 

package/package.json

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

@@ -165,6 +165,27 @@ Scan options:
                           excludes bare email/phone (too common in
                           ordinary text to meet this
                           project's own high-confidence bar even opt-in).
+  --include-injection      also scan transcript content for prompt-
+                          injection signatures: special/role-token
+                          sequences (<|im_start|>, [INST], <<SYS>>, and
+                          similar -- the control tokens an attacker can
+                          smuggle into fetched content to make a model
+                          treat it as a privileged turn instead of
+                          untrusted data) and hidden instructions carried
+                          by invisible Unicode. A third RISK CATEGORY,
+                          neither a credential nor PII: this looks for
+                          evidence an injection attempt already reached
+                          the agent, in the same at-rest transcript
+                          content every other pass scans -- not a
+                          static-analysis check of an application's own
+                          prompt-construction code (that's a different,
+                          much bigger product; see docs/comparison.md).
+                          Combine with --include-noisy for a small set of
+                          canonical override phrases ("ignore previous
+                          instructions" and close variants) -- disclosed
+                          as genuinely heuristic and prone to matching a
+                          security-research conversation about this exact
+                          technique, not a solved detection problem.
 
 Watch:
   residoo watch            continuous scanning instead of one snapshot:
@@ -182,7 +203,8 @@ Watch:
   --verify                same opt-in vendor check as scan --verify,
                           applied to each newly found credential once,
                           never to one already seen
-  --include-noisy, --include-suppressed, --include-pii, --no-color
+  --include-noisy, --include-suppressed, --include-pii,
+  --include-injection, --no-color
                           same meaning as scan
   --no-notify             skip the OS desktop notification watch fires for
                           each genuinely new finding (macOS via osascript,
@@ -774,6 +796,7 @@ async function runWatch(args) {
   const verify = args.includes("--verify");
   const noColor = args.includes("--no-color");
   const includePii = args.includes("--include-pii");
+  const includeInjection = args.includes("--include-injection");
   const noNotify = args.includes("--no-notify");
 
   let intervalSeconds = 5;
@@ -800,7 +823,7 @@ async function runWatch(args) {
 
   const { promise, stop } = startWatch({
     sources,
-    options: { includeNoisy, includeSuppressed, verify, noColor, includePii, noNotify, json: wantsJson, pollMs: intervalSeconds * 1000 },
+    options: { includeNoisy, includeSuppressed, verify, noColor, includePii, includeInjection, noNotify, json: wantsJson, pollMs: intervalSeconds * 1000 },
   });
 
   const printFinalSummary = (stats) => {
@@ -1098,6 +1121,11 @@ async function main(argv) {
   // card numbers, IBAN) rather than the shape-only, much noisier
   // categories (bare email, phone) some competitors also ship.
   const wantsPii = args.includes("--include-pii");
+  // --include-injection: a third, separate risk category from either of the
+  // above (see injection.js) -- detects a realized prompt-injection
+  // signature already sitting in transcript content, not a credential or
+  // personal data.
+  const wantsInjection = args.includes("--include-injection");
 
   // --project [dir]: the dir is optional (CI passes ".", a bare --project
   // means the current directory). null means machine mode.
@@ -1209,7 +1237,7 @@ async function main(argv) {
 
   const progress = makeProgressReporter(noColor);
   const result = await scan({
-    sources, includeNoisy, includeSuppressed, verify, noColor, ocr: wantsOcr, includePii: wantsPii,
+    sources, includeNoisy, includeSuppressed, verify, noColor, ocr: wantsOcr, includePii: wantsPii, includeInjection: wantsInjection,
     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

package/src/injection.js

@@ -0,0 +1,139 @@
+"use strict";
+
+const { scanZeroWidth } = require("./integrity");
+
+/**
+ * Prompt-injection signature detection, applied to the SAME transcript
+ * content every other pass already reads (tool_result blocks, fetched-page
+ * text, file contents an agent read, ordinary message text) -- no new
+ * source, no new file walk, just a second/third rule set matched against
+ * lines scan.js already has in memory. Opt-in via `--include-injection`,
+ * the same "different risk category, not a lower-confidence secret"
+ * reasoning pii.js's own header states for `--include-pii`.
+ *
+ * WHAT THIS IS NOT, stated up front because it is the single most important
+ * scope distinction here: this is NOT a static-analysis scanner for an LLM
+ * APPLICATION'S OWN SOURCE CODE (an f-string concatenating user input into a
+ * prompt, unsanitized external content reaching a prompt template). That is
+ * a real, different product -- it's what Medusa's own PI-SCAN does (checked
+ * directly against Medusa's own docs/AI_SECURITY.md, fetched 2026-09-05:
+ * "Direct Injection: f-string interpolation with user_input... Indirect
+ * Injection: External content fetched and embedded in prompts without
+ * sanitization" -- both examples are about auditing an application's PROMPT
+ * -CONSTRUCTION code for a latent vulnerability class). residoo has no
+ * access to that code and isn't built to read it; what residoo already has,
+ * uniquely, is the agent's own TRANSCRIPT -- a record of what actually got
+ * fed to a live agent. So this module detects INJECTION PAYLOADS THAT
+ * ALREADY REACHED AN AGENT, sitting in the same at-rest data every other
+ * residoo pass scans -- a genuinely different, arguably more valuable
+ * signal (a realized attempt, not a hypothetical vulnerable code path), not
+ * an attempt to clone Medusa's SAST feature with a worse implementation.
+ *
+ * SIGNAL SOURCES, verified 2026-09-05:
+ *
+ *   - **Special/role-token injection**: `<|im_start|>`, `<|im_end|>`,
+ *     `<|system|>`, `<|user|>`, `<|assistant|>`, `<|endoftext|>`,
+ *     `<|endofprompt|>`, `[INST]`/`[/INST]`, `<<SYS>>`/`<</SYS>>` -- the
+ *     control tokens chat-templated models use to delineate a message's
+ *     ROLE. An attacker who gets one of these into content an agent reads
+ *     (a fetched webpage, a file, a tool's output) can, on a vulnerable
+ *     serving pipeline, make the model treat injected text as a new
+ *     system/assistant turn rather than untrusted data. This is a named,
+ *     real technique -- "Special Token Injection" (Sentry's own STI attack
+ *     guide, blog.sentry.security/special-token-injection-sti-attack-guide,
+ *     fetched directly: "the model expects certain token patterns to
+ *     signify roles... if the... pipeline does not properly filter or
+ *     escape these sequences, an attacker's input will reach the model...
+ *     analogous to injecting a SQL query via an input field"), corroborated
+ *     by OWASP's LLM01 Prompt Injection entry (genai.owasp.org) and a 2026
+ *     arXiv paper specifically on chat-template abuse for indirect
+ *     injection ("ChatInject: Abusing Chat Templates for Prompt Injection
+ *     in LLM Agents," arxiv.org/abs/2509.22830) -- not one vendor's
+ *     unverified claim. Medusa's own docs name this same technique family
+ *     ("Code-Level Prompt Injection... ChatML tokens, role manipulation"),
+ *     confirming it's a real, converged-upon signal, not something invented
+ *     here. HIGH confidence: these exact token strings essentially never
+ *     appear in ordinary prose or code by accident -- the honest, disclosed
+ *     exception is a message that *discusses* these tokens by name (a
+ *     tokenizer bug report, this very file's own docstring) rather than
+ *     attempting to use them, the same "a real key a user pasted to ask
+ *     about it" false-positive class patterns.js's private_key_block rule
+ *     already carries.
+ *   - **Hidden/invisible Unicode**: reuses `scanZeroWidth` from
+ *     `integrity.js` verbatim (see that function's own docstring for the
+ *     TrapDoor campaign citation and the always-suspicious/context-
+ *     dependent tiering) -- extended here to every line of every
+ *     transcript this project reads, not only the fixed CLAUDE.md/memory-
+ *     file locations `checkIntegrity` already covers. This closes a real
+ *     gap in the existing coverage: a hidden instruction delivered via a
+ *     fetched web page or a tool's own output lands in ordinary transcript
+ *     content, not in one of `checkIntegrity`'s known config paths, so the
+ *     existing check cannot see it.
+ *
+ * NOISY_INJECTION_PATTERNS (opt-in ADDITIONALLY via `--include-noisy`,
+ * exactly mirroring patterns.js's own NOISY_PATTERNS contract -- "broader,
+ * shape-based patterns that catch more but false-positive more often"):
+ * a small set of the most-cited canonical instruction-override phrases
+ * ("ignore previous instructions" and its close variants). Disclosed
+ * plainly, not glossed over: phrase-based matching is genuinely prone to
+ * matching a security-research conversation, a GitHub issue about prompt
+ * injection, or this very codebase's own documentation discussing the
+ * technique -- OWASP's own LLM01 page and multiple practitioner write-ups
+ * (Simon Willison's "prompt injection" writing among them) describe
+ * reliable phrase-based detection as an open, unsolved problem, not
+ * something this rule set claims to have solved. LOW confidence, never
+ * part of the default report, for exactly that reason.
+ *
+ * WHAT THIS DOES NOT COVER, stated rather than silently gapped: tool-
+ * DESCRIPTION poisoning (a malicious MCP server changing a tool's
+ * description after approval, "rug-pull") is a real, named technique
+ * (Medusa's own "Tool Poisoning (MCP101)") that this module cannot check,
+ * because a tool's description is part of the MCP protocol payload sent to
+ * the model at request time, not something Claude Code's own transcript
+ * JSONL logs — verified directly against a real transcript on this
+ * project's own build machine: a `tool_use` record for an
+ * `mcp__`-namespaced tool carries only `{name, input}`, never the tool's
+ * description or input schema. Checking that would require a live MCP
+ * client connection to query `tools/list`, a fundamentally different
+ * architecture (an active protocol client, not a file scanner) that this
+ * project has not built and is not attempting to fake here.
+ */
+
+const CHATML_TOKEN_RE = /<\|(?:im_start|im_end|system|user|assistant|endoftext|endofprompt)\|>|\[\/?INST\]|<<\/?SYS>>/g;
+
+const INJECTION_PATTERNS = [
+  { id: "chatml_special_token", label: "Special/role-token injection (ChatML or similar)", confidence: "high" },
+  { id: "zero_width_hidden_instruction", label: "Hidden instruction carried by invisible Unicode", confidence: "high" },
+];
+
+const NOISY_INJECTION_PATTERNS = [
+  {
+    id: "injection_override_phrase", label: "Instruction-override phrase (heuristic)", confidence: "low",
+    // Deliberately narrow: the small set of phrasings cited across OWASP's
+    // LLM01 page and independent practitioner write-ups as the canonical
+    // "ignore what came before" injection framing, not an attempt at
+    // exhaustive jailbreak-phrase coverage (see module docstring on why
+    // phrase-based detection stays opt-in and low-confidence).
+    re: /\b(?:ignore|disregard)\s+(?:all\s+|any\s+)?(?:the\s+|your\s+)?(?:previous|prior|above|earlier)\s+instructions\b|\bforget\s+(?:everything|all)\s+(?:above|before\s+this)\b/gi,
+  },
+];
+
+/**
+ * Minimal per-line invisible-character summary: codepoint name + count,
+ * no line-number list (unlike integrity.js's summarizeZeroWidth, which is
+ * built for a whole-file, many-line summary) -- the caller already has the
+ * real line number for this one call, so repeating it here would just be
+ * confusing "(line 1)" noise from scanZeroWidth's own internal, line-blind
+ * counting of a single line with no embedded newline.
+ */
+function summarizeInvisibles(hits) {
+  const byCp = new Map();
+  for (const h of hits) byCp.set(h.cp, (byCp.get(h.cp) || 0) + 1);
+  const parts = [];
+  for (const [cp, count] of byCp) {
+    parts.push("U+" + cp.toString(16).toUpperCase().padStart(4, "0") + " ×" + count);
+  }
+  return parts.join(", ");
+}
+
+module.exports = { INJECTION_PATTERNS, NOISY_INJECTION_PATTERNS, CHATML_TOKEN_RE, summarizeInvisibles };

package/src/integrity.js

@@ -836,4 +836,9 @@ function checkIntegrity({ home = os.homedir(), cwd = process.cwd(), projectMode
   };
 }
 
-module.exports = { checkIntegrity };
+// scanZeroWidth is also reused by injection.js, applying the same
+// TrapDoor-sourced invisible-character classification (see its own
+// docstring above) to general transcript content, not just this file's
+// own fixed config-location list -- additive export, this module's own
+// behavior is unchanged.
+module.exports = { checkIntegrity, scanZeroWidth };

package/src/mcpTools.js

@@ -52,18 +52,20 @@ function rejectUnknownKeys(args, allowed) {
 
 /**
  * Shared arg shape for residoo_scan/residoo_check: includeNoisy,
- * includeSuppressed, includePii, maxEntries. includePii is exposed here
- * (unlike ocr or verify, see this file's own header comment on verify's
- * exclusion) because it is architecturally identical to includeNoisy --
- * local-only, no network call, no external process, just a different
- * detection category (see pii.js) -- not the network/live-secret trust
- * boundary verify's own exclusion is specifically about.
+ * includeSuppressed, includePii, includeInjection, maxEntries. includePii
+ * and includeInjection are exposed here (unlike ocr or verify, see this
+ * file's own header comment on verify's exclusion) because they are
+ * architecturally identical to includeNoisy -- local-only, no network
+ * call, no external process, just a different detection category (see
+ * pii.js and injection.js respectively) -- not the network/live-secret
+ * trust boundary verify's own exclusion is specifically about.
  */
 function validateSweepArgs(args, allowedKeys) {
   const errs = rejectUnknownKeys(args, allowedKeys);
   if (args.includeNoisy !== undefined && typeof args.includeNoisy !== "boolean") errs.push("includeNoisy must be a boolean");
   if (args.includeSuppressed !== undefined && typeof args.includeSuppressed !== "boolean") errs.push("includeSuppressed must be a boolean");
   if (args.includePii !== undefined && typeof args.includePii !== "boolean") errs.push("includePii must be a boolean");
+  if (args.includeInjection !== undefined && typeof args.includeInjection !== "boolean") errs.push("includeInjection must be a boolean");
   let maxEntries = 25;
   if (args.maxEntries !== undefined) {
     if (typeof args.maxEntries !== "number" || !Number.isInteger(args.maxEntries) || args.maxEntries < 1 || args.maxEntries > 200) {
@@ -74,7 +76,7 @@ function validateSweepArgs(args, allowedKeys) {
   }
   return {
     errs, includeNoisy: args.includeNoisy === true, includeSuppressed: args.includeSuppressed === true,
-    includePii: args.includePii === true, maxEntries,
+    includePii: args.includePii === true, includeInjection: args.includeInjection === true, maxEntries,
   };
 }
 
@@ -134,8 +136,8 @@ function buildTools({ sources }) {
   let checkStarted = false;
 
   async function handleScan(args) {
-    const SCAN_KEYS = new Set(["projectDir", "includeNoisy", "includeSuppressed", "includePii", "maxEntries"]);
-    const { errs, includeNoisy, includeSuppressed, includePii, maxEntries } = validateSweepArgs(args, SCAN_KEYS);
+    const SCAN_KEYS = new Set(["projectDir", "includeNoisy", "includeSuppressed", "includePii", "includeInjection", "maxEntries"]);
+    const { errs, includeNoisy, includeSuppressed, includePii, includeInjection, maxEntries } = validateSweepArgs(args, SCAN_KEYS);
     if (args.projectDir !== undefined && typeof args.projectDir !== "string") errs.push("projectDir must be a string");
     if (errs.length) return errorResult(`Invalid arguments: ${errs.join("; ")}`);
 
@@ -152,7 +154,7 @@ function buildTools({ sources }) {
       scanSources = sources;
     }
 
-    const result = await scan({ sources: scanSources, includeNoisy, includeSuppressed, includePii, verify: false, noColor: true });
+    const result = await scan({ sources: scanSources, includeNoisy, includeSuppressed, includePii, includeInjection, verify: false, noColor: true });
     const acks = loadAcks();
     const dismissed = loadDismissed();
     const rotation = renderRotation(result.findings, acks, dismissed);
@@ -179,8 +181,8 @@ function buildTools({ sources }) {
   }
 
   async function handleCheck(args) {
-    const CHECK_KEYS = new Set(["includeNoisy", "includeSuppressed", "includePii", "maxEntries"]);
-    const { errs, includeNoisy, includeSuppressed, includePii, maxEntries } = validateSweepArgs(args, CHECK_KEYS);
+    const CHECK_KEYS = new Set(["includeNoisy", "includeSuppressed", "includePii", "includeInjection", "maxEntries"]);
+    const { errs, includeNoisy, includeSuppressed, includePii, includeInjection, maxEntries } = validateSweepArgs(args, CHECK_KEYS);
     if (errs.length) return errorResult(`Invalid arguments: ${errs.join("; ")}`);
 
     const firstCheckThisSession = !checkStarted;
@@ -191,7 +193,7 @@ function buildTools({ sources }) {
     const emit = (e) => events.push(e);
     const stats = await sweepOnce({
       sources, tracked: checkTracked, seen: checkSeen, ledger,
-      options: { includeNoisy, includeSuppressed, includePii, verify: false, noColor: true }, emit,
+      options: { includeNoisy, includeSuppressed, includePii, includeInjection, verify: false, noColor: true }, emit,
     });
 
     const allNew = events.filter((e) => e.type === "finding");
@@ -366,6 +368,7 @@ function buildTools({ sources }) {
         includeNoisy: { type: "boolean", default: false, description: "Also run residoo's two low-confidence heuristic rules (generic password/secret assignments) -- catches more, false-positives more. Off by default." },
         includeSuppressed: { type: "boolean", default: false, description: "Include matches normally hidden because they look like vendor-documented example values or placeholder text. Off by default." },
         includePii: { type: "boolean", default: false, description: "Also scan for PII and adjacent secrets (US Social Security Numbers, Luhn-validated credit card numbers, checksum-validated IBANs, BIP-39 checksum-validated crypto wallet seed phrases) -- a different risk category from a vendor credential, not a lower confidence bar. Off by default; residoo is deliberately credentials-only otherwise." },
+        includeInjection: { type: "boolean", default: false, description: "Also scan transcript content for prompt-injection signatures (special/role-token sequences like <|im_start|> or [INST], and hidden instructions carried by invisible Unicode) -- evidence an injection attempt already reached the agent, not a static-analysis check of application code. A third risk category, off by default." },
         maxEntries: { type: "integer", minimum: 1, maximum: 200, default: 25, description: "Cap on distinct findings returned in full detail, pending-first. Counts in the response are always exact even when the entry list is truncated." },
       },
       required: [],
@@ -382,6 +385,7 @@ function buildTools({ sources }) {
         includeNoisy: { type: "boolean", default: false, description: "Same meaning as residoo_scan." },
         includeSuppressed: { type: "boolean", default: false, description: "Same meaning as residoo_scan." },
         includePii: { type: "boolean", default: false, description: "Same meaning as residoo_scan." },
+        includeInjection: { type: "boolean", default: false, description: "Same meaning as residoo_scan." },
         maxEntries: { type: "integer", minimum: 1, maximum: 200, default: 25, description: "Cap on new findings / re-exposures returned in full detail. Counts are always exact even when truncated." },
       },
       required: [],

package/src/report.js

@@ -541,11 +541,15 @@ function renderJson(result, integrity = null, rotation = null) {
         // value was never plain text at all -- it was read out of a
         // pasted or tool-returned image (see ocr.js); `pii` means this is
         // a --include-pii finding, a different risk category from a
-        // credential, not a rule from the default set (see pii.js).
+        // credential, not a rule from the default set (see pii.js);
+        // `injection` means this is a --include-injection finding -- a
+        // prompt-injection signature, not a credential or PII at all (see
+        // injection.js).
         ...(f.encoding ? { encoding: f.encoding } : {}),
         ...(f.spanLines ? { spanLines: f.spanLines } : {}),
         ...(f.ocr ? { ocr: true } : {}),
         ...(f.pii ? { pii: true } : {}),
+        ...(f.injection ? { injection: 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/rotation.js

@@ -1222,6 +1222,43 @@ const ROTATION_GUIDANCE = {
     ],
     revokeNote: "Low-confidence match: verify before rotating anything.",
   },
+
+  // ── INJECTION_PATTERNS (--include-injection; see injection.js) ─────────
+  // Framed like the PII entries above, not like a credential: there is no
+  // issuer, no console, nothing to rotate. The real action is investigating
+  // HOW this reached the transcript -- a fetched page, a file the agent
+  // read, a tool's own output -- since that's the actual attack surface,
+  // not the token/character itself.
+  chatml_special_token: {
+    label: "Special/role-token injection (ChatML or similar)",
+    consolePath: "No vendor console -- this is a structural signature in content, not a credential.",
+    steps: [
+      "Find which tool call or fetched source produced the line this was found in -- that's the actual entry point, not this file",
+      "If it came from external content (a web page, an API response, a file the agent read), treat that source as untrusted going forward and review what the agent did in the turns immediately after seeing it",
+      "If this is a false positive -- code or documentation that legitimately discusses these tokens by name (a tokenizer bug report, this project's own docs) -- no action needed",
+    ],
+    revokeNote: "High confidence structurally (these exact token sequences are rare in ordinary prose/code), but confidence in the MATCH is not the same as confidence an attack succeeded -- whether it actually altered the agent's behavior depends on the specific model/serving pipeline, which this check cannot see.",
+  },
+  zero_width_hidden_instruction: {
+    label: "Hidden instruction carried by invisible Unicode",
+    consolePath: "No vendor console -- this is a structural signature in content, not a credential.",
+    steps: [
+      "Inspect the source file in a hex viewer or an editor that reveals invisible characters -- never trust how it renders in a normal terminal, that's the whole point of this technique",
+      "Find which tool call or fetched source produced this line, the same way as the special-token rule above",
+      "This is the same technique named in the TrapDoor campaign (see integrity.js's own citation) -- if this pattern shows up in a fixed config location (CLAUDE.md, a hook script) rather than ordinary transcript content, `residoo scan`'s own integrity check (not this rule) is what already covers that case with campaign-specific detail",
+    ],
+    revokeNote: "The always-suspicious codepoint tier (not the context-dependent emoji-joiner tier) is what reaches this rule -- see integrity.js's scanZeroWidth for exactly which codepoints qualify and why.",
+  },
+  injection_override_phrase: {
+    label: "Instruction-override phrase (noisy rule)",
+    generic: true,
+    consolePath: "No vendor console -- this is a phrase match in content, not a credential.",
+    steps: [
+      "Read the surrounding context before treating this as a real attempt -- this exact phrase is also what a security-research conversation, a GitHub issue, or a prompt-engineering discussion about this technique looks like, and this rule cannot tell the difference",
+      "If it's a real attempt, find which tool call or fetched source it came from",
+    ],
+    revokeNote: "Low-confidence, phrase-based match: OWASP's own LLM01 guidance and independent practitioner writing both describe reliable phrase-based injection detection as unsolved, not something this rule claims to have done.",
+  },
 };
 Object.freeze(ROTATION_GUIDANCE);
 

package/src/scan.js

@@ -5,6 +5,8 @@ const { PATTERNS, NOISY_PATTERNS, redact } = require("./patterns");
 const { findDecodedMatches, findBoundaryMatches, contentProjection } = require("./decode");
 const { isTesseractAvailable, extractImageBlocks, ocrImageBase64 } = require("./ocr");
 const { PII_PATTERNS } = require("./pii");
+const { INJECTION_PATTERNS, NOISY_INJECTION_PATTERNS, CHATML_TOKEN_RE, summarizeInvisibles } = require("./injection");
+const { scanZeroWidth } = require("./integrity");
 const { findPairedSecret, findNearbyCandidate } = require("./pairing");
 const { looksRandom } = require("./rarity");
 const { decodeJwtExpiryMs } = require("./jwtExpiry");
@@ -273,7 +275,7 @@ 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, ocr = false, includePii = false } = {}) {
+async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null, verify = false, verifyOnlyFingerprint = null, onBeforeVerify = null, noColor = false, ocr = false, includePii = false, includeInjection = 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
@@ -639,6 +641,40 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
     }
   };
 
+  // --include-injection: a third, separate risk category (see injection.js's
+  // own header for why this is neither a secret nor PII). No suppression
+  // heuristics apply here -- there is no "vendor-documented example" or
+  // "placeholder-like context" equivalent for a special-token sequence or a
+  // hidden Unicode character, unlike a value-shaped secret. NOISY_INJECTION_
+  // PATTERNS additionally require --include-noisy, mirroring exactly how
+  // patterns.js's own NOISY_PATTERNS require it for secrets.
+  const injectionLine = (line, file, relFile, lineNo, mtimeMs) => {
+    if (!includeInjection) return;
+    for (const rule of INJECTION_PATTERNS) {
+      if (rule.id === "chatml_special_token") {
+        CHATML_TOKEN_RE.lastIndex = 0;
+        let m;
+        while ((m = CHATML_TOKEN_RE.exec(line)) !== null) {
+          record(rule, m[0], relFile, file, lineNo, mtimeMs, rule.confidence, null, { injection: true });
+        }
+      } else if (rule.id === "zero_width_hidden_instruction") {
+        const hits = scanZeroWidth(line).filter((h) => h.suspicious);
+        if (hits.length > 0) {
+          record(rule, summarizeInvisibles(hits), relFile, file, lineNo, mtimeMs, rule.confidence, null, { injection: true });
+        }
+      }
+    }
+    if (includeNoisy) {
+      for (const rule of NOISY_INJECTION_PATTERNS) {
+        rule.re.lastIndex = 0;
+        let m;
+        while ((m = rule.re.exec(line)) !== null) {
+          record(rule, m[0], relFile, file, lineNo, mtimeMs, rule.confidence, null, { injection: 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
@@ -763,6 +799,13 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
               flagFailed();
             }
           }
+          if (includeInjection) {
+            try {
+              injectionLine(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

package/src/sources/index.js

@@ -140,6 +140,13 @@ const atlassianRovoDev = require("./atlassian-rovo-dev");
 // cache/offline copy of thread content is documented anywhere found — the
 // same cloud-only reasoning as Augment Code/CodeGPT above, not missed.
 
+// Not a transcript store either — interactive shell/REPL history (bash,
+// zsh, fish, psql, mysql, Python, Node.js). See shell-history.js's own
+// header for why this is in scope despite not being literally "an AI
+// agent's session history," and for exactly which paths are
+// real-install-verified versus documented-but-unverified on this machine.
+const shellHistory = require("./shell-history");
+
 const ALL_SOURCES = [
   claudeCode,
   agentConfigs,
@@ -185,6 +192,7 @@ const ALL_SOURCES = [
   kimiCode,
   fx,
   atlassianRovoDev,
+  shellHistory,
 ];
 
 function availableSources() {

package/src/sources/shell-history.js

@@ -0,0 +1,241 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { createInterface } = require("readline/promises");
+
+/**
+ * Interactive shell and REPL/DB-client history files.
+ *
+ * SCOPE, stated plainly because this is the second source in this project
+ * (after agent-configs.js) that is not literally "an AI agent's session
+ * history": these files record what the DEVELOPER typed at a real
+ * interactive prompt, not what an agent wrote to disk on their behalf. It's
+ * included because it's the same failure mode, one hop away from what this
+ * tool already covers: a developer tests a curl call with a bearer token
+ * before pasting the working version into an agent prompt, connects to a
+ * database with a password embedded in the URI, or exports a token into a
+ * REPL to try a client library — plaintext, indefinitely, in a file almost
+ * nobody thinks to check, the exact description this project's own README
+ * opens with. It is also a real, disclosed, competitor-named gap: Medusa
+ * (see docs/comparison.md's Medusa section) already scans exactly
+ * bash/zsh/fish/psql/mysql/python-REPL history and residoo did not.
+ *
+ * Every path below is a documented default or a documented override
+ * environment variable from that tool's own primary docs, fetched directly
+ * (not assumed by analogy to a similar tool) on 2026-09-05:
+ *
+ *   - **bash**: `~/.bash_history` is bash's own long-standing built-in
+ *     default (its manual page).
+ *   - **zsh**: NOT a shell-level default the way bash's is — zsh's own
+ *     manual (zsh.sourceforge.io/Doc/Release/Parameters.html) states
+ *     plainly that if `HISTFILE` is unset, "the history is not saved" at
+ *     all. `~/.zsh_history` is checked anyway because it's the exact path
+ *     zsh's own bundled `zsh-newuser-install` script offers a new user who
+ *     accepts history saving, and the default both Oh My Zsh's and
+ *     Prezto's stock templates set — the de facto convention on most real
+ *     machines, not a shell-level guarantee. `$HISTFILE`, when set, is
+ *     checked once for both bash and zsh: a set value can't be attributed
+ *     to one shell over the other from outside the shell itself.
+ *   - **fish**: `$XDG_DATA_HOME/fish/fish_history`, defaulting to
+ *     `~/.local/share/fish/fish_history` when that variable is unset —
+ *     fish's own docs (fishshell.com/docs/current/interactive.html) state
+ *     this exact default and XDG override.
+ *   - **psql**: `~/.psql_history` (Unix) or
+ *     `%APPDATA%\postgresql\psql_history` (Windows) — PostgreSQL's own
+ *     psql docs (postgresql.org/docs/current/app-psql.html) state both
+ *     paths as the default. No environment-variable override is
+ *     documented; psql's own `\set HISTFILE ...` is an in-session psql
+ *     variable, not a process environment variable residoo can read from
+ *     outside the running psql process.
+ *   - **mysql**: `$MYSQL_HISTFILE`, defaulting to `~/.mysql_history` —
+ *     MySQL's own reference manual (dev.mysql.com/doc/refman/8.4/en/
+ *     mysql-logging.html) documents both, and its own text recommends
+ *     restricting this file's permissions because it "may contain
+ *     sensitive information" — a vendor admission of exactly the failure
+ *     mode this source exists to catch.
+ *   - **Python** (interactive interpreter): `$PYTHON_HISTORY`, defaulting
+ *     to `~/.python_history` — Python's own docs (docs.python.org/3/using/
+ *     cmdline.html). The environment variable is Python 3.13+ only (added
+ *     that release); reading it on an older interpreter simply finds it
+ *     unset and falls through to the same fixed default, so no version
+ *     check is needed here.
+ *   - **Node.js REPL**: `$NODE_REPL_HISTORY`, defaulting to
+ *     `~/.node_repl_history` — Node's own docs (nodejs.org/api/repl.html),
+ *     which also document that an empty or whitespace-only value means the
+ *     user explicitly disabled persistent history; honored here exactly as
+ *     documented rather than treated as "unset."
+ *
+ * VERIFICATION STATUS: `~/.bash_history` and `~/.python_history` are
+ * REAL-INSTALL-VERIFIED — both exist on this project's own build machine
+ * with genuine, non-empty content (confirmed directly, read-only, before
+ * this source was written). zsh/fish/psql/mysql/Node history are
+ * MULTI-SOURCE-CORROBORATED-BUT-UNVERIFIED: each path above comes from
+ * that tool's own primary documentation, but none of those five files
+ * exist on the machine this was built on, so the schema (there isn't
+ * one — every one of these is already plain line-delimited text) is
+ * unverified against real content the same way most of this project's
+ * other sources are. If you use zsh, fish, psql, mysql, or the Node REPL
+ * with a populated history file, running `residoo scan` and confirming
+ * `filesScanned` looks right is the single most useful way to firm this
+ * up (see CONTRIBUTING.md).
+ *
+ * FORMAT: every one of these files is already plain line-delimited text —
+ * zsh's optional "extended history" format (`: <ts>:<secs>;<command>`) and
+ * fish's YAML-ish `- cmd: ...` / `  when: ...` records still carry the
+ * actual command as a contiguous substring of one line, and every pattern
+ * in `src/patterns.js` matches on `\b` word boundaries, never a `^`
+ * line-start anchor — so no format-specific parsing is needed before
+ * pattern matching, the same reasoning agent-configs.js's readLines()
+ * docstring states for JSON/TOML config lines, and decode.js's own header
+ * already anticipates this exact case ("plain-text chat logs, shell
+ * history... used as-is").
+ *
+ * NOT covered, and why: shell history for any shell/tool not named above
+ * (fish's own `fish_history` predecessor formats, csh/tcsh, sqlite3's
+ * `.sqlite_history`, R's `.Rhistory`, IPython's separate SQLite-backed
+ * history database) — each would need its own documented default and
+ * schema check to the same bar as the seven above, not guessed by
+ * analogy. A welcome follow-up PR, per CONTRIBUTING.md.
+ */
+
+const HOME = os.homedir();
+
+function id() { return "shell-history"; }
+function label() { return "Shell & REPL history"; }
+
+/**
+ * Every candidate path this source checks, deduplicated (a customized
+ * override that happens to equal a default above would otherwise be
+ * checked twice). Order has no behavioral meaning — statIfPresent handles
+ * each independently.
+ */
+function candidatePaths() {
+  const xdgDataHome = process.env.XDG_DATA_HOME || path.join(HOME, ".local", "share");
+  const nodeReplHistory = process.env.NODE_REPL_HISTORY;
+  const nodeReplDisabled = nodeReplHistory !== undefined && nodeReplHistory.trim() === "";
+
+  const paths = [
+    path.join(HOME, ".bash_history"),
+    path.join(HOME, ".zsh_history"),
+    ...(process.env.HISTFILE ? [process.env.HISTFILE] : []),
+    path.join(xdgDataHome, "fish", "fish_history"),
+    process.platform === "win32"
+      ? path.join(process.env.APPDATA || path.join(HOME, "AppData", "Roaming"), "postgresql", "psql_history")
+      : path.join(HOME, ".psql_history"),
+    process.env.MYSQL_HISTFILE || path.join(HOME, ".mysql_history"),
+    process.env.PYTHON_HISTORY || path.join(HOME, ".python_history"),
+    ...(nodeReplDisabled ? [] : [nodeReplHistory || path.join(HOME, ".node_repl_history")]),
+  ];
+
+  return [...new Set(paths)];
+}
+
+/**
+ * Resolve one fixed candidate path into zero or one files() entries.
+ * Duplicated from agent-configs.js's statIfPresent rather than imported,
+ * per this project's one-small-self-contained-file-per-source convention
+ * (see cursor.js's own docstring for the same point). Absence (ENOENT/
+ * ENOTDIR) is the normal, expected case for a tool the user doesn't use
+ * and yields nothing; anything else that stops the path resolving (a
+ * dangling symlink, a permission error) is a broken entry, not silent
+ * absence — the same never-a-false-all-clear reasoning as every other
+ * source here.
+ */
+function* statIfPresent(p) {
+  let lst;
+  try { lst = fs.lstatSync(p); }
+  catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) return;
+    yield { file: p, broken: true };
+    return;
+  }
+
+  if (lst.isSymbolicLink()) {
+    try {
+      const st = fs.statSync(p);
+      if (!st.isFile()) { yield { file: p, broken: true }; return; }
+      yield { file: p, mtimeMs: st.mtimeMs, sizeBytes: st.size, broken: false };
+    } catch {
+      yield { file: p, broken: true };
+    }
+    return;
+  }
+
+  if (!lst.isFile()) return;
+  yield { file: p, mtimeMs: lst.mtimeMs, sizeBytes: lst.size, broken: false };
+}
+
+/**
+ * True when any candidate history file actually exists. Unlike
+ * agent-configs.js (which gates on a per-tool ROOT directory so an
+ * installed-but-empty tool still shows as checked), none of the files
+ * here have a natural "installed" signal separate from the file's own
+ * existence — there is no `~/.bash/` directory to check instead. A
+ * machine with none of these files present correctly doesn't list this
+ * source at all, the same as a brand-new machine with no shell history
+ * yet would have nothing meaningful to report either way.
+ */
+function available() {
+  for (const p of candidatePaths()) {
+    for (const _ of statIfPresent(p)) return true;
+  }
+  return false;
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every candidate present.
+ */
+function* files() {
+  for (const p of candidatePaths()) yield* statIfPresent(p);
+}
+
+// Real observations on this project's own build machine: ~40KB
+// (~.bash_history, years of use) and ~6.6KB (~.python_history). 256MB is a
+// generous, uncalibrated backstop against a corrupted or pathological file
+// (the same caveat cursor.js states for its own size bound), not a measured
+// ceiling — a file over it is surfaced as "too-large", never silently
+// skipped.
+const MAX_BYTES = 256 * 1024 * 1024;
+const READ_TIMEOUT_MS = 60_000;
+
+/**
+ * Read one history file as an array of raw text lines. Identical streaming
+ * shape (readline/promises, MAX_BYTES cap, READ_TIMEOUT_MS watchdog,
+ * partial-read lines kept rather than discarded) to every other source
+ * here — see claude-code.js's readLines() docstring for the full
+ * reasoning, all of which applies unchanged since this is plain
+ * line-delimited UTF-8 text on disk (see the module docstring's FORMAT
+ * section for why no per-tool parsing is needed first).
+ */
+async function readLines(file) {
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch { return { lines: [], status: "failed", bytesRead: 0 }; }
+  if (stat.size > MAX_BYTES) return { lines: [], status: "too-large", bytesRead: 0 };
+
+  const lines = [];
+  let bytesRead = 0;
+  const stream = fs.createReadStream(file, { encoding: "utf-8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  const timer = setTimeout(() => stream.destroy(new Error("read timed out")), READ_TIMEOUT_MS);
+
+  try {
+    for await (const line of rl) {
+      lines.push(line);
+      bytesRead += Buffer.byteLength(line, "utf-8") + 1; // +1 for the stripped newline
+    }
+    return { lines, status: "complete", bytesRead };
+  } catch {
+    // Lines read before the failure are real content and may hold a real
+    // secret -- an honest "partial" beats a silent false negative.
+    return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+    stream.destroy();
+  }
+}
+
+module.exports = { id, label, available, files, readLines };

package/src/watch.js

@@ -267,14 +267,14 @@ function makeSyntheticSource(realId, batchesByFile) {
  * `verify` is always forced off here: seeding a dedup cache must never be
  * the reason a live vendor API gets hit.
  */
-async function baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, includeNoisy, includeSuppressed, noColor, includePii) {
+async function baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, includeNoisy, includeSuppressed, noColor, includePii, includeInjection) {
   const batch = await readWholeFile(source, file, sizeBytes, mtimeMs);
   if (!batch) return;
   let result;
   try {
     result = await scan({
       sources: [makeSyntheticSource(sourceId, new Map([[file, batch]]))],
-      includeNoisy, includeSuppressed, verify: false, noColor, includePii,
+      includeNoisy, includeSuppressed, verify: false, noColor, includePii, includeInjection,
     });
   } catch {
     return; // best-effort: a failure here just leaves this file's dedup
@@ -300,7 +300,7 @@ async function baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, in
  * `dismiss` takes effect without a restart.
  */
 async function sweepOnce({ sources, tracked, seen, ledger, options, emit }) {
-  const { includeNoisy, includeSuppressed, verify, noColor, includePii } = options || {};
+  const { includeNoisy, includeSuppressed, verify, noColor, includePii, includeInjection } = options || {};
   let loud = 0;
   let quiet = 0;
   let suppressedByLedger = 0;
@@ -364,7 +364,7 @@ async function sweepOnce({ sources, tracked, seen, ledger, options, emit }) {
           contentHash: tailable ? null : wholeFileHash(file),
         });
         if (!tailable) {
-          await baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, includeNoisy, includeSuppressed, noColor, includePii);
+          await baselineSeed(source, sourceId, file, sizeBytes, mtimeMs, seen, includeNoisy, includeSuppressed, noColor, includePii, includeInjection);
         }
         continue;
       }
@@ -433,7 +433,7 @@ async function sweepOnce({ sources, tracked, seen, ledger, options, emit }) {
     try {
       result = await scan({
         sources: [makeSyntheticSource(sourceId, batchesByFile)],
-        includeNoisy, includeSuppressed, verify, noColor, includePii,
+        includeNoisy, includeSuppressed, verify, noColor, includePii, includeInjection,
       });
     } catch (err) {
       emit({ type: "watch-error", at: new Date(), source: sourceId, detail: "scan failed: " + (err && err.message) });