@coo-quack/sensitive-canary 0.7.0 → 0.8.1

package/src/lib/rules.ts

@@ -1,7 +1,15 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import vm from "node:vm";
+import {
+  entropy,
+  isNotSecretShaped,
+  isPlaceholder,
+  keyDescribesRatherThanHolds,
+} from "./shapes.ts";
+import { getValidator } from "./validators.ts";
 
 export type Category = "secret" | "pii";
 
@@ -24,6 +32,10 @@ interface Rule {
   category: Category;
   contextWords?: string[];
   requireContext?: boolean;
+  // Words that, found near a match, say it is not what the rule is looking for —
+  // the mirror of contextWords. The postal-code rule uses it: `65536 bytes` and
+  // `max 3` are five-digit numbers beside a word that says they are not places.
+  excludeContext?: string[];
   contextWindow?: number;
 }
 
@@ -41,6 +53,8 @@ export interface RuleConfig {
   category: Category;
   contextWords?: string[];
   requireContext?: boolean;
+  // See Rule.excludeContext.
+  excludeContext?: string[];
   contextWindow?: number;
 }
 
@@ -74,326 +88,6 @@ export function enabledCategoriesFromEnv(): Set<Category> {
   return parseCategories(SENSITIVE_CANARY_CATEGORIES);
 }
 
