@m2-ai/lattice-cli 0.0.0-stage → 0.8.7

package/dist/security-runtime/src/checks/_lib/secrets.mjs

@@ -0,0 +1,381 @@
+// Shared secret-scanning helpers (REQ-012): a Betterleaks wrapper, git/ignore handling and finding builders.
+// Used by secrets-tree, secrets-history and secrets-build, and reusable by the live stage for served JavaScript
+// (scanSecretsInDirectory, scanSecretsInBuffer). Raw secret values never leave this module: hits carry only a redaction.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { listFiles } from '../../core/detect.mjs';
+import { excludeNested } from '../../core/nested.mjs';
+import { gitFileLists, MAX_LIST_BYTES, prunedSpecs } from './gitfiles.mjs';
+import { redact, scrubText, severityRank, sha256 } from '../../core/findings.mjs';
+
+const TOOL = 'betterleaks';
+const posix = (p) => String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Directories that never hold project secrets worth scanning (huge, generated or vsg's own output). */
+export const ALWAYS_SKIP = [String.raw`(?:^|/)(?:node_modules|\.git|\.venv|venv|__pycache__|\.pnpm-store)/`, String.raw`^\.vsg/`];
+
+// ---- git helpers: argument arrays only, repository-controlled config that can run code is switched off ----
+const GIT = ['-c', 'core.fsmonitor=false', '--no-optional-locks'];
+export const git = (ctx, args, o = {}) => ctx.runProcess({ command: 'git', args: [...GIT, ...args], cwd: o.cwd ?? ctx.repo, timeoutMs: o.timeoutMs ?? 60_000, ...(o.maxOutputBytes ? { maxOutputBytes: o.maxOutputBytes } : {}) });
+const nulList = (s) => s.split('\0').filter(Boolean);
+
+/**
+ * { usable, hasCommits, shallow }. `usable` means the directory has its own git view and is not itself hidden by a parent's .gitignore
+ * (a fixture under a gitignored worktree path must still be scanned).
+ */
+export async function gitState(ctx) {
+  const inside = await git(ctx, ['rev-parse', '--is-inside-work-tree']);
+  if (inside.status !== 'ran' || inside.exitCode !== 0 || inside.stdout.trim() !== 'true') return { usable: false, hasCommits: false, shallow: false };
+  const ignored = await git(ctx, ['check-ignore', '-q', '.']);
+  if (ignored.status !== 'ran' || ignored.exitCode !== 1) return { usable: false, hasCommits: false, shallow: false };
+  const head = await git(ctx, ['rev-parse', '--verify', '-q', 'HEAD']);
+  const shallow = await git(ctx, ['rev-parse', '--is-shallow-repository']);
+  return { usable: true, hasCommits: head.exitCode === 0, shallow: shallow.stdout.trim() === 'true' };
+}
+
+/**
+ * Untracked paths that .gitignore hides (directories end with "/"). Empty when git is unusable.
+ * Dependency and cache directories are not listed (ALWAYS_SKIP covers them), which also keeps git from walking them.
+ */
+export async function ignoredPaths(ctx) {
+  const n = excludeNested(ctx.nestedRepos);
+  const r = await git(ctx, ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--directory', ...(n.length ? n : ['--', '.']), ...prunedSpecs()], { maxOutputBytes: MAX_LIST_BYTES });
+  return r.status === 'ran' && r.exitCode === 0 && !r.truncated ? nulList(r.stdout).map(posix) : [];
+}
+
+/**
+ * Files to read for static checks: { files, tracked (Set, or null without git), git }. Respects .gitignore. Untracked files inside
+ * dependency and cache directories (node_modules and similar) are left out; tracked files are always included.
+ * A git listing that cannot be read completely falls back to a directory walk, never to a partial list.
+ */
+export async function repoFiles(ctx, state) {
+  const st = state ?? await gitState(ctx);
+  if (st.usable) {
+    const lists = await gitFileLists(ctx);
+    if (lists) {
+      const isFile = (f) => { try { return fs.statSync(path.join(ctx.repo, f)).isFile(); } catch { return false; } };
+      return { files: [...new Set([...lists.tracked, ...lists.untracked].map(posix))].filter(isFile).sort(), tracked: new Set(lists.tracked.map(posix)), git: true };
+    }
+  }
+  return { files: listFiles(ctx.repo), tracked: null, git: false };
+}
+
+/** Regex path allowlist entries (RE2) for everything .gitignore hides plus the always-skipped directories. */
+export const skipPatterns = (ignored, exactFiles = []) => [
+  ...ALWAYS_SKIP,
+  ...ignored.filter((p) => !p.includes("'''")).map((p) => (p.endsWith('/') ? `^${escapeRe(p)}` : `^${escapeRe(p)}$`)),
+  ...exactFiles.filter((p) => !p.includes("'''")).map((p) => `^${escapeRe(p)}$`),
+];
+
+/**
+ * The scan configuration is ours, never the repository's: a repo-supplied .betterleaks.toml, .betterleaksignore or
+ * inline allow comment could silence findings. Risk is accepted only through vsg.accept.json.
+ */
+const configToml = (skip) => `[extend]\nuseDefault = true\n\n[[allowlists]]\ndescription = "vsg path exclusions"\npaths = [\n${skip.map((s) => `  '''${s}''',`).join('\n')}\n]\n`;
+
+// ---- noise filter: generic rules fire on ordinary words in UI translation files ----
+/** Localization files: a translations directory holding a data file. */
+const LOCALIZATION_FILE = /(?:^|\/)(?:i18n|locales?|l10n|translations?|lang|languages)\/(?:.+\/)?[^/]+\.(?:json|ya?ml|po|properties|xlf|arb)$/i;
+/** Betterleaks catch-all rules (generic-password, generic-api-key ...). Provider rules (stripe, github, aws ...) are never filtered. */
+const GENERIC_RULE = /^generic-/i;
+
+function shannonEntropy(s) {
+  const counts = new Map();
+  for (const c of s) counts.set(c, (counts.get(c) ?? 0) + 1);
+  let h = 0;
+  for (const n of counts.values()) h -= (n / s.length) * Math.log2(n / s.length);
+  return h;
+}
+
+/** True for a value that reads as ordinary text rather than a credential: spaces, letters only, non-ASCII text (credentials are ASCII), or low entropy. */
+export const looksLikeWords = (secret) => /\s/.test(secret) || /[^\x00-\x7f]/.test(secret) || /^[\p{L}\p{M}'’]+$/u.test(secret) || shannonEntropy(secret) < 3;
+
+/** A generic-rule hit in a localization file whose value is ordinary words (a translated "Password" label, not a password). */
+export const isLocalizationNoise = (ruleId, file, secret) => GENERIC_RULE.test(ruleId) && LOCALIZATION_FILE.test(file) && looksLikeWords(secret);
+
+// ---- false-positive suppression (REQ-037) ----
+// Every rule below runs where the raw value is still in hand (toHit); nothing here keeps the value. Provider-specific rules (AWS, Stripe,
+// GitHub, OpenAI, Anthropic, Supabase service role, Slack ...) are never touched by the generic-only rules. The one rule that applies to
+// every rule is the long-base64-run test, and it can only drop a value that is itself plain base64 inside a 200+ character base64 run.
+
+/** Common placeholder passwords, compared by the value's hash prefix (lower-cased) so no list of plaintext values is used. */
+const PLACEHOLDER_HASHES = new Set(['postgres', 'password', 'secret', 'pass', 'changeme', 'example', 'test', 'admin', 'root'].map((w) => sha256(w).slice(0, 12)));
+export const isPlaceholderValue = (secret) => PLACEHOLDER_HASHES.has(sha256(String(secret).toLowerCase()).slice(0, 12));
+
+/** Hosts that mean "this machine or its container network": a credential URI to one of them is a local development URI. */
+export function isLocalHost(host) {
+  const h = String(host ?? '').trim().toLowerCase().replace(/^\[|\]$/g, '');
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === 'host.docker.internal' || h.endsWith('.local');
+}
+const URI_HOST = /^[a-z][a-z0-9+.-]*:\/\/[^/@\s]*@(\[[^\]]+\]|[^:/?#\s]+)/i;
+const uriHostOf = (r) => String(r.CaptureGroups?.host ?? URI_HOST.exec(String(r.Match ?? ''))?.[1] ?? '');
+
+const b64urlJson = (part) => { try { return JSON.parse(Buffer.from(part, 'base64url').toString('utf8')); } catch { return null; } };
+/** Claims of a JWT-shaped value, or null. The signature is not checked: this only reads which public key kind a token is. */
+export function jwtClaims(value) {
+  const parts = String(value).split('.');
+  if (parts.length !== 3 || !parts.every((p) => /^[A-Za-z0-9_-]+$/.test(p))) return null;
+  const header = b64urlJson(parts[0]);
+  const claims = b64urlJson(parts[1]);
+  return header && typeof header === 'object' && claims && typeof claims === 'object' && !Array.isArray(claims) ? claims : null;
+}
+const SUPABASE_PUBLISHABLE = /^sb_publishable_[A-Za-z0-9_-]{8,}$/;
+const SUPABASE_ANON_HEADER = '{"alg":"HS256","typ":"JWT"}';
+const SUPABASE_ANON_CLAIMS = ['iss', 'role', 'iat', 'exp'];
+// Hosted Supabase includes the project ref between iss and role; the local key omits it.
+const SUPABASE_ANON_CLAIMS_WITH_REF = ['iss', 'ref', 'role', 'iat', 'exp'];
+const decodedJwtPart = (part) => Buffer.from(part, 'base64url').toString('utf8');
+/** Strict legacy anon shape. Signature validity is intentionally not checked. */
+function isCanonicalSupabaseAnonJwt(value) {
+  const parts = String(value ?? '').split('.');
+  if (parts.length !== 3 || !parts.every((p) => /^[A-Za-z0-9_-]+$/.test(p))) return false;
+  let header;
+  let claims;
+  let headerText;
+  let claimsText;
+  try {
+    headerText = decodedJwtPart(parts[0]);
+    claimsText = decodedJwtPart(parts[1]);
+    header = JSON.parse(headerText);
+    claims = JSON.parse(claimsText);
+  } catch { return false; }
+  if (headerText !== SUPABASE_ANON_HEADER || JSON.stringify(header) !== headerText) return false;
+  if (!claims || typeof claims !== 'object' || Array.isArray(claims) || JSON.stringify(claims) !== claimsText) return false;
+  const keys = Object.keys(claims);
+  if (keys.join('\0') !== SUPABASE_ANON_CLAIMS.join('\0') && keys.join('\0') !== SUPABASE_ANON_CLAIMS_WITH_REF.join('\0')) return false;
+  if (claims.iss !== 'supabase' || claims.role !== 'anon') return false;
+  if (!Number.isSafeInteger(claims.iat) || claims.iat <= 0 || !Number.isSafeInteger(claims.exp) || claims.exp <= claims.iat) return false;
+  return claims.ref === undefined || (typeof claims.ref === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(claims.ref));
+}
+/** Classifies only Supabase's low-privilege public API key shapes; ambiguous JWTs remain secrets. */
+export function supabasePublicKeyKind(value) {
+  const text = String(value ?? '');
+  if (SUPABASE_PUBLISHABLE.test(text)) return 'publishable key';
+  return isCanonicalSupabaseAnonJwt(text) ? 'anon key' : '';
+}
+/** The public Supabase local-development keys (issuer "supabase-demo") ship with every local stack and unlock nothing real. */
+export const isSupabaseDemoJwt = (value) => jwtClaims(value)?.iss === 'supabase-demo';
+
+const B64_CHAR = /[A-Za-z0-9+/=]/;
+export const BASE64_RUN_MIN = 200;
+/** True when every occurrence of `secret` in `line` is plain base64 with at least `min` base64 characters on each side (embedded WASM, images, fonts). */
+export function insideBase64Run(line, secret, min = BASE64_RUN_MIN) {
+  if (!secret || !/^[A-Za-z0-9+/=]+$/.test(secret)) return false;
+  let found = false;
+  for (let i = line.indexOf(secret); i >= 0; i = line.indexOf(secret, i + 1)) {
+    found = true;
+    let left = 0;
+    while (left < min && i - 1 - left >= 0 && B64_CHAR.test(line[i - 1 - left])) left++;
+    const end = i + secret.length;
+    let right = 0;
+    while (right < min && end + right < line.length && B64_CHAR.test(line[end + right])) right++;
+    if (left < min || right < min) return false;
+  }
+  return found;
+}
+
+/** Why a hit is not a finding ('' when it is): demo-jwt, base64-run, placeholder, local-uri or localization. */
+function suppressionOf(r, file, secret, readLine) {
+  if (isSupabaseDemoJwt(secret)) return 'demo-jwt';
+  const rule = r.RuleID ?? 'unknown';
+  // Betterleaks provider rules retain their guardrail; only generic/JWT-shaped detections get this shape classification.
+  if ((GENERIC_RULE.test(rule) || /^jwt(?:-|$)/i.test(rule)) && supabasePublicKeyKind(secret)) return 'supabase-public-key';
+  if (/^[A-Za-z0-9+/=]+$/.test(secret) && readLine) {
+    const line = readLine(file, r.StartLine);
+    if (line !== null && insideBase64Run(line, secret)) return 'base64-run';
+  }
+  if (isLocalizationNoise(rule, file, secret)) return 'localization';
+  if (GENERIC_RULE.test(rule)) {
+    if (isPlaceholderValue(secret)) return 'placeholder';
+    const host = uriHostOf(r);
+    if (host && isLocalHost(host)) return 'local-uri';
+  }
+  return '';
+}
+
+/** Reads one line of a file under root (cached per file); null when unreadable. Used only to look around a hit. */
+function lineReader(root) {
+  const cache = new Map();
+  return (file, line) => {
+    if (!cache.has(file)) {
+      try { cache.set(file, fs.readFileSync(path.join(root, file), 'utf8').split(/\r?\n/)); } catch { cache.set(file, null); }
+    }
+    const lines = cache.get(file);
+    return lines ? (Number.isInteger(line) && line > 0 ? lines[line - 1] ?? null : lines.join('\n')) : null;
+  };
+}
+
+/** One normalized hit: the secret itself is reduced to its redaction and a short hash. `suppressed` names why it is not a finding. */
+function toHit(r, cwd, readLine) {
+  const secret = String(r.Secret ?? '');
+  const publicKeyKind = supabasePublicKeyKind(secret);
+  let file = posix(r.File ?? r.Attributes?.path ?? '');
+  const root = posix(path.resolve(cwd)).replace(/\/$/, '');
+  if (file.toLowerCase().startsWith(`${root.toLowerCase()}/`)) file = file.slice(root.length + 1);
+  return {
+    ruleId: r.RuleID ?? 'unknown',
+    description: String(r.Description ?? ''),
+    file,
+    line: Number.isInteger(r.StartLine) && r.StartLine > 0 ? r.StartLine : undefined,
+    redacted: redact(secret),
+    hash: sha256(secret).slice(0, 12),
+    suppressed: suppressionOf(r, file, secret, readLine),
+    entropy: typeof r.Entropy === 'number' ? Math.round(r.Entropy * 100) / 100 : undefined,
+    confidence: ['high', 'medium', 'low'].includes(r.Attributes?.confidence) ? r.Attributes.confidence : 'medium',
+    validation: validationOf(r.ValidationStatus, r.ValidationReason),
+    ...(publicKeyKind ? { publicKeyKind } : {}),
+    commit: r.Commit ? String(r.Commit) : undefined,
+    date: r.Date ? String(r.Date) : undefined,
+  };
+}
+
+/** valid = live credential; inactive = checked and invalid or revoked; unvalidated = not checked or inconclusive. */
+export function validationOf(status, reason) {
+  const s = String(status ?? '').toLowerCase();
+  const state = s === 'valid' ? 'valid' : s === 'invalid' || s === 'revoked' ? 'inactive' : 'unvalidated';
+  return { state, status: s || 'none', reason: String(reason ?? '') };
+}
+
+/** Same secret, rule and file reported repeatedly (for example in several commits) becomes one hit with its commits. */
+function mergeHits(hits) {
+  const byKey = new Map();
+  for (const h of hits) {
+    const k = `${h.ruleId}\0${h.file}\0${h.hash}`;
+    const seen = byKey.get(k);
+    if (!seen) { byKey.set(k, { ...h, commits: h.commit ? [h.commit] : [] }); continue; }
+    if (h.commit && !seen.commits.includes(h.commit)) seen.commits.push(h.commit);
+    if (h.validation.state === 'valid') seen.validation = h.validation;
+  }
+  return [...byKey.values()].map(({ commit: _c, ...h }) => h);
+}
+
+/**
+ * Drops suppressed hits. Returns { hits, filtered (localization noise, the original counter), suppressed (counts per reason, distinct hits),
+ * demoJwts ([{ file, line }] for the Supabase local demo key, reported once as info), and publicKeys }.
+ */
+function dropNoise(hits) {
+  const suppressed = { placeholder: 0, localUri: 0, base64Run: 0, demoJwt: 0, publicKey: 0 };
+  const key = { placeholder: 'placeholder', 'local-uri': 'localUri', 'base64-run': 'base64Run', 'demo-jwt': 'demoJwt', 'supabase-public-key': 'publicKey' };
+  const demoJwts = [];
+  const publicKeys = [];
+  let filtered = 0;
+  const kept = [];
+  for (const { suppressed: why, ...h } of hits) {
+    if (!why) kept.push(h);
+    else if (why === 'localization') filtered++;
+    else {
+      suppressed[key[why]]++;
+      if (why === 'demo-jwt') demoJwts.push({ file: h.file, line: h.line });
+      if (why === 'supabase-public-key') publicKeys.push({ file: h.file, line: h.line, kind: h.publicKeyKind });
+    }
+  }
+  return { hits: kept, filtered, suppressed, demoJwts, publicKeys };
+}
+
+/**
+ * Runs Betterleaks. kind: 'dir' (paths relative to cwd), 'git' (full history of cwd) or 'stdin' (input).
+ * Returns { status: 'ran', hits, filtered, suppressed, demoJwts, publicKeys } (see dropNoise) or { status: 'not_run', reason }. Exit 0 and 1 (leaks found) are success; anything else is a tool failure.
+ */
+export async function runBetterleaks(ctx, { kind, paths = ['.'], cwd = ctx.repo, input, validate = false, skip = ALWAYS_SKIP, timeoutSec }) {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'vsg-bl-'));
+  try {
+    const cfg = path.join(work, 'betterleaks.toml');
+    // other checkouts inside the scanned tree (worktrees, clones) are not this repository; a history scan never reads them by path
+    const nested = kind === 'dir' && cwd === ctx.repo ? (ctx.nestedRepos ?? []).map((n) => `^${escapeRe(n.path)}/`) : [];
+    fs.writeFileSync(cfg, configToml([...skip, ...nested.filter((p) => !p.includes("'''"))]));
+    const args = [kind, '--no-banner', '--no-color', '-l', 'error', '-c', cfg, '-i', work, '--ignore-gitleaks-allow',
+      '--max-target-megabytes', '10', '-f', 'json', '-r', '-', ...(validate ? ['--validation'] : [])];
+    if (kind === 'dir') args.push(...paths);
+    if (kind === 'git') args.push('.');
+    const res = await ctx.runTool(TOOL, args, { cwd, input, timeoutSec });
+    if (res.status !== 'ran') return { status: 'not_run', reason: res.reason };
+    if (res.truncated) return { status: 'not_run', reason: 'Betterleaks output was too large to read completely.' };
+    if (res.exitCode !== 0 && res.exitCode !== 1) {
+      const tail = scrubText(res.stderr.trim().split(/\r?\n/).slice(-2).join(' | '));
+      return { status: 'not_run', reason: `Betterleaks failed with exit code ${res.exitCode}${tail ? `: ${tail}` : ''}.` };
+    }
+    let parsed;
+    try { parsed = res.stdout.trim() ? JSON.parse(res.stdout) : []; } catch { return { status: 'not_run', reason: 'Betterleaks did not return valid JSON.' }; }
+    if (!Array.isArray(parsed)) return { status: 'not_run', reason: 'Betterleaks returned an unexpected report shape.' };
+    const readLine = kind === 'dir' ? lineReader(cwd) : null;
+    return { status: 'ran', ...dropNoise(mergeHits(parsed.map((r) => toHit(r, cwd, readLine)))) };
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** Reusable for the live stage: scans a directory (for example downloaded JavaScript). Paths in hits are relative to dir. */
+export const scanSecretsInDirectory = (ctx, dir, { validate = false, skip = ALWAYS_SKIP } = {}) =>
+  runBetterleaks(ctx, { kind: 'dir', paths: ['.'], cwd: path.resolve(dir), validate, skip });
+
+/** Reusable for the live stage: scans one in-memory document. `name` is reported as the file (for example the script URL path). */
+export async function scanSecretsInBuffer(ctx, buffer, { name = 'stdin', validate = false } = {}) {
+  const res = await runBetterleaks(ctx, { kind: 'stdin', input: buffer, validate });
+  if (res.status === 'ran') for (const h of res.hits) h.file = name;
+  return res;
+}
+
+const CONFIDENCE = { high: 'high', medium: 'medium', low: 'low' };
+
+export const isGenericRule = (ruleId) => GENERIC_RULE.test(ruleId);
+export const LOW_ENTROPY = 3.5;
+/** A generic catch-all hit that is not a validated live credential and is low confidence or low entropy: reported, but it cannot block. */
+export const isLowSignalGeneric = (hit) => GENERIC_RULE.test(hit.ruleId) && hit.validation.state !== 'valid'
+  && (hit.confidence === 'low' || (hit.entropy !== undefined && hit.entropy < LOW_ENTROPY));
+
+/** The severity a hit is reported at: low-signal generic hits are capped at Medium. */
+export const effectiveSeverity = (hit, severity) => (isLowSignalGeneric(hit) && severityRank(severity) > severityRank('medium') ? 'medium' : severity);
+
+/**
+ * Raw finding (input for makeFinding) from a hit. Nothing here can carry the secret: evidence is the redaction.
+ * opts: { category, severity, where (words), fix }
+ */
+export function hitToFinding(hit, { category, severity, where, fix, extra = '' }) {
+  const state = hit.validation.state;
+  const confidence = state === 'valid' ? 'confirmed' : CONFIDENCE[hit.confidence] ?? 'medium';
+  const verdict = state === 'valid' ? ' Betterleaks confirmed this credential is live.'
+    : state === 'inactive' ? ` Betterleaks checked it and the issuer reports it inactive (${hit.validation.status}).` : '';
+  const low = isLowSignalGeneric(hit);
+  const lowNote = low ? ` Low-signal generic match (${hit.confidence === 'low' ? 'confidence low' : `entropy ${hit.entropy}, under ${LOW_ENTROPY}`}): reported as Medium and does not block. Check whether it is a real credential.` : '';
+  return {
+    category, severity: effectiveSeverity(hit, severity), confidence, tool: TOOL, ruleId: hit.ruleId, key: `${hit.ruleId}:${hit.hash}`,
+    location: { file: hit.file, line: hit.line },
+    title: `Secret ${where}: ${hit.ruleId}`,
+    description: `${hit.description || `Betterleaks rule ${hit.ruleId} matched.`}${verdict}${lowNote}${extra}`,
+    evidence: `${hit.redacted} (rule ${hit.ruleId}${hit.entropy !== undefined ? `, entropy ${hit.entropy}` : ''})`,
+    refs: [],
+    fix,
+  };
+}
+
+/** One info finding for the Supabase local demo key (public, ships with every local stack), or null when the scan saw none. */
+export function demoJwtFinding(demoJwts, { category = 'secret', where }) {
+  if (!demoJwts?.length) return null;
+  const shown = demoJwts.slice(0, 10).map((d) => `${d.file}${d.line ? `:${d.line}` : ''}`);
+  return {
+    category, severity: 'info', confidence: 'high', tool: TOOL, ruleId: 'supabase-demo-jwt', key: 'supabase-demo-jwt',
+    location: { file: demoJwts[0].file, line: demoJwts[0].line },
+    title: `Supabase local demo key ${where}`,
+    description: 'A JWT whose issuer is "supabase-demo" is the public development key every local Supabase stack ships with. It unlocks nothing outside a local stack, so it is not a secret. Reported once.',
+    evidence: `${demoJwts.length} occurrence(s): ${shown.join(', ')}${demoJwts.length > shown.length ? `, and ${demoJwts.length - shown.length} more` : ''}`,
+    refs: [], fix: 'No action needed. Make sure no real project key sits next to it.',
+  };
+}
+
+/** One info finding for Supabase anon/publishable keys, which are intended for public clients. */
+export function supabasePublicKeyFinding(publicKeys, { category = 'secret', where }) {
+  if (!publicKeys?.length) return null;
+  const shown = publicKeys.slice(0, 10).map((k) => `${k.kind ?? 'public key'} at ${k.file}${k.line ? `:${k.line}` : ''}`);
+  return {
+    category, severity: 'info', confidence: 'high', tool: TOOL, ruleId: 'supabase-public-key', key: 'supabase-public-key',
+    location: { file: publicKeys[0].file, line: publicKeys[0].line },
+    title: `Supabase public key ${where}`,
+    description: 'A Supabase anon or publishable API key is intended for public clients and does not grant elevated access. Keep Row Level Security and least-privilege grants enabled.',
+    evidence: `${publicKeys.length} occurrence(s): ${shown.join(', ')}${publicKeys.length > shown.length ? `, and ${publicKeys.length - shown.length} more` : ''}`,
+    refs: [], fix: 'No secret rotation is needed for this public key. Confirm the project uses Row Level Security and least-privilege grants.',
+  };
+}
+
+export const ROTATE = 'Treat the value as exposed: revoke or rotate it at the issuer first, then remove it from the code and load it from an environment variable or a secret manager.';

package/dist/security-runtime/src/checks/_lib/targets.mjs

@@ -0,0 +1,79 @@
+// Explicit scan targets for tools that walk "." themselves. Opengrep (with --no-git-ignore) and Betterleaks still traverse a directory they
+// are told to exclude, so a tree with 100 agent worktrees (millions of node_modules files) takes tens of minutes even though every file in
+// them is excluded. Handing the tool the directory's entries instead, and leaving the dropped paths out, avoids that traversal.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ignoredUntracked } from '../../core/nested.mjs';
+
+const MAX_TARGETS = 600; // keep the command line short; past this the plain "." scan (with its exclusions) is the safer choice
+
+/**
+ * Same as scanTargets, and when `skipIgnored` is set also leaves out the directories among the targets that git ignores and the repository
+ * does not track (build output, browser profiles). Returns { targets, ignoredDirs, prunedDirs } (prunedDirs: pruned-name directories below
+ * the top level that were left out, for the coverage evidence).
+ */
+export function scanTargetsWithIgnored(repo, dropPaths, pruneNames, skipIgnored) {
+  const { targets, prunedDirs } = planTargets(repo, dropPaths, pruneNames);
+  if (!skipIgnored || targets[0] === '.') return { targets, ignoredDirs: [], prunedDirs };
+  const isDir = (t) => { try { return fs.statSync(path.join(repo, t)).isDirectory(); } catch { return false; } };
+  const rel = (t) => (t.startsWith('./') ? t.slice(2) : t);
+  const ignoredDirs = ignoredUntracked(repo, targets.filter(isDir).map(rel));
+  const out = targets.filter((t) => !ignoredDirs.includes(rel(t)));
+  return out.length ? { targets: out, ignoredDirs, prunedDirs } : { targets, ignoredDirs: [], prunedDirs };
+}
+
+const MAX_DEPTH = 10;
+
+/**
+ * Directories named in `pruneNames` that sit below the top level (for example an untracked project's own node_modules), as root-relative
+ * posix paths. Opengrep still walks a directory it is told to exclude (40,000 files of one nested node_modules cost 40 seconds), so these
+ * are left out of the targets as well. Does not enter them, nested checkouts (`skip`) or symbolic links.
+ */
+function innerPruned(repo, skip, prune) {
+  const found = [];
+  const walk = (rel, depth) => {
+    if (depth > MAX_DEPTH) return;
+    let entries;
+    try { entries = fs.readdirSync(path.join(repo, rel), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isSymbolicLink() || !e.isDirectory()) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (skip.has(r)) continue;
+      if (prune.has(e.name)) { if (rel) found.push(r); continue; }
+      walk(r, depth + 1);
+    }
+  };
+  walk('', 0);
+  return found;
+}
+
+/**
+ * Root-relative targets ("./a/b") that cover everything under `repo` except `dropPaths` (root-relative posix paths), any directory
+ * named in `pruneNames` at the top level, and any such directory deeper down (see innerPruned). Only directories that contain a dropped
+ * path are expanded; every other entry is handed over whole.
+ * Returns ["."] when nothing is dropped, so an ordinary repository is scanned exactly as before.
+ */
+export const scanTargets = (repo, dropPaths = [], pruneNames = []) => planTargets(repo, dropPaths, pruneNames).targets;
+
+/** scanTargets plus the pruned directories found below the top level: { targets, prunedDirs }. */
+export function planTargets(repo, dropPaths = [], pruneNames = []) {
+  const prune = new Set(pruneNames);
+  const prunedDirs = prune.size ? innerPruned(repo, new Set(dropPaths), prune) : [];
+  const drop = new Set([...dropPaths, ...prunedDirs]);
+  if (!drop.size) return { targets: ['.'], prunedDirs: [] };
+  const ancestors = new Set();
+  for (const p of drop) for (let i = p.indexOf('/'); i > 0; i = p.indexOf('/', i + 1)) ancestors.add(p.slice(0, i));
+  const targets = [];
+  const expand = (rel) => {
+    let entries;
+    try { entries = fs.readdirSync(path.join(repo, rel), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isSymbolicLink() || drop.has(r) || (e.isDirectory() && prune.has(e.name))) continue;
+      if (e.isDirectory() && ancestors.has(r)) expand(r);
+      else targets.push(r.startsWith('-') ? `./${r}` : r); // plain relative paths: a path allowlist is anchored on them, so "./" would defeat it
+    }
+  };
+  expand('');
+  return targets.length && targets.length <= MAX_TARGETS ? { targets, prunedDirs } : { targets: ['.'], prunedDirs: [] };
+}

package/dist/security-runtime/src/checks/agent-review/index.mjs

@@ -0,0 +1,52 @@
+// agent-review (REQ-027, REQ-028, REQ-029): writes the agent brief, optionally runs the configured headless reviewer, and ingests
+// <out>/agent/findings.json. Until that file exists the check is not_run, so `deep` is INCOMPLETE until the review is done.
+// vsg never calls an LLM itself. `agentReview.command` in vsg.config.json is run exactly as configured, without a shell.
+import fs from 'node:fs';
+import { renderBrief } from '../../agent/brief.mjs';
+import { runCommandString } from '../../agent/exec.mjs';
+import { agentDir, awaitingReason, briefPath, findingsPath, ingestAgentFindings, reviewIdentity, reviewIdentityError, reviewMetaPath, rotateFindings } from '../../agent/ingest.mjs';
+import { packageRoot } from '../../core/paths.mjs';
+import { scrubText } from '../../core/findings.mjs';
+
+export const id = 'agent-review';
+export const title = 'Agent review (brief and findings ingestion)';
+export const modes = ['deep', 'release'];
+export const requiredIn = ['deep', 'release'];
+export const HOOK_TIMEOUT_MS = 30 * 60 * 1000;
+// the hook, then up to 20 reproduction commands of up to 2 minutes each, plus slack
+export const timeoutSec = HOOK_TIMEOUT_MS / 1000 + 20 * 120 + 300;
+/** Runs after the other checks, so the brief can list this run's scanner findings. */
+export const last = true;
+export const applies = () => true;
+
+const rank = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+
+export async function run(ctx) {
+  const dir = agentDir(ctx.out);
+  fs.mkdirSync(dir, { recursive: true });
+  // Every deep/release run starts a fresh review. Keep any manually supplied findings recoverable, even when no hook is configured.
+  rotateFindings(ctx.out);
+  const identity = reviewIdentity(ctx.repo, ctx.runId, ctx.out);
+  fs.writeFileSync(reviewMetaPath(ctx.out), `${JSON.stringify(identity, null, 2)}\n`);
+  const prior = (ctx.priorFindings?.() ?? []).sort((a, b) => Number(b.blocking) - Number(a.blocking) || rank[a.severity] - rank[b.severity] || a.fingerprint.localeCompare(b.fingerprint));
+  fs.writeFileSync(briefPath(ctx.out), renderBrief({ repo: ctx.repo, out: ctx.out, mode: ctx.mode, detection: ctx.detection, findings: prior, vsgVersion: ctx.vsgVersion ?? '0.0.0', vsgRoot: packageRoot }));
+  ctx.log(`agent brief written to ${briefPath(ctx.out)}`);
+
+  const command = ctx.config?.agentReview?.command;
+  if (command) {
+    const extra = (process.env.VSG_AGENT_ENV ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    const r = await runCommandString(ctx.runProcess, command, {
+      repo: ctx.repo, timeoutMs: HOOK_TIMEOUT_MS, envNames: extra,
+      extraEnv: { VSG_AGENT_BRIEF: briefPath(ctx.out), VSG_AGENT_FINDINGS: findingsPath(ctx.out) },
+    });
+    if (r.status !== 'ran') return { status: 'not_run', reason: `agentReview.command did not run to completion: ${scrubText(r.reason)}. ${awaitingReason(ctx.out)}` };
+    if (r.exitCode !== 0) return { status: 'not_run', reason: `agentReview.command exited with code ${r.exitCode}. ${awaitingReason(ctx.out)}` };
+    if (!fs.existsSync(findingsPath(ctx.out))) return { status: 'not_run', reason: `agentReview.command finished but wrote no findings file. ${awaitingReason(ctx.out)}` };
+  }
+  const identityProblem = reviewIdentityError({ repo: ctx.repo, out: ctx.out });
+  if (identityProblem) return { status: 'not_run', reason: identityProblem };
+  const res = await ingestAgentFindings({ repo: ctx.repo, out: ctx.out, runProcess: ctx.runProcess, note: ctx.log });
+  return res;
+}
+
+export default { id, title, modes, requiredIn, timeoutSec, last, applies, run };