@coo-quack/sensitive-canary 0.6.0 → 0.8.0

package/src/lib/rules.ts

@@ -1,3 +1,16 @@
+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";
 
 export interface Finding {
@@ -6,6 +19,7 @@ export interface Finding {
   category: Category;
   matchRedacted: string;
   secretValue: string;
+  score?: number;
 }
 
 interface Rule {
@@ -16,6 +30,39 @@ interface Rule {
   entropyThreshold?: number;
   validate?: (str: string) => boolean;
   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;
+}
+
+// JSON representation of a rule, as written in config files. The `regex` is a
+// source string (not a RegExp literal), compiled at load time. `validate` is a
+// name into the VALIDATORS registry.
+export interface RuleConfig {
+  id: string;
+  description: string;
+  regex: string;
+  flags?: string;
+  secretGroup?: number;
+  entropyThreshold?: number;
+  validate?: string;
+  category: Category;
+  contextWords?: string[];
+  requireContext?: boolean;
+  // See Rule.excludeContext.
+  excludeContext?: string[];
+  contextWindow?: number;
+}
+
+// Top-level config file: a context window override plus a list of rules.
+// User config files use the same shape and can override built-in rules by id.
+export interface CanaryConfig {
+  contextWindow?: number;
+  rules: RuleConfig[];
 }
 
 const ALL_CATEGORIES: ReadonlySet<Category> = new Set(["secret", "pii"]);
@@ -41,301 +88,468 @@ 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, "");
-  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;
+// ── Context enhancement ──────────────────────────────────────────────────────
+
+// Set from the default config during module initialisation (see buildRules).
+let effectiveContextWindow = 3;
+
+export function getDefaultContextWindow(): number {
+  return effectiveContextWindow;
+}
+
+// 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(
+  text: string,
+  matchStart: number,
+  matchEnd: number,
+  contextWords: string[],
+  windowTokens: number,
+): boolean {
+  if (contextWords.length === 0) return true;
+  const charWindow = windowTokens * 8;
+  const before = text.slice(Math.max(0, matchStart - charWindow), matchStart);
+  const after = text.slice(matchEnd, matchEnd + charWindow);
+  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 ───────────────────────────────────────────────────────────
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG_PATH = join(MODULE_DIR, "default-config.json");
+const { SENSITIVE_CANARY_CONFIG: userConfigPath } = process.env;
+const USER_CONFIG_PATH =
+  userConfigPath ??
+  join(homedir(), ".config", "sensitive-canary", "config.json");
+
+function readJsonFile(filePath: string): unknown {
+  return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+
+// Validate a raw JSON object against the RuleConfig schema. Throws with a
+// descriptive message when a required field is missing, a type is wrong, or a
+// cross-field constraint is violated.
+function validateRuleConfig(rc: unknown): asserts rc is RuleConfig {
+  if (typeof rc !== "object" || rc === null) {
+    throw new Error("rule must be an object");
+  }
+  const {
+    id,
+    description,
+    regex: source,
+    category,
+    flags,
+    secretGroup,
+    entropyThreshold,
+    validate: validateName,
+    contextWords,
+    excludeContext,
+    requireContext,
+    contextWindow,
+  } = rc as Record<string, unknown>;
+
+  if (typeof id !== "string" || id.length === 0) {
+    throw new Error('missing or empty "id" field');
+  }
+  if (typeof description !== "string" || description.length === 0) {
+    throw new Error('missing or empty "description" field');
+  }
+  if (typeof source !== "string" || source.length === 0) {
+    throw new Error('missing or empty "regex" field');
+  }
+  if (category !== "secret" && category !== "pii") {
+    throw new Error(
+      `invalid "category" ${JSON.stringify(category)} (must be "secret" or "pii")`,
+    );
+  }
+  if (flags != null && typeof flags !== "string") {
+    throw new Error('"flags" must be a string');
+  }
+  if (
+    secretGroup != null &&
+    (typeof secretGroup !== "number" ||
+      !Number.isInteger(secretGroup) ||
+      secretGroup < 0)
+  ) {
+    throw new Error('"secretGroup" must be a non-negative integer');
+  }
+  if (
+    entropyThreshold != null &&
+    (typeof entropyThreshold !== "number" || entropyThreshold < 0)
+  ) {
+    throw new Error('"entropyThreshold" must be a non-negative number');
+  }
+  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) ||
+      contextWords.some((w) => typeof w !== "string" || w.length === 0)
+    ) {
+      throw new Error('"contextWords" must be an array of non-empty strings');
     }
-    sum += d;
-    double = !double;
   }