-// Luhn algorithm checksum validation. Returns true if the number (digits only) passes.
-export function luhn(str: string): boolean {
-  const digits = str.replace(/\D/g, "");
-  if (digits.length === 0) return false;
-  let sum = 0;
-  let double = false;
-  for (let i = digits.length - 1; i >= 0; i--) {
-    let d = parseInt(digits[i] ?? "", 10);
-    if (double) {
-      d *= 2;
-      if (d > 9) d -= 9;
-    }
-    sum += d;
-    double = !double;
-  }
-  return sum % 10 === 0;
-}
-
-// ── National ID checksum validators ──────────────────────────────────────────
-
-// Japanese Individual Number (My Number): 12 digits, weighted checksum over the
-// first 11 digits with weights 6,5,4,3,2,7,6,5,4,3,2. The 12th digit is
-// 11 - (sum mod 11); when the remainder is 0 or 1, the check digit is 0.
-// Spec: 地方公共団体情報システム機構 (J-LIS).
-export function validateMyNumber(input: string): boolean {
-  const digits = input.replace(/\D/g, "");
-  if (digits.length !== 12) return false;
-  const weights = [6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
-  let sum = 0;
-  for (let i = 0; i < 11; i++) {
-    sum += parseInt(digits[i] ?? "", 10) * (weights[i] ?? 0);
-  }
-  const remainder = sum % 11;
-  const checkDigit = remainder <= 1 ? 0 : 11 - remainder;
-  return checkDigit === parseInt(digits[11] ?? "", 10);
-}
-
-// French NIR (Numéro de sécurité sociale / INSEE): 15 digits, 2-digit check key
-// computed as 97 - (N mod 97) over the leading 13 digits. Corsica departements
-// use 2A/2B, substituted to 19/18 before the mod. The 13-digit value can exceed
-// Number.MAX_SAFE_INTEGER, so BigInt is used. Spec: INSEE / décret n°82-103.
-export function validateFrenchNIR(input: string): boolean {
-  const cleaned = input.replace(/\s/g, "");
-  let nir13: string;
-  let keyStr: string;
-
-  const standard = cleaned.match(/^([12]\d{12})(\d{2})$/);
-  const corseA = cleaned.match(/^([12]\d{4}2A\d{6})(\d{2})$/i);
-  const corseB = cleaned.match(/^([12]\d{4}2B\d{6})(\d{2})$/i);
-
-  if (standard) {
-    nir13 = standard[1] ?? "";
-    keyStr = standard[2] ?? "";
-  } else if (corseA) {
-    nir13 = (corseA[1] ?? "").replace(/2A/i, "19");
-    keyStr = corseA[2] ?? "";
-  } else if (corseB) {
-    nir13 = (corseB[1] ?? "").replace(/2B/i, "18");
-    keyStr = corseB[2] ?? "";
-  } else {
-    return false;
-  }
-
-  const num = BigInt(nir13);
-  const computedKey = 97 - Number(num % 97n);
-  return computedKey === parseInt(keyStr, 10);
-}
-
-// Italian Codice Fiscale: 16 alphanumeric chars. The last char is a control
-// character computed by summing odd/even position values (different maps) mod 26.
-// Spec: Agenzia delle Entrate, DM 12 giugno 2007.
-const CF_ODD_VALUES: Record<string, number> = {
-  "0": 1,
-  "1": 0,
-  "2": 5,
-  "3": 7,
-  "4": 9,
-  "5": 13,
-  "6": 15,
-  "7": 17,
-  "8": 19,
-  "9": 21,
-  A: 1,
-  B: 0,
-  C: 5,
-  D: 7,
-  E: 9,
-  F: 13,
-  G: 15,
-  H: 17,
-  I: 19,
-  J: 21,
-  K: 2,
-  L: 4,
-  M: 18,
-  N: 20,
-  O: 11,
-  P: 3,
-  Q: 6,
-  R: 8,
-  S: 12,
-  T: 14,
-  U: 16,
-  V: 10,
-  W: 22,
-  X: 25,
-  Y: 24,
-  Z: 23,
-};
-
-export function validateCodiceFiscale(input: string): boolean {
-  const cf = input.toUpperCase().replace(/\s/g, "");
-  if (!/^[A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z]$/.test(cf)) return false;
-
-  let sum = 0;
-  for (let i = 0; i < 15; i++) {
-    const ch = cf[i] ?? "";
-    if (i % 2 === 0) {
-      sum += CF_ODD_VALUES[ch] ?? -1;
-    } else if (/[0-9]/.test(ch)) {
-      sum += parseInt(ch, 10);
-    } else {
-      sum += ch.charCodeAt(0) - 65;
-    }
-  }
-  const expected = String.fromCharCode(65 + (sum % 26));
-  return expected === cf[15];
-}
-
-// German Steuer-Identifikationsnummer (IdNr.): 11 digits, first digit non-zero.
-// Uses ISO/IEC 7064 MOD 11,10. Spec: Bundeszentralamt für Steuern.
-export function validateGermanIdNr(input: string): boolean {
-  const cleaned = input.replace(/\s/g, "");
-  if (!/^[1-9]\d{10}$/.test(cleaned)) return false;
-
-  let produkt = 10;
-  for (let i = 0; i < 10; i++) {
-    let summe = (parseInt(cleaned[i] ?? "", 10) + produkt) % 10;
-    if (summe === 0) summe = 10;
-    produkt = (summe * 2) % 11;
-  }
-  let check = 11 - produkt;
-  if (check === 10) check = 0;
-  return check === parseInt(cleaned[10] ?? "", 10);
-}
-
-// Spanish DNI (8 digits + letter) and NIE (X/Y/Z + 7 digits + letter). The
-// control letter is selected from TRWAGMYFPDXBNJZSQVHLCKE by the number mod 23.
-// NIE leading letters map X→0, Y→1, Z→2 before the mod.
-// Spec: Ministerio del Interior, Orden INT/2058/2008.
-const NIF_LETTERS = "TRWAGMYFPDXBNJZSQVHLCKE";
-
-export function validateSpanishNIF(input: string): boolean {
-  const cleaned = input.toUpperCase().replace(/[\s-]/g, "");
-
-  const dni = cleaned.match(/^(\d{8})([A-Z])$/);
-  if (dni) {
-    return NIF_LETTERS[parseInt(dni[1] ?? "", 10) % 23] === dni[2];
-  }
-
-  const nie = cleaned.match(/^([XYZ])(\d{7})([A-Z])$/);
-  if (nie) {
-    const prefix = nie[1] === "X" ? "0" : nie[1] === "Y" ? "1" : "2";
-    const num = parseInt(prefix + (nie[2] ?? ""), 10);
-    return NIF_LETTERS[num % 23] === nie[3];
-  }
-
-  return false;
-}
-
-// Korean Resident Registration Number (RRN, 주민등록번호): 13 digits.
-// Checksum is (11 - (weighted sum mod 11)) mod 10 with weights
-// 2,3,4,5,6,7,8,9,2,3,4,5 over the first 12 digits.
-// Note: numbers issued after Oct 2020 randomize digits 8-13, so the checksum
-// may not pass for valid recent numbers (false negatives possible).
-// Spec: 주민등록 사무편람 (Ministry of the Interior and Safety).
-export function validateKoreanRRN(input: string): boolean {
-  const s = input.replace(/[-\s]/g, "");
-  if (!/^\d{13}$/.test(s)) return false;
-  const weights = [2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4, 5];
-  let sum = 0;
-  for (let i = 0; i < 12; i++) {
-    sum += parseInt(s[i] ?? "", 10) * (weights[i] ?? 0);
-  }
-  const check = (11 - (sum % 11)) % 10;
-  return check === parseInt(s[12] ?? "", 10);
-}
-
-// Korean Business Registration Number (사업자등록번호): 10 digits. Uses the
-// NTS (Hometax) standard algorithm: weights 1,3,7,1,3,7,1,3,5 over digits 1-9,
-// plus floor(digit9 × 5 / 10), and the check digit is (10 - (sum mod 10)) mod 10.
-export function validateKoreanBRN(input: string): boolean {
-  const s = input.replace(/[-\s]/g, "");
-  if (!/^\d{10}$/.test(s)) return false;
-  const weights = [1, 3, 7, 1, 3, 7, 1, 3, 5];
-  let sum = 0;
-  for (let i = 0; i < 9; i++) {
-    sum += parseInt(s[i] ?? "", 10) * (weights[i] ?? 0);
-  }
-  sum += Math.floor((parseInt(s[8] ?? "", 10) * 5) / 10);
-  return (10 - (sum % 10)) % 10 === parseInt(s[9] ?? "", 10);
-}
-
-// Chinese Resident Identity Card (居民身份证): 18 chars (17 digits + check).
-// ISO 7064 MOD 11-2 per GB 11643-1999. Weights
-// 7,9,10,5,8,4,2,1,6,3,7,9,10,5,8,4,2; remainder maps to "10X98765432".
-export function validateChineseID(input: string): boolean {
-  const s = input.toUpperCase().replace(/[-\s]/g, "");
-  if (!/^\d{17}[\dX]$/.test(s)) return false;
-  const weights = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];
-  const code = "10X98765432";
-  let sum = 0;
-  for (let i = 0; i < 17; i++) {
-    sum += parseInt(s[i] ?? "", 10) * (weights[i] ?? 0);
-  }
-  return code[sum % 11] === s[17];
-}
-
-// IPv4 reserved / non-public ranges. Returns true for addresses that should
-// NOT be flagged as PII (loopback, private, link-local, TEST-NET, multicast,
-// reserved, CGN, benchmarking). Used by pii-ipv4-public to keep only public IPs.
-export function isReservedIpv4(ip: string): boolean {
-  const octets = ip.split(".");
-  // Require exactly 4 octets of 1–3 digits each, so partial parses
-  // (e.g. "1a" → 1 via parseInt) are treated as malformed, not public.
-  if (octets.length !== 4 || octets.some((o) => !/^\d{1,3}$/.test(o))) {
-    return true;
-  }
-  const parts = octets.map((o) => parseInt(o, 10));
-  if (parts.some((p) => p > 255)) {
-    return true;
-  }
-  const a = parts[0] ?? 0;
-  const b = parts[1] ?? 0;
-  const c = parts[2] ?? 0;
-  if (a === 0 || a === 10) return true;
-  if (a === 100 && b >= 64 && b <= 127) return true; // CGN 100.64.0.0/10
-  if (a === 127) return true; // loopback
-  if (a === 169 && b === 254) return true; // link-local
-  if (a === 172 && b >= 16 && b <= 31) return true; // private
-  if (a === 192 && b === 0 && c === 0) return true; // IETF protocol assignments
-  if (a === 192 && b === 0 && c === 2) return true; // TEST-NET-1
-  if (a === 192 && b === 88 && c === 99) return true; // 6to4 relay anycast (deprecated)
-  if (a === 192 && b === 168) return true; // private
-  if (a === 198 && (b === 18 || b === 19)) return true; // benchmark
-  if (a === 198 && b === 51 && c === 100) return true; // TEST-NET-2
-  if (a === 203 && b === 0 && c === 113) return true; // TEST-NET-3
-  if (a >= 224) return true; // multicast + reserved
-  return false;
-}
-
-// IPv6 reserved / non-public ranges. Returns true for addresses that should
-// NOT be flagged as PII (loopback, unspecified, link-local, unique-local,
-// multicast, documentation). Properly handles both compressed (::) and
-// fully-expanded (0:0:0:0:0:0:0:1) forms. Used by pii-ipv6.
-// Each group must be 1–4 hex digits; anything else is malformed.
-const isHexGroup = (g: string): boolean => /^[0-9a-f]{1,4}$/.test(g);
-export function isReservedIpv6(ip: string): boolean {
-  const lower = ip.toLowerCase();
-
-  // Multiple :: is invalid — treat as reserved.
-  const halves = lower.split("::");
-  if (halves.length > 2) return true;
-
-  // Split and expand :: notation into zero groups.
-  let groups: number[];
-  if (halves.length === 1) {
-    const raw = lower.split(":");
-    if (raw.some((g) => !isHexGroup(g))) return true;
-    groups = raw.map((g) => Number.parseInt(g, 16));
-  } else {
-    const leftRaw = halves[0] ? halves[0].split(":") : [];
-    const rightRaw = halves[1] ? halves[1].split(":") : [];
-    if (
-      leftRaw.some((g) => !isHexGroup(g)) ||
-      rightRaw.some((g) => !isHexGroup(g))
-    ) {
-      return true;
-    }
-    // Too many groups to fit in 128 bits — malformed. A "::" that compresses
-    // zero groups (left + right === 8) is also invalid per RFC 4291 §2.2.
-    if (leftRaw.length + rightRaw.length >= 8) return true;
-    const left = leftRaw.map((g) => Number.parseInt(g, 16));
-    const right = rightRaw.map((g) => Number.parseInt(g, 16));
-    const zeros = Array(8 - left.length - right.length).fill(0);
-    groups = [...left, ...zeros, ...right];
-  }
-
-  if (groups.length !== 8) return true; // malformed — treat as reserved
-
-  // Unspecified (::)
-  if (groups.every((g) => g === 0)) return true;
-  // Loopback (::1)
-  if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return true;
-  // Link-local fe80::/10
-  if ((groups[0] ?? 0) >= 0xfe80 && (groups[0] ?? 0) <= 0xfebf) return true;
-  // Unique-local fc00::/7
-  if (((groups[0] ?? 0) & 0xfe00) === 0xfc00) return true;
-  // Multicast ff00::/8
-  if (((groups[0] ?? 0) & 0xff00) === 0xff00) return true;
-  // Documentation 2001:db8::/32
-  if ((groups[0] ?? 0) === 0x2001 && (groups[1] ?? 0) === 0x0db8) return true;
-
-  return false;
-}
-
-// Shannon entropy (bits per character; ≈0–8 for byte-sized alphabets)
-export function entropy(str: string): number {
-  if (str.length === 0) return 0;
-  const freq: Record<string, number> = {};
-  for (const ch of str) freq[ch] = (freq[ch] ?? 0) + 1;
-  let h = 0;
-  const n = str.length;
-  for (const count of Object.values(freq)) {
-    const p = count / n;
-    h -= p * Math.log2(p);
-  }
-  return h;
-}
-
 // ── Context enhancement ──────────────────────────────────────────────────────
 
 // Set from the default config during module initialisation (see buildRules).
