residoo 0.1.0 → 0.3.0

package/src/patterns.js

@@ -28,12 +28,13 @@ const PATTERNS = [
     re: /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/g },
   { id: "stripe_key", label: "Stripe API key", confidence: "high",
     re: /\b(sk|rk)_live_[A-Za-z0-9]{20,}\b/g },
-  // The negative lookahead keeps this rule and anthropic_key mutually exclusive —
-  // without it, "sk-ant-..." matches BOTH patterns and gets reported twice under
-  // two different (one wrong) provider labels. Verified: both regexes independently
-  // matched a synthetic sk-ant- key before this fix.
+  // The negative lookahead keeps this rule mutually exclusive with anthropic_key
+  // and openrouter_key below — without it, "sk-ant-..." or "sk-or-v1-..." match
+  // BOTH this pattern and the more specific one, and get reported twice under
+  // two different (one wrong) provider labels. Verified: all three regexes
+  // independently matched their overlapping synthetic keys before this fix.
   { id: "openai_key", label: "OpenAI API key", confidence: "high",
-    re: /\bsk-(?!ant-)(proj-)?[A-Za-z0-9_-]{20,}\b/g },
+    re: /\bsk-(?!ant-|or-)(proj-)?[A-Za-z0-9_-]{20,}\b/g },
   { id: "anthropic_key", label: "Anthropic API key", confidence: "high",
     re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
   { id: "google_api_key", label: "Google / Firebase API key", confidence: "high",
@@ -54,6 +55,78 @@ const PATTERNS = [
     re: /"refresh_token"\s*:\s*"[^"\s]{20,}"/gi },
   { id: "access_token_field", label: "access_token field", confidence: "medium",
     re: /"access_token"\s*:\s*"[^"\s]{20,}"/gi },
+
+  // ── AI / LLM providers (added: competitive gap-close, see project history) ─
+  // Every regex body below was checked against a production, field-tested
+  // detector — trufflehog's (github.com/trufflesecurity/trufflehog,
+  // pkg/detectors/<vendor>) — not guessed from a blog post, as of 2026-09.
+  // Cohere, Mistral, Together AI, Fireworks and DeepSeek were researched too
+  // and deliberately left out: none has a trufflehog detector, official docs
+  // describe them as unprefixed/opaque tokens, and DeepSeek's "sk-" prefix is
+  // provably indistinguishable from OpenAI's (trufflehog's own DeepSeek
+  // detector only fires with a nearby "deepseek" keyword as extra context,
+  // which this flat-regex model doesn't have) — exactly the shaky-prefix case
+  // this file's own header comment says to leave out rather than force.
+  { id: "groq_key", label: "Groq API key", confidence: "high",
+    re: /\bgsk_[a-zA-Z0-9]{52}\b/g },
+  { id: "xai_key", label: "xAI (Grok) API key", confidence: "high",
+    re: /\bxai-[0-9a-zA-Z_]{80}\b/g },
+  { id: "openrouter_key", label: "OpenRouter API key", confidence: "high",
+    re: /\bsk-or-v1-[0-9a-f]{64}\b/g },
+  { id: "huggingface_token", label: "Hugging Face access token", confidence: "high",
+    re: /\b(?:hf_|api_org_)[a-zA-Z0-9]{34}\b/g },
+  { id: "pinecone_key", label: "Pinecone API key", confidence: "high",
+    re: /\bpcsk_[A-Za-z0-9]{5,6}_[A-Za-z0-9]{63}\b/g },
+  // No trufflehog detector exists for this one, so it leans on a second,
+  // independent signal instead: Perplexity's own product is literally named
+  // "pplx-api" (see their "Introducing pplx-api" launch post), and every
+  // integration doc that shows a real key (liteLLM, apideck, etc.) agrees on
+  // "pplx-" + a >=40-char body — consistent across independent sources even
+  // without one canonical spec page.
+  { id: "perplexity_key", label: "Perplexity API key", confidence: "high",
+    re: /\bpplx-[A-Za-z0-9]{40,}\b/g },
+  { id: "replicate_token", label: "Replicate API token", confidence: "high",
+    re: /\br8_[0-9A-Za-z_-]{37}\b/g },
+
+  // ── Cloud / infra ──────────────────────────────────────────────────────
+  { id: "digitalocean_token", label: "DigitalOcean access token", confidence: "high",
+    re: /\b(?:dop|doo|dor)_v1_[a-f0-9]{64}\b/g },
+  { id: "supabase_token", label: "Supabase personal access token", confidence: "high",
+    re: /\bsbp_[a-z0-9]{40}\b/g },
+  { id: "vault_token", label: "HashiCorp Vault service token", confidence: "high",
+    // Vault 1.10+ format only (hvs.<90-120 chars>). The pre-1.10 legacy
+    // format is a bare "s." + 18-40 chars — "s." is nowhere near specific
+    // enough to be a vendor prefix, so that older shape is deliberately left
+    // out rather than turned into a noisy 2-character trigger.
+    re: /\bhvs\.[A-Za-z0-9_-]{90,120}\b/g },
+  { id: "onepassword_service_token", label: "1Password service account token", confidence: "high",
+    // Confirmed against 1Password's own developer docs (developer.1password.com
+    // -> 1password.dev/service-accounts/security): the token is "ops_" plus a
+    // base64-encoded JWT, so it always continues "eyJ" (base64 of `{"`).
+    re: /\bops_eyJ[A-Za-z0-9+/=_-]{40,}\b/g },
+
+  // ── Comms / SaaS ───────────────────────────────────────────────────────
+  { id: "discord_webhook", label: "Discord webhook URL", confidence: "high",
+    re: /\bhttps:\/\/discord\.com\/api\/webhooks\/[0-9]{18,19}\/[0-9a-zA-Z_-]{68}\b/g },
+  { id: "telegram_bot_token", label: "Telegram bot token", confidence: "high",
+    re: /\b[0-9]{8,10}:[a-zA-Z0-9_-]{35}\b/g },
+  { id: "mailgun_key", label: "Mailgun API key", confidence: "high",
+    re: /\bkey-[a-z0-9]{32}\b/g },
+  // Notion's own docs explicitly warn against regex-matching its tokens,
+  // since the format has changed before and may again — noted, not ignored,
+  // and worth restating here rather than treating this as equally solid as
+  // the others. secret_ (legacy, exactly 43 chars) is trufflehog-verified;
+  // ntn_ (current format since 2024-09-25) is vendor-confirmed as a prefix
+  // but Notion has not published an exact body length for it, so its bound
+  // below is a floor, not a verified exact count.
+  { id: "notion_token", label: "Notion integration token", confidence: "high",
+    re: /\b(?:secret_[A-Za-z0-9]{43}|ntn_[A-Za-z0-9]{20,})\b/g },
+  { id: "linear_key", label: "Linear API key", confidence: "high",
+    re: /\blin_api_[0-9A-Za-z]{40}\b/g },
+  { id: "sentry_token", label: "Sentry auth token", confidence: "high",
+    // Covers both current Sentry token shapes: org-scoped (sntrys_, base64
+    // JWT-like body) and user-scoped (sntryu_, hex body).
+    re: /\b(?:sntrys_eyJ[A-Za-z0-9+/=_]{100,}|sntryu_[a-f0-9]{64})\b/g },
 ];
 
 /**

package/src/report.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const path = require("path");
+const { fingerprintFinding, ROTATION_ORDER_ADVISORY } = require("./rotation");
 
 // Minimal raw ANSI — no chalk, no deps. A security tool asking you to trust
 // a pile of third-party packages before it's even scanned anything is a bad
@@ -28,13 +29,144 @@ function ageDays(mtimeMs) {
   return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86400000));
 }
 
-function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount = 0, distinctCounts = {}, unreadableFiles = [] }, { noColor = false } = {}) {
+// File NAMES are attacker-controllable text headed for a terminal: in
+// --project mode a hostile checkout chooses its own filenames, and a name
+// carrying raw ESC bytes could clear the screen or overwrite the findings
+// block with a spoofed all-clear. Same discipline integrity.js applies to
+// its displayed paths (its stripControlChars/escapeInvisibles pair, mirrored
+// here rather than exported: patterns.js and integrity.js each keep their own
+// copy for the same shared-file reason): control bytes stripped, invisible
+// code points made visible so a zero-width name cannot render as nothing.
+const INVISIBLES_RE = /[\u200b\u200c\u200d\u2060\ufeff\u{e0000}-\u{e007f}]/gu;
+function safeBasename(file) {
+  return path.basename(String(file))
+    .replace(/[\x00-\x1f\x7f]/g, "")
+    .replace(INVISIBLES_RE, (ch) => "\\u{" + ch.codePointAt(0).toString(16).toUpperCase() + "}");
+}
+
+// Plain greedy word wrap for the one long-paragraph string this report prints
+// (the rotation ordering advisory). Continuation lines get the indent.
+function wrapText(s, width, indent) {
+  const words = String(s).split(/\s+/);
+  const lines = [];
+  let cur = "";
+  for (const w of words) {
+    if (cur && cur.length + 1 + w.length > width) { lines.push(cur); cur = w; }
+    else cur = cur ? cur + " " + w : w;
+  }
+  if (cur) lines.push(cur);
+  return lines.map((l, i) => (i === 0 ? l : indent + l));
+}
+
+/**
+ * The rotation section: what to DO about each distinct finding, fed by
+ * src/rotation.js's renderRotation() (pure data) and printed in the same
+ * visual language as the rest of the report. Compact on purpose: one status
+ * line plus one guidance pointer per distinct value; the full runbook lives
+ * behind "residoo explain <rule-id>" so the report stays scannable. The
+ * fingerprint is printed in full because it is the exact argument
+ * "residoo ack" takes; a truncated one would be prettier and useless.
+ *
+ * `showAdvisory` is set by render() only when integrity WARNINGS and secret
+ * findings coexist in one run: that is the ChainDrop scenario where rotating
+ * first can itself trigger the planted payload, so remediation order becomes
+ * safety-critical and the report says so before listing anything to rotate.
+ */
+function renderRotationSection(rotation, { noColor = false, showAdvisory = false } = {}) {
+  const paint = makePaint(noColor);
+  const lines = [];
+  const push = (s = "") => lines.push(s);
+  const { counts, entries } = rotation;
+  if (counts.distinct === 0) return "";
+
+  // "rotations", not "distinct values": the headline's distinct count dedupes
+  // raw values, while these entries dedupe fingerprints (which include the
+  // basename, so one value in two differently-named files is two rotations to
+  // track). Two counts under one word would read as a contradiction.
+  push(paint(c.bold, "Rotation:") +
+    ` ${counts.pending} of ${counts.distinct} rotation${counts.distinct === 1 ? "" : "s"} pending` +
+    (counts.acked > 0 ? ` (${counts.acked} acknowledged)` : ""));
+  if (showAdvisory) {
+    const wrapped = wrapText(ROTATION_ORDER_ADVISORY, 72, "     ");
+    push(`  ${paint(c.red + c.bold, "⚠  " + wrapped[0])}`);
+    for (const l of wrapped.slice(1)) push(`  ${paint(c.red, l)}`);
+  }
+  // Same anti-flood policy as the by-file table: a report is a summary, not a
+  // dump. Everything elided here is in --json in full.
+  const MAX_SHOWN = 12;
+  const shown = entries.slice(0, MAX_SHOWN);
+  for (const e of shown) {
+    const tag = e.status === "pending" ? paint(c.yellow, "pending") : paint(c.green, "acked  ");
+    push(`  ${tag}  ${e.fingerprint}  ${e.label}`);
+    if (e.status === "acked") {
+      push(paint(c.dim, `           acknowledged ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""}`));
+    } else {
+      const g = e.guidance;
+      const where = g.rotateUrl ? `rotate: ${g.rotateUrl}` : `where: ${g.consolePath}`;
+      push(paint(c.dim, `           ${where}`));
+    }
+  }
+  if (entries.length > shown.length) {
+    push(paint(c.dim, `  … and ${entries.length - shown.length} more; see --json for the full list`));
+  }
+  push(paint(c.dim, `  Full runbook: residoo explain <rule-id> · mark one rotated: residoo ack <fingerprint>`));
+  return lines.join("\n");
+}
+
+/**
+ * The integrity section — findings from src/integrity.js, rendered in the
+ * same visual language as the scan report. Severity drives everything:
+ * "warn" (a verified campaign signature, or a location that exists but
+ * couldn't be verified) paints red and counts toward --fail-on-find; "info"
+ * (a hook/rules file that runs automatically and merely deserves the user's
+ * confirmation) stays dim. Every finding is printed — integrity findings are
+ * few by construction (checkIntegrity caps its own noise), so unlike scan
+ * findings they are never truncated to a top-N.
+ *
+ * Exported separately because cli.js's "no transcript sources on this
+ * machine" path still runs the integrity checks — a planted repo-level hook
+ * is exactly as dangerous on a machine with no transcripts to scan.
+ */
+function renderIntegrity(integrity, { noColor = false } = {}) {
+  const paint = makePaint(noColor);
+  const lines = [];
+  const push = (s = "") => lines.push(s);
+
+  const warns = integrity.findings.filter((f) => f.severity === "warn");
+  const infos = integrity.findings.filter((f) => f.severity === "info");
+  const checked = integrity.filesChecked.filter((f) => f.status === "checked").length;
+  const absent = integrity.filesChecked.filter((f) => f.status === "absent").length;
+
+  if (integrity.findings.length === 0) {
+    push(paint(c.green + c.bold, "✓ Integrity: no planted hooks, droppers, or hidden instructions detected") +
+      `: ${checked} location${checked === 1 ? "" : "s"} checked, ${absent} absent.`);
+  } else if (warns.length > 0) {
+    push(paint(c.red + c.bold, `⚠  Integrity: ${warns.length} warning${warns.length === 1 ? "" : "s"}`) +
+      (infos.length > 0 ? ` + ${infos.length} item${infos.length === 1 ? "" : "s"} to review` : "") +
+      paint(c.dim, ` · ${checked} location${checked === 1 ? "" : "s"} checked`));
+  } else {
+    push(paint(c.bold, `Integrity: ${infos.length} item${infos.length === 1 ? "" : "s"} to review`) +
+      paint(c.dim, ` (nothing matching a known campaign signature) · ${checked} location${checked === 1 ? "" : "s"} checked`));
+  }
+  for (const f of warns) {
+    push(`  ${paint(c.red, "warn")}  ${paint(c.cyan, f.file)}`);
+    push(`        ${f.detail}`);
+  }
+  for (const f of infos) {
+    push(`  ${paint(c.dim, "info")}  ${paint(c.cyan, f.file)}`);
+    push(paint(c.dim, `        ${f.detail}`));
+  }
+  push(paint(c.dim, `   ${integrity.scopeNote}`));
+  return lines.join("\n");
+}
+
+function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount = 0, distinctCounts = {}, unreadableFiles = [] }, { noColor = false, integrity = null, rotation = null } = {}) {
   const paint = makePaint(noColor);
   const lines = [];
   const push = (s = "") => lines.push(s);
 
   const suppressedNote = suppressedCount > 0
-    ? paint(c.dim, ` (${suppressedCount} more matched but looked like placeholder/example text — see --include-suppressed)`)
+    ? paint(c.dim, ` (${suppressedCount} more matched but looked like placeholder/example text; see --include-suppressed)`)
     : "";
   // Surfaced, not silent: a file that couldn't be (fully) read was not fully
   // scanned, and a report must not read as "checked and found nothing" for
@@ -43,14 +175,18 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
   // project-name-derived directory slug, which is exactly the kind of thing
   // every other line in this report is careful to redact down from.
   const unreadableNote = unreadableFiles.length > 0
-    ? paint(c.yellow, `⚠  ${unreadableFiles.length} file(s) not fully scanned — see --json for which and why.`)
+    ? paint(c.yellow, `⚠  ${unreadableFiles.length} file(s) not fully scanned. See --json for which and why.`)
     : null;
 
   if (findings.length === 0) {
     push(paint(c.green + c.bold, "✓ No exposed secrets found") +
-      ` — ${filesScanned} file${filesScanned === 1 ? "" : "s"} scanned across ${sourcesScanned.join(", ") || "no sources"}.` +
+      `: ${filesScanned} file${filesScanned === 1 ? "" : "s"} scanned across ${sourcesScanned.join(", ") || "no sources"}.` +
       suppressedNote);
     if (unreadableNote) push(unreadableNote);
+    if (integrity) {
+      push();
+      push(renderIntegrity(integrity, { noColor }));
+    }
     return lines.join("\n");
   }
 
@@ -87,18 +223,37 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
   push(paint(c.bold, "By file:"));
   const fileRows = [...byFile.entries()].sort((a, b) => b[1] - a[1]).slice(0, 15);
   for (const [file, count] of fileRows) {
-    push(`  ${String(count).padStart(4)}  ${paint(c.cyan, path.basename(file))}`);
+    push(`  ${String(count).padStart(4)}  ${paint(c.cyan, safeBasename(file))}`);
   }
   if (byFile.size > fileRows.length) push(paint(c.dim, `  … and ${byFile.size - fileRows.length} more file(s)`));
 
+  if (rotation && rotation.counts.distinct > 0) {
+    const integrityWarns = integrity ? integrity.findings.filter((f) => f.severity === "warn").length : 0;
+    push();
+    push(renderRotationSection(rotation, { noColor, showAdvisory: integrityWarns > 0 }));
+  }
+
+  if (integrity) {
+    push();
+    push(renderIntegrity(integrity, { noColor }));
+  }
+
   push();
-  push(paint(c.dim, "Values are redacted in this report — first/last 4 characters only. Nothing scanned"));
+  push(paint(c.dim, "Values are redacted in this report (first/last 4 characters only). Nothing scanned"));
   push(paint(c.dim, "here left your machine; residoo makes no network calls. Run with --json for full detail."));
 
   return lines.join("\n");
 }
 