-  return sum % 10 === 0;
+  if (requireContext != null && typeof requireContext !== "boolean") {
+    throw new Error('"requireContext" must be a boolean');
+  }
+  if (
+    contextWindow != null &&
+    (typeof contextWindow !== "number" ||
+      !Number.isInteger(contextWindow) ||
+      contextWindow < 1)
+  ) {
+    throw new Error('"contextWindow" must be a positive integer');
+  }
+
+  // Cross-field: requireContext is meaningless without contextWords
+  if (
+    requireContext === true &&
+    (!Array.isArray(contextWords) || contextWords.length === 0)
+  ) {
+    throw new Error(
+      '"requireContext" is true but "contextWords" is empty — context gating would be disabled and the rule would always fire',
+    );
+  }
 }
 
-// Shannon entropy (bits per character, 0–8 scale)
-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);
+// Compile a single RuleConfig (JSON) into a Rule (with compiled RegExp and
+// resolved validator function). Throws on invalid regex or missing required
+// fields so the caller (buildRules) can catch and warn per-rule.
+export function compileRule(rc: RuleConfig): Rule {
+  validateRuleConfig(rc);
+  const { regex: source, flags, validate: validateName, ...rest } = rc;
+  // matchAll requires the global flag; ensure it is always present.
+  const flagStr = flags ?? "g";
+  const withG = flagStr.includes("g") ? flagStr : `${flagStr}g`;
+  const rule: Rule = {
+    ...rest,
+    regex: new RegExp(source, withG),
+  };
+  if (validateName) {
+    const fn = getValidator(validateName);
+    if (fn) {
+      rule.validate = fn;
+    } else {
+      process.stderr.write(
+        `sensitive-canary: unknown validator "${validateName}" in rule "${rc.id}" — validation disabled\n`,
+      );
+    }
   }
-  return h;
+  return rule;
+}
+
+// Load and compile the built-in default rules from default-config.json.
+function loadDefaultConfig(): CanaryConfig {
+  return readJsonFile(DEFAULT_CONFIG_PATH) as CanaryConfig;
 }
 