@@ -403,16 +97,21 @@ export function getDefaultContextWindow(): number {
   return effectiveContextWindow;
 }
 
-// Split on whitespace and Unicode punctuation. A cheap tokenizer with no NLP
-// dependency, sufficient for matching context labels (phone, ZIP, etc.) in
-// Latin-script text. Japanese PII rules rely on prefixes (〒) or required
-// separators rather than context words, so this tokenizer not needing to
-// handle Japanese word segmentation is acceptable.
-function tokenize(text: string): string[] {
-  return text
-    .toLowerCase()
-    .split(/[\s\p{P}]+/u)
-    .filter(Boolean);
+// Words as they were written, with only the punctuation around them removed.
+// Splitting on punctuation made `extract-zip` supply "zip" and
+// `golang.org/x/mobile` supply "mobile", so a version number beside either read
+// as a postal code or a telephone number — which is to say lockfiles and
+// `go.sum` could not be read.
+function contextTokens(text: string): Set<string> {
+  const out = new Set<string>();
+  for (const raw of text.split(/\s+/)) {
+    const word = raw
+      .replace(/^[\p{P}\p{S}]+/gu, "")
+      .replace(/[\p{P}\p{S}]+$/gu, "")
+      .toLowerCase();
+    if (word) out.add(word);
+  }
+  return out;
 }
 
 function hasNearbyContextWord(
@@ -426,33 +125,17 @@ function hasNearbyContextWord(
   const charWindow = windowTokens * 8;
   const before = text.slice(Math.max(0, matchStart - charWindow), matchStart);
   const after = text.slice(matchEnd, matchEnd + charWindow);
-  const nearby = new Set(tokenize(`${before} ${after}`));
-  return contextWords.some((word) => nearby.has(word.toLowerCase()));
-}
-
-// ── Validator registry ───────────────────────────────────────────────────────
-// Validators are code (checksum algorithms), not data. They live here and are
-// referenced by name from the JSON config. User-defined rules can use any of
-// these validators or omit `validate` entirely.
-
-const VALIDATORS: Readonly<Record<string, (str: string) => boolean>> = {
-  luhn,
-  "mynumber-jp": validateMyNumber,
-  "nir-fr": validateFrenchNIR,
-  "codice-fiscale-it": validateCodiceFiscale,
-  "steuer-id-de": validateGermanIdNr,
-  "dni-nie-es": validateSpanishNIF,
-  "rrn-kr": validateKoreanRRN,
-  "brn-kr": validateKoreanBRN,
-  "resident-id-cn": validateChineseID,
-  "public-ipv4": (ip: string) => !isReservedIpv4(ip),
-  "public-ipv6": (ip: string) => !isReservedIpv6(ip),
-};
-
-export function getValidator(
-  name: string,
-): ((str: string) => boolean) | undefined {
-  return VALIDATORS[name];
+  const window = `${before} ${after}`;
+  const nearby = contextTokens(window);
+  const lowered = window.toLowerCase();
+  return contextWords.some((raw) => {
+    const word = raw.toLowerCase();
+    // A label in a language that does not put spaces around its words is
+    // written against the number, so it is looked for as written.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: the ASCII range is the test
+    if (!/^[\x00-\x7f]+$/.test(word)) return lowered.includes(word);
+    return nearby.has(word);
+  });
 }
 
 // ── Config loading ───────────────────────────────────────────────────────────
@@ -485,6 +168,7 @@ function validateRuleConfig(rc: unknown): asserts rc is RuleConfig {
     entropyThreshold,
     validate: validateName,
     contextWords,
+    excludeContext,
     requireContext,
     contextWindow,
   } = rc as Record<string, unknown>;
@@ -523,6 +207,14 @@ function validateRuleConfig(rc: unknown): asserts rc is RuleConfig {
   if (validateName != null && typeof validateName !== "string") {
     throw new Error('"validate" must be a string');
   }
+  if (excludeContext != null) {
+    if (
+      !Array.isArray(excludeContext) ||
+      excludeContext.some((w) => typeof w !== "string" || w.length === 0)
+    ) {
+      throw new Error('"excludeContext" must be an array of non-empty strings');
+    }
+  }
   if (contextWords != null) {
     if (
       !Array.isArray(contextWords) ||
@@ -568,7 +260,7 @@ export function compileRule(rc: RuleConfig): Rule {
     regex: new RegExp(source, withG),
   };
   if (validateName) {
-    const fn = VALIDATORS[validateName];
+    const fn = getValidator(validateName);
     if (fn) {
       rule.validate = fn;
     } else {
@@ -590,6 +282,16 @@ function loadDefaultConfig(): CanaryConfig {
 // so that a broken config file is not silently ignored.
 function loadUserConfig(): CanaryConfig | null {
   try {
+    // A FIFO or a device here would block the read until something wrote to
+    // it, and a hook that never returns is killed by the timeout, which does
+    // not block. The transcript reader and the file scanner both pay this stat
+    // already; this path was the one that did not.
+    if (!statSync(USER_CONFIG_PATH).isFile()) {
+      process.stderr.write(
+        `sensitive-canary: user config "${USER_CONFIG_PATH}" is not a regular file, ignoring\n`,
+      );
+      return null;
+    }
     return readJsonFile(USER_CONFIG_PATH) as CanaryConfig;
   } catch (e) {
     if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
@@ -662,7 +364,7 @@ function buildRules(): Rule[] {
       }
       return defaultRules
         .filter((r) => !byId.has(r.id))
-        .concat(...byId.values());
+        .concat(Array.from(byId.values()));
     }
   }
 
@@ -671,25 +373,144 @@ function buildRules(): Rule[] {
 
 export const RULES: Rule[] = buildRules();
 
-// Show first 4 + **** + last 4 chars; fully mask strings of 8 chars or fewer
+// Enough of a value to say which one was found, and no more.
+//
+// The block reason is written to stderr, which is where Claude reads it, so
+// whatever is shown here reaches the API that the block exists to keep it from.
+// Four characters at each end returned eight of a nine-character password.
+// A quarter of the value, capped at four per end.
 export function redact(str: string): string {
-  if (str.length <= 8) return "****";
-  return `${str.slice(0, 4)}****${str.slice(-4)}`;
+  // Code points, not code units. Slicing by unit cuts a surrogate pair in half
+  // and writes a lone surrogate to the terminal, which is neither the character
+  // nor a redaction of it.
+  const characters = [...str];
+  const shown = Math.min(4, Math.floor(characters.length / 8));
+  if (shown === 0) return "****";
+  const head = characters.slice(0, shown).join("");
+  const tail = characters.slice(-shown).join("");
+  return `${head}****${tail}`;
+}
+
+// Longer than any honest scan and far shorter than the hook timeout. A rule
+// that backtracks badly takes minutes on a megabyte, and a hook killed by the
+// timeout does not block, so the damage is silent. The patterns that did that
+// are bounded; this catches the next one of that shape rather than letting it
+// repeat. The check sits between rules because a single `matchAll` cannot be
+// interrupted.
+export const SCAN_BUDGET_MS = 10_000;
+
+export class ScanBudgetExceeded extends Error {
+  constructor(ruleId: string, elapsed: number) {
+    super(
+      `the scan passed ${SCAN_BUDGET_MS}ms (${elapsed}ms at rule "${ruleId}")`,
+    );
+    this.name = "ScanBudgetExceeded";
+  }
+}
+
+// The budget belongs to the hook invocation, not to one `scan()` call. A single
+// call is a small part of the work: `scanEnvironment` scans once per variable,
+// a file is scanned at both ends, and `Object.keys(process.env)` sets the
+// multiplier. Per call, each stays inside the budget while the total runs past
+// the hook timeout — and a hook killed by the timeout does not block.
+//
+// Set once by each hook entry point. Left unset, every call gets the full
+// budget, which is what the test suite needs.
+let deadline: number | null = null;
+
+// `null` clears it, which is the state a process starts in.
+export function beginScanBudget(totalMs: number | null = SCAN_BUDGET_MS): void {
+  deadline = totalMs === null ? null : Date.now() + totalMs;
+}
+
+// What is left of the budget, or the whole of it when none was begun.
+function remainingBudget(): number {
+  return deadline === null ? SCAN_BUDGET_MS : deadline - Date.now();
+}
+
+// The between-rule check below cannot interrupt a single `matchAll`, and one
+// rule from a user config is enough to hang the hook — which is then killed by
+// the timeout, and a killed hook does not block. A V8-side timeout does
+// interrupt a running match. Measured at 0.06ms per call, against a scan that
+// costs hundreds of times that.
+const SCAN_SLOT = "__sensitiveCanaryScan";
+const HARD_LIMIT_SLACK_MS = 2_000;
+
+// `limitMs` bounds this call so it cannot overshoot what the invocation has
+// left. Without it a single call could run the full hard limit past a deadline
+// that was already spent.
+function runInterruptibly<T>(work: () => T, limitMs: number): T {
+  const slots = globalThis as unknown as Record<string, unknown>;
+  slots[SCAN_SLOT] = work;
+  try {
+    return vm.runInThisContext(`globalThis.${SCAN_SLOT}()`, {
+      timeout: limitMs,
+      displayErrors: false,
+    }) as T;
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("timed out"))
+      throw new ScanBudgetExceeded("a single rule", limitMs);
+    throw error;
+  } finally {
+    delete slots[SCAN_SLOT];
+  }
 }
 
 export function scan(
   text: string,
   categories: ReadonlySet<Category> = ALL_CATEGORIES,
+): Finding[] {
+  const remaining = remainingBudget();
+  if (remaining <= 0)
+    throw new ScanBudgetExceeded("this call's total", SCAN_BUDGET_MS);
+  return runInterruptibly(
+    () => scanUninterrupted(text, categories, remaining),
+    remaining + HARD_LIMIT_SLACK_MS,
+  );
+}
+
+function scanUninterrupted(
+  text: string,
+  categories: ReadonlySet<Category>,
+  budgetMs: number,
 ): Finding[] {
   const findings: Finding[] = [];
+  const startedAt = Date.now();
 
   for (const rule of RULES) {
     if (!categories.has(rule.category)) continue;
+    const elapsed = Date.now() - startedAt;
+    // Thrown rather than returned: a partial result is indistinguishable from a
+    // clean one, and the hooks stop the call on an error they cannot explain.
+    if (elapsed > budgetMs) throw new ScanBudgetExceeded(rule.id, elapsed);
     for (const match of text.matchAll(rule.regex)) {
       const secretValue =
         rule.secretGroup != null ? match[rule.secretGroup] : match[0];
 
       if (!secretValue) continue;
+      // Both the captured value and the whole match: a rule with a
+      // `secretGroup` captures only part of what it matched, and the
+      // connection-string rule stops at the `@`, so the host — the one thing
+      // that separates `user:password@localhost` from `user:password@` in front
+      // of real infrastructure — is outside the capture.
+      const matchStart = match.index ?? 0;
+      const matchEnd = matchStart + match[0].length;
+      const following = text.slice(matchEnd, matchEnd + 64);
+      // The shape test applies only where the rule captured a free-form value.
+      // A rule that matches a fixed prefix has already said what the thing is —
+      // a Slack webhook is a URL and a secret, and asking whether it looks like
+      // a URL is asking the wrong question.
+      const capturesAValue = rule.secretGroup != null;
+      if (
+        rule.category === "secret" &&
+        (isPlaceholder(secretValue, following) ||
+          (capturesAValue &&
+            (isNotSecretShaped(secretValue) ||
+              isPlaceholder(match[0], following) ||
+              isNotSecretShaped(match[0]) ||
+              keyDescribesRatherThanHolds(match[0]))))
+      )
+        continue;
       if (
         rule.entropyThreshold != null &&
         entropy(secretValue) < rule.entropyThreshold
@@ -697,8 +518,6 @@ export function scan(
         continue;
       if (rule.validate != null && !rule.validate(secretValue)) continue;
 
-      const matchStart = match.index ?? 0;
-      const matchEnd = matchStart + match[0].length;
       const hasContext =
         !rule.contextWords || rule.contextWords.length === 0
           ? true
@@ -714,6 +533,24 @@ export function scan(
       // no context label is nearby, to avoid flagging every 5-digit number.
       if (rule.requireContext && !hasContext) continue;
 
+      // And the other way: a word nearby that says this is not what the rule is
+      // for. `git clone git@github.com:…` and `ssh deploy@host` are addresses by
+      // shape, and the command in front of them is what says they are not
+      // anyone's mail.
+      if (
+        rule.excludeContext &&
+        rule.excludeContext.length > 0 &&
+        hasNearbyContextWord(
+          text,
+          matchStart,
+          matchEnd,
+          rule.excludeContext,
+          rule.contextWindow ?? effectiveContextWindow,
+        )
+      ) {
+        continue;
+      }
+
       findings.push({
         ruleId: rule.id,
         description: rule.description,