-function renderJson(result) {
+// `integrity` is the checkIntegrity() result, or null when --no-integrity
+// skipped it — the key is always present so a --json consumer can tell
+// "checked, clean" apart from "never checked" without guessing from absence.
+// `rotation` is src/rotation.js's renderRotation() result (counts + per-
+// distinct-fingerprint entries with guidance attached), or null for a caller
+// that never computed it; the per-finding `fingerprint` is emitted either
+// way, since it is derived from already-redacted material and is what
+// "residoo ack" takes.
+function renderJson(result, integrity = null, rotation = null) {
   return JSON.stringify(
     {
       summary: {
@@ -113,11 +268,36 @@ function renderJson(result) {
       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,
+        fingerprint: fingerprintFinding(f),
       })),
+      // orderAdvisory mirrors the human report's ChainDrop ordering warning:
+      // remediation order is safety-critical when planted persistence and
+      // leaked credentials coexist, and a --json consumer (a CI summarizer)
+      // must not have to re-derive that condition. The advisory text when the
+      // condition holds, null otherwise.
+      rotation: rotation
+        ? {
+            counts: rotation.counts,
+            entries: rotation.entries,
+            orderAdvisory:
+              result.findings.length > 0 &&
+              integrity && integrity.findings.some((f) => f.severity === "warn")
+                ? ROTATION_ORDER_ADVISORY
+                : null,
+          }
+        : null,
+      integrity: integrity
+        ? {
+            warningCount: integrity.findings.filter((f) => f.severity === "warn").length,
+            findings: integrity.findings,
+            filesChecked: integrity.filesChecked,
+            scopeNote: integrity.scopeNote,
+          }
+        : null,
     },
     null,
     2
   );
 }
 
-module.exports = { render, renderJson };
+module.exports = { render, renderIntegrity, renderRotationSection, renderJson };