@torus-engineering/tas-kit 1.8.0 → 1.10.0

package/.tas/hooks/security-scan.js

@@ -0,0 +1,599 @@
+#!/usr/bin/env node
+/**
+ * TAS Kit — Pre-commit Security Scanner
+ *
+ * Invoked by the pre-commit hook (husky or native .git/hooks).
+ *
+ * Flow (3-tier):
+ *   Tier 1 (always, blocking):     Fast regex scan of staged files — hardcoded
+ *                                  secrets, AWS/Azure/GCP keys, private keys.
+ *   Tier 2 (if on PATH, blocking): External scanner — gitleaks / trufflehog.
+ *                                  Runs only when found on PATH.
+ *   Tier 3 (opt-in, LOCAL-ONLY, REPORT-ONLY):
+ *                                  AI deep scan via claude / codex / gemini.
+ *                                  Triggered only by `deep_scan_on_every_commit:
+ *                                  true` in tas.yaml. Writes findings to
+ *                                  docs/security-report.md. Never blocks the
+ *                                  commit. Intended for local runs (using a
+ *                                  dev's personal Claude Code subscription —
+ *                                  no API charges). Dev can choose to include
+ *                                  the report file in their PR if they want
+ *                                  reviewers to see the deep-scan output.
+ *
+ *   Exit 1 only if Tier 1/2 findings match `block_on`. Tier 3 never blocks.
+ *
+ * Bypass: SKIP_SECURITY_SCAN=1 git commit ...  OR  git commit --no-verify
+ *
+ * This script is intentionally dependency-free (vanilla Node only).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync, spawnSync } = require('child_process');
+
+// ─── Bypass ──────────────────────────────────────────────────────────────────
+if (process.env.SKIP_SECURITY_SCAN === '1' || process.env.TAS_SKIP_SECURITY === '1') {
+  console.log('[TAS Security] Scan skipped via SKIP_SECURITY_SCAN env var');
+  process.exit(0);
+}
+
+// ─── Locate repo root ────────────────────────────────────────────────────────
+function findRepoRoot(start) {
+  let dir = path.resolve(start);
+  for (let i = 0; i < 20; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+const repoRoot = findRepoRoot(process.cwd());
+if (!repoRoot) {
+  console.log('[TAS Security] Not inside a git repo, skipping');
+  process.exit(0);
+}
+
+// ─── Config loader (minimal YAML reader for `security:` section only) ────────
+function loadConfig(root) {
+  const defaults = {
+    pre_commit_hook: true,
+    tool: 'claude',
+    external_scanner: 'auto',
+    deep_scan_on_every_commit: false,
+    block_on: ['critical', 'high'],
+    allow_bypass: true,
+  };
+  const p = path.join(root, 'tas.yaml');
+  if (!fs.existsSync(p)) return defaults;
+
+  const content = fs.readFileSync(p, 'utf8');
+  const secMatch = content.match(/^security:\s*\n((?:[ \t]+.*\n?)+)/m);
+  if (!secMatch) return defaults;
+
+  const body = secMatch[1];
+  const cfg = { ...defaults };
+
+  const getRaw = (key) => {
+    const m = body.match(new RegExp(`^[ \\t]+${key}:[ \\t]*(.+?)[ \\t]*$`, 'm'));
+    if (!m) return null;
+    // Strip YAML trailing comment (# outside of quotes)
+    let v = m[1];
+    const hashAt = v.indexOf('#');
+    if (hashAt >= 0) {
+      const before = v.slice(0, hashAt);
+      const dquotes = (before.match(/"/g) || []).length;
+      const squotes = (before.match(/'/g) || []).length;
+      if (dquotes % 2 === 0 && squotes % 2 === 0) {
+        v = before;
+      }
+    }
+    return v.trim();
+  };
+  const asBool = (v) => (v == null ? null : /^(true|yes|on)$/i.test(v));
+  const asStr = (v) => (v == null ? null : v.replace(/^['"]|['"]$/g, '').trim());
+  const asList = (v) => {
+    if (v == null) return null;
+    return v.replace(/^\[|\]$/g, '')
+      .split(',')
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, '').toLowerCase())
+      .filter(Boolean);
+  };
+
+  const b1 = asBool(getRaw('pre_commit_hook'));
+  if (b1 !== null) cfg.pre_commit_hook = b1;
+
+  const t = asStr(getRaw('tool'));
+  if (t) cfg.tool = t.toLowerCase();
+
+  const ext = asStr(getRaw('external_scanner'));
+  if (ext) cfg.external_scanner = ext.toLowerCase();
+
+  const b2 = asBool(getRaw('deep_scan_on_every_commit'));
+  if (b2 !== null) cfg.deep_scan_on_every_commit = b2;
+
+  const arr = asList(getRaw('block_on'));
+  if (arr) cfg.block_on = arr;
+
+  const b3 = asBool(getRaw('allow_bypass'));
+  if (b3 !== null) cfg.allow_bypass = b3;
+
+  return cfg;
+}
+
+const cfg = loadConfig(repoRoot);
+if (cfg.pre_commit_hook === false) {
+  console.log('[TAS Security] Pre-commit hook disabled in tas.yaml');
+  process.exit(0);
+}
+
+// ─── Read staged files ───────────────────────────────────────────────────────
+function git(args) {
+  try {
+    return execSync(`git ${args}`, { cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+  } catch {
+    return '';
+  }
+}
+
+const stagedRaw = git('diff --cached --name-only --diff-filter=ACM');
+const staged = stagedRaw.split('\n').filter(Boolean);
+
+if (staged.length === 0) {
+  console.log('[TAS Security] No staged files, skipping');
+  process.exit(0);
+}
+
+// ─── Fast regex patterns ─────────────────────────────────────────────────────
+const PATTERNS = [
+  // ── Cloud provider credentials ─────────────────────────────────────────────
+  { id: 'aws_access_key', re: /\bAKIA[0-9A-Z]{16}\b/, severity: 'critical', label: 'AWS Access Key' },
+  { id: 'aws_secret_key', re: /aws(.{0,20})?(secret|access)(.{0,20})?[:=]\s*['"][A-Za-z0-9/+=]{40}['"]/i, severity: 'critical', label: 'AWS Secret Key' },
+  { id: 'azure_storage_key', re: /AccountKey\s*=\s*[A-Za-z0-9+/=]{80,}/i, severity: 'critical', label: 'Azure Storage Account Key' },
+  { id: 'azure_conn_string', re: /DefaultEndpointsProtocol\s*=\s*https?;AccountName\s*=\s*[A-Za-z0-9]+;AccountKey\s*=/i, severity: 'critical', label: 'Azure Storage Connection String' },
+  { id: 'gcp_service_account', re: /"type"\s*:\s*"service_account"\s*,[\s\S]{0,200}"private_key"\s*:/, severity: 'critical', label: 'GCP Service Account JSON' },
+  { id: 'google_api', re: /\bAIza[0-9A-Za-z_-]{35}\b/, severity: 'critical', label: 'Google API Key' },
+  { id: 'digitalocean_token', re: /\bdop_v1_[a-f0-9]{64}\b/, severity: 'critical', label: 'DigitalOcean Personal Access Token' },
+  { id: 'cloudflare_token', re: /\b[A-Za-z0-9_-]{40}\b(?=.{0,30}(cloudflare|cf[_-]?token|cf[_-]?api))/i, severity: 'high', label: 'Cloudflare API Token (heuristic)' },
+  { id: 'heroku_key', re: /heroku[a-zA-Z0-9_ .\-,]{0,25}[:=]\s*['"][0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}['"]/i, severity: 'critical', label: 'Heroku API Key' },
+
+  // ── VCS / Package registries ───────────────────────────────────────────────
+  { id: 'github_token', re: /\bgh[opsur]_[A-Za-z0-9]{30,}\b/, severity: 'critical', label: 'GitHub Token' },
+  { id: 'github_fine_grained', re: /\bgithub_pat_[A-Za-z0-9_]{70,}\b/, severity: 'critical', label: 'GitHub Fine-grained PAT' },
+  { id: 'gitlab_token', re: /\bglpat-[A-Za-z0-9_-]{20,}\b/, severity: 'critical', label: 'GitLab Personal Access Token' },
+  { id: 'npm_token', re: /\bnpm_[A-Za-z0-9]{36}\b/, severity: 'critical', label: 'npm Token' },
+  { id: 'pypi_token', re: /\bpypi-AgEIcHlwaS5vcmc[A-Za-z0-9_-]{50,}\b/, severity: 'critical', label: 'PyPI Token' },
+
+  // ── AI provider keys ───────────────────────────────────────────────────────
+  { id: 'openai_key', re: /\bsk-(proj-)?[A-Za-z0-9_-]{20,}T3BlbkFJ[A-Za-z0-9_-]{20,}\b/, severity: 'critical', label: 'OpenAI API Key' },
+  { id: 'openai_key_legacy', re: /\bsk-[A-Za-z0-9]{48}\b/, severity: 'critical', label: 'OpenAI API Key (legacy)' },
+  { id: 'anthropic_key', re: /\bsk-ant-(api|admin)[0-9]{2}-[A-Za-z0-9_-]{80,}\b/, severity: 'critical', label: 'Anthropic API Key' },
+
+  // ── Payments ───────────────────────────────────────────────────────────────
+  { id: 'stripe_live', re: /\b(sk|rk)_live_[0-9a-zA-Z]{24,}\b/, severity: 'critical', label: 'Stripe Live Secret Key' },
+  { id: 'stripe_test', re: /\b(sk|rk)_test_[0-9a-zA-Z]{24,}\b/, severity: 'high', label: 'Stripe Test Key' },
+  { id: 'stripe_publishable', re: /\bpk_(live|test)_[0-9a-zA-Z]{24,}\b/, severity: 'medium', label: 'Stripe Publishable Key (OK in frontend, not in backend)' },
+  { id: 'square_token', re: /\bsq0(atp|csp|idp)-[A-Za-z0-9_-]{22,}\b/, severity: 'critical', label: 'Square Access Token' },
+  { id: 'paypal_braintree', re: /\baccess_token\$production\$[0-9a-z]{16}\$[0-9a-f]{32}\b/, severity: 'critical', label: 'Braintree Production Token' },
+
+  // ── Messaging / Email ──────────────────────────────────────────────────────
+  { id: 'slack_token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/, severity: 'critical', label: 'Slack Token' },
+  { id: 'slack_webhook', re: /\bhttps:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]{20,}\b/, severity: 'high', label: 'Slack Webhook URL' },
+  { id: 'discord_bot', re: /\b[MN][A-Za-z\d]{23}\.[\w-]{6}\.[\w-]{27,}\b/, severity: 'critical', label: 'Discord Bot Token' },
+  { id: 'discord_webhook', re: /\bhttps:\/\/(canary\.|ptb\.)?discord(app)?\.com\/api\/webhooks\/\d{17,19}\/[\w-]{60,}\b/, severity: 'high', label: 'Discord Webhook URL' },
+  { id: 'twilio_sid', re: /\bAC[a-f0-9]{32}\b/, severity: 'high', label: 'Twilio Account SID' },
+  { id: 'twilio_auth', re: /\bSK[a-f0-9]{32}\b/, severity: 'critical', label: 'Twilio Auth Token / API Key' },
+  { id: 'sendgrid', re: /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/, severity: 'critical', label: 'SendGrid API Key' },
+  { id: 'mailgun', re: /\bkey-[0-9a-zA-Z]{32}\b/, severity: 'critical', label: 'Mailgun API Key' },
+  { id: 'mailchimp', re: /\b[0-9a-f]{32}-us[0-9]{1,2}\b/, severity: 'critical', label: 'Mailchimp API Key' },
+  { id: 'postmark', re: /\bPOSTMARK_[A-Z_]*TOKEN\s*[:=]\s*['"][0-9a-f-]{36}['"]/i, severity: 'critical', label: 'Postmark Token' },
+
+  // ── Keys / certificates ────────────────────────────────────────────────────
+  { id: 'private_key', re: /-----BEGIN (RSA |OPENSSH |EC |DSA |PGP |ENCRYPTED )?PRIVATE KEY-----/, severity: 'critical', label: 'Private Key' },
+  { id: 'ssh_key', re: /\bssh-(rsa|ed25519|dss) AAAA[A-Za-z0-9+/=]{100,}\b/, severity: 'high', label: 'SSH Public Key (context check)' },
+  { id: 'pgp_private', re: /-----BEGIN PGP PRIVATE KEY BLOCK-----/, severity: 'critical', label: 'PGP Private Key Block' },
+
+  // ── Connection strings & auth patterns ────────────────────────────────────
+  { id: 'connection_string', re: /(mongodb(\+srv)?|mysql|postgres(ql)?|redis|amqp|amqps):\/\/[^:\s'"]+:[^@\s'"]+@/i, severity: 'high', label: 'DB/MQ Connection String with Credentials' },
+  { id: 'jdbc_password', re: /jdbc:[a-z]+:\/\/[^?\s]+\?.*password=[^&\s'"]+/i, severity: 'high', label: 'JDBC URL with Password' },
+  { id: 'basic_auth_url', re: /\bhttps?:\/\/[A-Za-z0-9._~-]+:[A-Za-z0-9._~%+-]{6,}@[A-Za-z0-9.-]+/, severity: 'high', label: 'HTTP Basic Auth in URL' },
+
+  // ── Generic catch-all (looser, more false positives possible) ──────────────
+  { id: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/, severity: 'high', label: 'JWT Token' },
+  { id: 'generic_secret', re: /\b(api[_-]?key|secret[_-]?key|password|passwd|auth[_-]?token|access[_-]?token|bearer[_-]?token|client[_-]?secret)\b\s*[:=]\s*['"][A-Za-z0-9_\-!@#$%^&*+/=]{12,}['"]/i, severity: 'high', label: 'Hardcoded Secret' },
+  { id: 'authorization_header', re: /authorization\s*[:=]\s*['"]\s*(bearer|basic)\s+[A-Za-z0-9+/=_.-]{20,}['"]/i, severity: 'high', label: 'Authorization Header with Credentials' },
+];
+
+// ── Placeholders to ignore (reduces false positives from docs/examples) ──────
+const PLACEHOLDER_HINTS = [
+  /\bexample\b/i, /\bplaceholder\b/i, /\bxxxxxxxx\b/, /\bchange[_-]?me\b/i,
+  /\byour[_-]?(api|key|token|secret)/i, /\bfake\b/i, /\bdummy\b/i, /<your/i,
+];
+
+// Files we shouldn't scan byte-for-byte
+const SKIP_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.pdf', '.zip', '.gz', '.tar', '.dll', '.exe', '.bin', '.woff', '.woff2', '.ttf', '.eot']);
+
+const findings = [];
+
+for (const file of staged) {
+  const lower = file.toLowerCase();
+  const basename = path.basename(lower);
+
+  // .env files staged (allow .env.example / .env.sample)
+  if (/^\.env(\..+)?$/.test(basename) && !/\.(example|sample|template)$/.test(basename)) {
+    findings.push({ file, line: 0, severity: 'critical', label: '.env file staged for commit', match: file });
+    continue;
+  }
+
+  const ext = path.extname(lower);
+  if (SKIP_EXT.has(ext)) continue;
+
+  const full = path.join(repoRoot, file);
+  if (!fs.existsSync(full)) continue;
+
+  let stat;
+  try { stat = fs.statSync(full); } catch { continue; }
+  if (stat.size > 2 * 1024 * 1024) continue;
+
+  let content;
+  try { content = fs.readFileSync(full, 'utf8'); } catch { continue; }
+
+  const lines = content.split('\n');
+  for (const pat of PATTERNS) {
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.length > 500) continue;
+      const m = pat.re.exec(line);
+      if (!m) continue;
+
+      // Skip obvious placeholders (docs, examples, templates)
+      if (PLACEHOLDER_HINTS.some((h) => h.test(line))) continue;
+
+      findings.push({
+        file,
+        line: i + 1,
+        severity: pat.severity,
+        label: pat.label,
+        match: m[0].length > 40 ? m[0].slice(0, 37) + '...' : m[0],
+      });
+    }
+  }
+}
+
+// ─── Tier 2: External scanner (gitleaks / trufflehog, if on PATH) ────────────
+function commandExists(bin) {
+  const probe = process.platform === 'win32' ? 'where' : 'command';
+  const args = process.platform === 'win32' ? [bin] : ['-v', bin];
+  try {
+    const res = spawnSync(probe, args, {
+      stdio: 'ignore',
+      shell: process.platform !== 'win32',
+      timeout: 5000,
+    });
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+const EXTERNAL_SCANNERS = {
+  gitleaks: {
+    bin: 'gitleaks',
+    run: (root) => {
+      // gitleaks v8.30+: `git --staged` is canonical. (Older `protect --staged`
+      // was deprecated and removed.) --pre-commit flag is implicit with --staged.
+      const res = spawnSync('gitleaks', [
+        'git', '--staged', '--no-banner', '--redact', '--no-color', '-v',
+      ], { cwd: root, encoding: 'utf8', timeout: 60_000 });
+      if (res.error) return null;
+      if (res.status === 0) return { findings: [], raw: '' };
+      const out = (res.stdout || '') + (res.stderr || '');
+      const clean = out.replace(/\x1b\[[0-9;]*m/g, ''); // strip any residual ANSI
+      const countMatch = clean.match(/leaks?\s+found:\s*(\d+)/i);
+      const count = countMatch ? parseInt(countMatch[1], 10) : 1;
+      const items = [];
+      // Gitleaks finding block:
+      //   Finding: ...
+      //   Secret:  ...
+      //   RuleID:  <id>
+      //   ...
+      //   File:    <path>
+      //   Line:    <n>
+      const re = /RuleID:\s*(\S+)[\s\S]*?File:\s*(\S+)[\s\S]*?Line:\s*(\d+)/g;
+      let m;
+      while ((m = re.exec(clean)) !== null) {
+        items.push({
+          file: m[2].replace(/\\/g, '/'),
+          line: parseInt(m[3], 10) || 0,
+          severity: 'critical',
+          label: `gitleaks: ${m[1]}`,
+          match: 'external',
+        });
+      }
+      if (items.length === 0) {
+        items.push({
+          file: 'gitleaks',
+          line: 0,
+          severity: 'critical',
+          label: `gitleaks reported ${count} leak(s)`,
+          match: 'see output',
+        });
+      }
+      return { findings: items, raw: clean };
+    },
+  },
+  trufflehog: {
+    bin: 'trufflehog',
+    run: (root, stagedFiles) => {
+      if (!stagedFiles.length) return { findings: [], raw: '' };
+      const existing = stagedFiles
+        .filter((f) => fs.existsSync(path.join(root, f)))
+        .map((f) => path.join(root, f));
+      if (!existing.length) return { findings: [], raw: '' };
+      const res = spawnSync('trufflehog', [
+        'filesystem', '--json', '--no-update', '--fail', ...existing,
+      ], { cwd: root, encoding: 'utf8', timeout: 60_000 });
+      if (res.error) return null;
+      if (res.status === 0) return { findings: [], raw: '' };
+      const items = [];
+      const out = res.stdout || '';
+      for (const line of out.split('\n')) {
+        if (!line.trim()) continue;
+        try {
+          const obj = JSON.parse(line);
+          const fileMeta = obj.SourceMetadata?.Data?.Filesystem || {};
+          const relFile = (fileMeta.file || '').replace(root + path.sep, '').replace(/\\/g, '/');
+          items.push({
+            file: relFile || 'trufflehog',
+            line: fileMeta.line || 0,
+            severity: obj.Verified ? 'critical' : 'high',
+            label: `trufflehog: ${obj.DetectorName}${obj.Verified ? ' (VERIFIED live)' : ''}`,
+            match: (obj.Raw || '').slice(0, 30),
+          });
+        } catch {
+          /* skip non-JSON line */
+        }
+      }
+      if (items.length === 0 && res.status !== 0) {
+        items.push({
+          file: 'trufflehog',
+          line: 0,
+          severity: 'critical',
+          label: 'trufflehog reported findings',
+          match: 'see output',
+        });
+      }
+      return { findings: items, raw: (res.stderr || '') };
+    },
+  },
+};
+
+function runExternalScanner() {
+  const pref = (cfg.external_scanner || 'auto').toLowerCase();
+  if (pref === 'none') return;
+
+  const order = pref === 'auto' ? ['gitleaks', 'trufflehog'] : [pref];
+  for (const name of order) {
+    const scanner = EXTERNAL_SCANNERS[name];
+    if (!scanner) {
+      if (pref !== 'auto') console.warn(`[TAS Security] Unknown external_scanner "${pref}"`);
+      continue;
+    }
+    if (!commandExists(scanner.bin)) {
+      if (pref !== 'auto') {
+        console.warn(`[TAS Security] external_scanner="${name}" not on PATH — skipping tier 2`);
+      }
+      continue;
+    }
+    console.log(`[TAS Security] Running tier 2 scanner: ${name}...`);
+    const result = scanner.run(repoRoot, staged);
+    if (!result) {
+      console.warn(`[TAS Security] Tier 2 (${name}) invocation failed`);
+      return;
+    }
+    if (result.findings.length > 0) {
+      findings.push(...result.findings);
+    } else {
+      console.log(`[TAS Security] Tier 2 (${name}) — clean`);
+    }
+    return; // only run first available
+  }
+}
+
+runExternalScanner();
+
+// ─── Tier 3: AI deep scan → report-only, LOCAL ONLY ──────────────────────────
+// Triggers ONLY when deep_scan_on_every_commit=true in tas.yaml.
+// Not intended for CI — use a personal Claude Code subscription locally
+// (5h reset, no per-call API charges). Writes/appends to docs/security-report.md;
+// dev may choose to `git add` it into the PR if they want reviewers to see.
+const runDeep = cfg.deep_scan_on_every_commit && cfg.tool !== 'none';
+
+function writeDeepScanReport(aiOutput, commitSha, staged) {
+  const docsDir = path.join(repoRoot, 'docs');
+  const reportPath = path.join(docsDir, 'security-report.md');
+  try { fs.mkdirSync(docsDir, { recursive: true }); } catch { /* ignore */ }
+
+  const now = new Date();
+  const isoDate = now.toISOString().replace('T', ' ').slice(0, 19) + ' UTC';
+  const shortSha = (commitSha || 'staged').slice(0, 8);
+
+  // Initial file template (only on first scan)
+  const header = [
+    '# Security Report',
+    '',
+    '> Generated by pre-commit / CI deep scan. Report-only — does NOT block commits.',
+    '> Review findings during PR review; open issues or fix in follow-up commits.',
+    '',
+    '## Scan History',
+    '',
+    '| Date (UTC) | Commit | Tool | Status | Findings |',
+    '|---|---|---|---|---|',
+    '',
+    '---',
+    '',
+  ].join('\n');
+
+  let content = '';
+  if (fs.existsSync(reportPath)) {
+    content = fs.readFileSync(reportPath, 'utf8');
+  } else {
+    content = header;
+  }
+
+  // Build per-scan section
+  const trimmed = (aiOutput || '').trim();
+  const isClean = /^NO FINDINGS\s*$/im.test(trimmed) || trimmed.length === 0;
+  const status = isClean ? 'Clean' : 'Findings present';
+
+  // Count findings from AI output (structured line format if present)
+  const lineRe = /^\s*(CRITICAL|HIGH|MEDIUM|LOW)\s*\|/gmi;
+  const matches = trimmed.match(lineRe) || [];
+  const findingsCount = matches.length;
+
+  const newHistoryRow = `| ${isoDate} | ${shortSha} | ${cfg.tool} | ${status} | ${findingsCount} |`;
+  const sectionAnchor = `scan-${now.getTime()}`;
+
+  const section = [
+    '',
+    `## Scan ${isoDate} — ${shortSha} <a id="${sectionAnchor}"></a>`,
+    '',
+    `- **Tool:** \`${cfg.tool}\``,
+    `- **Scope:** staged diff (${staged.length} file${staged.length === 1 ? '' : 's'})`,
+    `- **Status:** ${status}`,
+    '',
+    '### Staged files',
+    '',
+    ...staged.map((f) => `- \`${f}\``),
+    '',
+    '### AI Review Output',
+    '',
+    '```',
+    trimmed || 'NO FINDINGS',
+    '```',
+    '',
+    '---',
+    '',
+  ].join('\n');
+
+  // Insert new history row after the table header
+  const tableMatcher = /(\|\s*Date \(UTC\)[\s\S]*?\|---\|---\|---\|---\|---\|\n)/;
+  if (tableMatcher.test(content)) {
+    content = content.replace(tableMatcher, `$1${newHistoryRow}\n`);
+  } else {
+    // Fallback: no table header found, prepend history
+    content += `\n${newHistoryRow}\n`;
+  }
+
+  // Append full section at end
+  content = content.trimEnd() + '\n\n' + section;
+  fs.writeFileSync(reportPath, content);
+
+  return { reportPath, status, findingsCount };
+}
+
+if (runDeep) {
+  const diff = git('diff --cached -U0');
+  const headSha = git('rev-parse HEAD').trim();
+  if (diff && diff.length < 200_000) {
+    const prompt = [
+      'You are a senior security reviewer auditing a git staged diff before commit.',
+      '',
+      'Produce a structured security review. For each finding, output one line in this exact format:',
+      '  <SEVERITY> | <file:line> | <description> | <remediation>',
+      '',
+      'SEVERITY must be one of: CRITICAL, HIGH, MEDIUM, LOW.',
+      '',
+      'Focus areas: OWASP Top 10, hardcoded secrets, SQL/command injection, XSS, IDOR,',
+      'broken authn/authz, unsafe deserialization, insecure cryptography, SSRF, path traversal.',
+      '',
+      'Skip: style issues, missing tests, generic code quality. Only report security-relevant issues.',
+      '',
+      'If there are no security issues, output exactly: NO FINDINGS',
+      '',
+      'After the finding lines, add a short paragraph summarizing overall risk (1-3 sentences).',
+      '',
+      '=== DIFF START ===',
+      diff,
+      '=== DIFF END ===',
+    ].join('\n');
+
+    const tools = {
+      claude: { bin: 'claude', args: ['--print', '--permission-mode', 'bypassPermissions'] },
+      codex: { bin: 'codex', args: ['exec', '--quiet'] },
+      gemini: { bin: 'gemini', args: ['--prompt-stdin'] },
+    };
+    const tool = tools[cfg.tool];
+
+    if (!tool) {
+      console.warn(`[TAS Security] Tier 3: unknown tool "${cfg.tool}", skipping deep scan`);
+    } else {
+      console.log(`[TAS Security] Tier 3: running deep scan via ${cfg.tool} (report-only)...`);
+      const res = spawnSync(tool.bin, tool.args, {
+        input: prompt,
+        encoding: 'utf8',
+        timeout: 180_000,
+        shell: process.platform === 'win32',
+      });
+
+      if (res.error) {
+        console.warn(`[TAS Security] Tier 3: ${cfg.tool} CLI not installed or not on PATH — skipping`);
+      } else {
+        const out = ((res.stdout || '') + '\n' + (res.stderr || '')).trim();
+        const { reportPath, status, findingsCount } = writeDeepScanReport(out, headSha, staged);
+        const rel = path.relative(repoRoot, reportPath).replace(/\\/g, '/');
+        console.log(`[TAS Security] Tier 3: ${status} (${findingsCount} finding${findingsCount === 1 ? '' : 's'}) → ${rel}`);
+        if (findingsCount > 0) {
+          console.log(`[TAS Security]          Commit proceeds (report-only).`);
+          console.log(`[TAS Security]          To include the report in this commit so reviewers see it:`);
+          console.log(`[TAS Security]            git add ${rel} && git commit --amend --no-edit --no-verify`);
+        }
+      }
+    }
+  }
+}
+
+// ─── Report & exit ───────────────────────────────────────────────────────────
+if (findings.length === 0) {
+  console.log(`[TAS Security] Pass — ${staged.length} staged file(s) scanned, no issues`);
+  process.exit(0);
+}
+
+const sevOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+findings.sort((a, b) => (sevOrder[a.severity] ?? 9) - (sevOrder[b.severity] ?? 9));
+
+console.error('');
+console.error('[TAS Security] Findings:');
+console.error('─'.repeat(72));
+for (const f of findings) {
+  const sev = f.severity.toUpperCase().padEnd(8);
+  const loc = f.line ? `${f.file}:${f.line}` : f.file;
+  console.error(`  [${sev}] ${loc}`);
+  console.error(`           ${f.label}${f.match ? ' — ' + f.match : ''}`);
+}
+console.error('─'.repeat(72));
+
+const blockList = (cfg.block_on || []).map((s) => s.toLowerCase());
+const shouldBlock = findings.some((f) => blockList.includes(f.severity));
+
+if (shouldBlock) {
+  console.error('');
+  console.error('[TAS Security] COMMIT BLOCKED — findings at or above blocking threshold.');
+  console.error(`               block_on: [${blockList.join(', ')}]`);
+  if (cfg.allow_bypass) {
+    console.error('');
+    console.error('  To bypass (document the reason in commit message):');
+    console.error('    SKIP_SECURITY_SCAN=1 git commit ...');
+    console.error('    git commit --no-verify');
+  }
+  console.error('');
+  process.exit(1);
+}
+
+console.warn('');
+console.warn('[TAS Security] Warnings only — below block threshold, commit allowed.');
+console.warn('');
+process.exit(0);