-// Patterns sourced from gitleaks and TruffleHog detector definitions.
-// Each rule:
-//   regex        — must have /g flag
-//   secretGroup  — capture group containing the secret (default: 0 = full match)
-//   entropyThreshold — skip match if entropy(secretValue) is below threshold
-
-// ── Secrets ───────────────────────────────────────────────────────────────────
-
-const SECRET_RULES: Rule[] = [
-  // Cloud
-  {
-    id: "aws-access-key",
-    description: "AWS Access Key ID",
-    regex:
-      /\b(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}\b/g,
-    category: "secret",
-  },
-  {
-    id: "gcp-api-key",
-    description: "Google Cloud API Key",
-    regex: /AIza[0-9A-Za-z_-]{35}/g,
-    category: "secret",
-  },
-  {
-    id: "private-key",
-    description: "PEM Private Key",
-    // Covers RSA, EC, DSA, PGP, and OpenSSH private keys
-    regex: /-----BEGIN (RSA |EC |DSA |PGP |OPENSSH )?PRIVATE KEY/g,
-    category: "secret",
-  },
-
-  // Source control
-  {
-    id: "github-pat",
-    description: "GitHub Personal Access Token",
-    regex: /gh[pousr]_[A-Za-z0-9]{36,255}/g,
-    category: "secret",
-  },
-  {
-    id: "github-fine-grained",
-    description: "GitHub Fine-Grained Token",
-    regex: /github_pat_[A-Za-z0-9_]{82}/g,
-    category: "secret",
-  },
-  {
-    id: "gitlab-pat",
-    description: "GitLab Personal Access Token",
-    regex: /glpat-[A-Za-z0-9_=-]{20,22}/g,
-    category: "secret",
-  },
-
-  // Package registries
-  {
-    id: "npm-token",
-    description: "npm Access Token",
-    regex: /npm_[A-Za-z0-9]{36}/g,
-    category: "secret",
-  },
-
-  // Communication
-  {
-    id: "slack-token",
-    description: "Slack Token",
-    regex: /xox[baprs]-[0-9a-zA-Z-]{10,72}/g,
-    category: "secret",
-  },
-  {
-    id: "slack-webhook",
-    description: "Slack Webhook URL",
-    regex:
-      /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9_]{8,10}\/B[A-Za-z0-9_]{8,12}\/[A-Za-z0-9_]{23,24}/g,
-    category: "secret",
-  },
-  {
-    id: "discord-webhook",
-    description: "Discord Webhook URL",
-    regex:
-      /https:\/\/discord(?:app)?\.com\/api\/webhooks\/[0-9]{17,20}\/[A-Za-z0-9_-]{68}/g,
-    category: "secret",
-  },
-  {
-    id: "telegram-bot-token",
-    description: "Telegram Bot Token",
-    regex: /[0-9]{8,10}:AA[0-9A-Za-z_-]{33}/g,
-    category: "secret",
-  },
-  {
-    id: "twilio-sid",
-    description: "Twilio Account SID",
-    regex: /AC[0-9a-f]{32}/g,
-    category: "secret",
-  },
-
-  // Email services
-  {
-    id: "sendgrid-key",
-    description: "SendGrid API Key",
-    regex: /SG\.[A-Za-z0-9_-]{20,24}\.[A-Za-z0-9_-]{39,50}/g,
-    category: "secret",
-  },
-  {
-    id: "mailgun-key",
-    description: "Mailgun API Key",
-    regex: /key-[0-9a-zA-Z]{32}/g,
-    category: "secret",
-  },
-  {
-    id: "mailchimp-key",
-    description: "Mailchimp API Key",
-    regex: /[0-9a-f]{32}-us[0-9]{1,2}/g,
-    category: "secret",
-  },
-
-  // Payment
-  {
-    id: "stripe-secret-key",
-    description: "Stripe Secret Key",
-    regex: /sk_(live|test)_[0-9a-zA-Z]{24}/g,
-    category: "secret",
-  },
-  {
-    id: "stripe-restricted-key",
-    description: "Stripe Restricted Key",
-    regex: /rk_(live|test)_[0-9a-zA-Z]{24}/g,
-    category: "secret",
-  },
-
-  // AI services
-  {
-    id: "openai-key",
-    description: "OpenAI API Key (legacy)",
-    regex: /sk-(?!proj-|ant-)[A-Za-z0-9]{48}/g,
-    category: "secret",
-  },
-  {
-    id: "openai-project-key",
-    description: "OpenAI Project API Key",
-    regex: /sk-proj-[A-Za-z0-9_-]{40,}/g,
-    entropyThreshold: 3.5,
-    category: "secret",
-  },
-  {
-    id: "anthropic-key",
-    description: "Anthropic API Key",
-    regex: /sk-ant-[A-Za-z0-9_-]{95}/g,
-    category: "secret",
-  },
-
-  // Auth tokens
-  {
-    id: "jwt",
-    description: "JSON Web Token (JWT)",
-    regex: /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
-    category: "secret",
-  },
-
-  // Generic / env-based
-  {
-    id: "generic-secret",
-    description: "Generic API Key / Secret",
-    regex:
-      /(api[_-]?key|secret[_-]?key|access[_-]?token|api[_-]?secret)\s*[:=]\s*['"]?([A-Za-z0-9\-_.]{20,})/gi,
-    secretGroup: 2,
-    entropyThreshold: 3.5,
-    category: "secret",
-  },
-  {
-    id: "env-assignment",
-    description: ".env style secret assignment",
-    regex:
-      /\b[A-Z_]*(SECRET|PASSWORD|PASSWD|TOKEN|API_KEY|PRIVATE_KEY)[A-Z_0-9]*\s*=\s*(\S{8,})/g,
-    secretGroup: 2,
-    entropyThreshold: 3.0,
-    category: "secret",
-  },
-  {
-    id: "connection-string",
-    description: "Database Connection String with credentials",
-    regex: /(mongodb|mysql|postgres|postgresql|redis):\/\/[^:\s]+:[^@\s]+@/g,
-    category: "secret",
-  },
-];
-
-// ── PII ───────────────────────────────────────────────────────────────────────
-
-const PII_RULES: Rule[] = [
-  {
-    id: "pii-email",
-    description: "Email Address",
-    regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
-    category: "pii",
-  },
-  {
-    id: "pii-credit-card",
-    description: "Credit Card Number",
-    // Visa (16d) | Mastercard (16d) | Amex (15d) | Discover (16d)
-    // Optional spaces or dashes between digit groups
-    regex:
-      /\b(?:4[0-9]{3}(?:[\s-]?[0-9]{4}){3}|5[1-5][0-9]{2}(?:[\s-]?[0-9]{4}){3}|3[47][0-9]{2}[\s-]?[0-9]{6}[\s-]?[0-9]{5}|6(?:011|5[0-9]{2})[0-9](?:[\s-]?[0-9]{4}){3})\b/g,
-    validate: luhn,
-    category: "pii",
-  },
-  {
-    id: "pii-ssn",
-    description: "US Social Security Number",
-    regex: /\b(?!000|666|9\d{2})\d{3}[- ](?!00)\d{2}[- ](?!0000)\d{4}\b/g,
-    category: "pii",
-  },
-  {
-    id: "pii-phone-us",
-    description: "US Phone Number",
-    regex: /\b(\+1[\s.-]?)?\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4}\b/g,
-    category: "pii",
-  },
-  {
-    id: "pii-phone-jp",
-    description: "Japanese Phone Number",
-    regex: /\b0\d{1,4}[\s-]\d{1,4}[\s-]\d{4}\b/g,
-    category: "pii",
-  },
-  {
-    id: "pii-postal-jp",
-    description: "Japanese Postal Code",
-    // Require 〒 prefix to avoid false positives (e.g. phone number fragments)
-    regex: /〒\d{3}[\s-]\d{4}/g,
-    category: "pii",
-  },
-  {
-    id: "pii-ipv4",
-    description: "IPv4 Address (private range)",
-    // Only flag RFC-1918 private addresses to reduce noise
-    regex:
-      /\b(10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b/g,
-    category: "pii",
-  },
-];
-
-export const RULES: Rule[] = [...SECRET_RULES, ...PII_RULES];
-
-// Show first 4 + **** + last 4 chars; fully mask strings of 8 chars or fewer
+// Load user config if it exists. Returns null when the file is absent (the
+// common case). JSON parse errors and permission issues are reported on stderr
+// 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") {
+      process.stderr.write(
+        `sensitive-canary: could not read user config "${USER_CONFIG_PATH}": ${e instanceof Error ? e.message : String(e)}\n`,
+      );
+    }
+    return null;
+  }
+}
+
+// Build the final rule list: default rules first, then user rules. A user rule
+// with the same id as a built-in rule replaces it; new ids are appended.
+// Invalid user rules (bad regex, etc.) are skipped with a warning so that one
+// bad entry does not break the entire hook.
+function buildRules(): Rule[] {
+  const defaultConfig = loadDefaultConfig();
+  effectiveContextWindow = defaultConfig.contextWindow ?? 3;
+
+  const defaultRules: Rule[] = [];
+  for (const rc of defaultConfig.rules) {
+    try {
+      defaultRules.push(compileRule(rc));
+    } catch (e) {
+      process.stderr.write(
+        `sensitive-canary: failed to compile built-in rule "${(rc as { id?: unknown })?.id ?? "(unknown)"}": ${e instanceof Error ? e.message : String(e)}\n`,
+      );
+    }
+  }
+
+  const userConfig = loadUserConfig();
+  if (userConfig) {
+    if (
+      typeof userConfig.contextWindow === "number" &&
+      Number.isInteger(userConfig.contextWindow) &&
+      userConfig.contextWindow >= 1
+    ) {
+      effectiveContextWindow = userConfig.contextWindow;
+    } else if (userConfig.contextWindow != null) {
+      process.stderr.write(
+        `sensitive-canary: invalid contextWindow in user config, ignoring\n`,
+      );
+    }
+    if (userConfig.rules != null && !Array.isArray(userConfig.rules)) {
+      process.stderr.write(
+        `sensitive-canary: "rules" in user config must be an array, ignoring\n`,
+      );
+    }
+    if (Array.isArray(userConfig.rules) && userConfig.rules.length) {
+      const userRules: Rule[] = [];
+      for (const rc of userConfig.rules) {
+        try {
+          userRules.push(compileRule(rc));
+        } catch (e) {
+          process.stderr.write(
+            `sensitive-canary: skipping user rule "${(rc as { id?: unknown })?.id ?? "(unknown)"}": ${e instanceof Error ? e.message : String(e)}\n`,
+          );
+        }
+      }
+      // De-duplicate by id (last definition wins) so duplicate ids in the
+      // user config don't produce duplicate rules and duplicate findings.
+      const byId = new Map<string, Rule>();
+      for (const rule of userRules) {
+        if (byId.has(rule.id)) {
+          process.stderr.write(
+            `sensitive-canary: duplicate user rule id "${rule.id}" — using the last definition\n`,
+          );
+        }
+        byId.set(rule.id, rule);
+      }
+      return defaultRules
+        .filter((r) => !byId.has(r.id))
+        .concat(Array.from(byId.values()));
+    }
+  }
+
+  return defaultRules;
+}
+
+export const RULES: Rule[] = buildRules();
+
+// 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
       )
         continue;
-      if (rule.validate != null && !rule.validate(match[0])) continue;
+      if (rule.validate != null && !rule.validate(secretValue)) continue;
+
+      const hasContext =
+        !rule.contextWords || rule.contextWords.length === 0
+          ? true
+          : hasNearbyContextWord(
+              text,
+              matchStart,
+              matchEnd,
+              rule.contextWords,
+              rule.contextWindow ?? effectiveContextWindow,
+            );
+
+      // Rules that require context (e.g. bare postal codes) are dropped when
+      // 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,
@@ -343,6 +557,7 @@ export function scan(
         category: rule.category,
         matchRedacted: redact(secretValue),
         secretValue,
+        score: hasContext ? 1.0 : 0.4,
       });
     }
   }