@archpublicwebsite/eslint-config 1.0.18 → 1.0.19

package/tools/security/scan.mjs

@@ -11,7 +11,8 @@
  * │  What is checked                                    │
  * │  1. Staged .js/.ts/.vue files — eval, obfuscation,  │
  * │     base64 payloads, net/dns/child_process in       │
- * │     build-config files, prototype pollution         │
+ * │     build-config files, prototype pollution,        │
+ * │     XSS sinks, hardcoded secrets, SSRF, ReDoS      │
  * │  2. Newly added npm packages — install scripts      │
  * │     with curl/wget, base64-exec, credential theft   │
  * │  3. Typosquatting — package names within edit-      │
@@ -25,174 +26,53 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { extname, join } from 'node:path'
+import { INSTALL_SCRIPT_PATTERNS, SCAN_EXTENSIONS } from './patterns.mjs'
+import { isBlocking, partitionFindings, sortFindings } from './risks.mjs'
 import {
-  CONFIG_FILE_PATTERNS,
-  FILE_PATTERNS,
-  INSTALL_SCRIPT_PATTERNS,
-  POPULAR_PACKAGES,
-  SCAN_EXTENSIONS,
-} from './patterns.mjs'
+  BOLD,
+  DIM,
+  GRN,
+  R,
+  YLW,
+  collectObfuscatedLineFindings,
+  collectPatternFindings,
+  detectTyposquat,
+  isConfigFile,
+  printFileFinding,
+  printScanFooter,
+  printScanHeader,
+  printSupplyFinding,
+  shouldSkip,
+} from './scanner.mjs'
 import {
   getRepoRoot,
   getStagedNameStatus,
   runSafe,
 } from '../git-hooks/shared.mjs'
 
-// ─── ANSI colours ──────────────────────────────────────────────────────────────
-const R = '\x1b[0m'
-const RED = '\x1b[31m'
-const YLW = '\x1b[33m'
-const CYN = '\x1b[36m'
-const GRN = '\x1b[32m'
-const BOLD = '\x1b[1m'
-const DIM = '\x1b[2m'
-const HR = `${DIM}${'─'.repeat(62)}${R}`
-
-function badge(severity) {
-  switch (severity) {
-    case 'critical': return `${RED}${BOLD}[CRITICAL]${R}`
-    case 'high':     return `${RED}[HIGH]    ${R}`
-    case 'medium':   return `${YLW}[MEDIUM]  ${R}`
-    default:         return `${CYN}[LOW]     ${R}`
-  }
-}
-
-function isBlocking(severity) {
-  return severity === 'critical' || severity === 'high'
-}
-
-// ─── Helpers ───────────────────────────────────────────────────────────────────
-
-function isConfigFile(filePath) {
-  return CONFIG_FILE_PATTERNS.some(p => p.test(filePath))
-}
-
-// Files that intentionally contain dangerous-pattern literals for lint/security
-// rule definitions and scanner fixture tests. Scanning them with FILE_PATTERNS
-// causes self-referential false positives and blocks commits.
-const SELF_REFERENTIAL_SCAN_EXCLUSIONS = [
-  'packages/eslint-config/eslint.config.mjs',
-  'packages/eslint-config/tools/security/patterns.mjs',
-  'packages/eslint-config/tools/security/test-patterns.mjs',
-]
-
-function shouldSkipSelfReferentialFile(filePath) {
-  const normalizedPath = filePath.replaceAll('\\', '/')
-  return SELF_REFERENTIAL_SCAN_EXCLUSIONS.some(excluded => normalizedPath.endsWith(excluded))
-}
-
-function collectPatternFindings(lines, isConfig, filePath) {
-  const findings = []
-
-  for (const pattern of FILE_PATTERNS) {
-    if (pattern.configOnly && !isConfig) continue
-
-    for (let i = 0; i < lines.length; i++) {
-      if (pattern.regex.test(lines[i])) {
-        findings.push({
-          file: filePath,
-          line: i + 1,
-          lineContent: lines[i].trim().slice(0, 120),
-          patternId: pattern.id,
-          severity: pattern.severity,
-          message: pattern.message,
-        })
-      }
-    }
-  }
-
-  return findings
-}
-
-function collectObfuscatedLineFindings(lines, filePath) {
-  const findings = []
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    if (line.length <= 800) continue
-
-    // Encoded payload lines tend to have unusually high symbol density.
-    const nonWord = (line.match(/[^a-zA-Z0-9\s.,;:(){}[\]=<>+\-*/'"_]/g) || []).length
-    const density = nonWord / line.length
-    if (density <= 0.18) continue
-
-    findings.push({
-      file: filePath,
-      line: i + 1,
-      lineContent: `[${line.length} chars] ${line.trim().slice(0, 80)}…`,
-      patternId: 'long-obfuscated-line',
-      severity: 'critical',
-      message: `Line is ${line.length} chars with high symbol density (${(density * 100).toFixed(0)}%) — likely an embedded payload (dropper pattern)`,
-    })
-  }
-
-  return findings
-}
+// ─── Read staged file content ──────────────────────────────────────────────────
 
 /**
  * Read the staged (index) version of a file so we scan exactly what will be
  * committed — not any unsaved working-tree changes.
+ * @param {string} filePath
+ * @returns {string}
  */
 function readStagedContent(filePath) {
   return runSafe(`git show ":${filePath}"`)
 }
 
-/**
- * Levenshtein distance between two strings.
- * Used to detect typosquatted package names.
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-function levenshtein(a, b) {
-  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i])
-  for (let j = 0; j <= b.length; j++) dp[0][j] = j
-  for (let i = 1; i <= a.length; i++) {
-    for (let j = 1; j <= b.length; j++) {
-      dp[i][j] = a[i - 1] === b[j - 1]
-        ? dp[i - 1][j - 1]
-        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
-    }
-  }
-  return dp[a.length][b.length]
-}
-
-/**
- * Returns the popular package name that the given name is likely a typosquat
- * of (edit distance === 1), or null if no match.
- * @param {string} pkgName
- * @returns {string|null}
- */
-function detectTyposquat(pkgName) {
-  // Strip npm scope for comparison
-  const bare = pkgName.startsWith('@') ? (pkgName.split('/')[1] ?? pkgName) : pkgName
-  if (bare.length < 3) return null
-
-  for (const popular of POPULAR_PACKAGES) {
-    if (bare === popular) return null // exact match is fine
-    if (levenshtein(bare.toLowerCase(), popular.toLowerCase()) === 1) return popular
-  }
-  return null
-}
-
 // ─── Stage-file scanner ────────────────────────────────────────────────────────
 
-/**
- * @typedef {{ file: string, line: number, lineContent: string,
- *             patternId: string, severity: string, message: string }} FileFinding
- */
-
 /**
  * Scan every staged JS/TS/Vue file against FILE_PATTERNS.
- * @param {string} _repoRoot   (unused here but kept for symmetry)
- * @returns {FileFinding[]}
+ * @returns {import('./scanner.mjs').FileFinding[]}
  */
-function scanStagedFiles(_repoRoot) {
+function scanStagedFiles() {
   const staged = getStagedNameStatus()
   const toScan = staged.filter(({ status, path }) =>
     ['A', 'M'].includes(status[0]) && SCAN_EXTENSIONS.has(extname(path)),
   )
-
   if (toScan.length === 0) return []
 
   process.stdout.write(`\nScanning ${toScan.length} staged source file(s)...\n`)
@@ -201,10 +81,7 @@ function scanStagedFiles(_repoRoot) {
   let skipped = 0
 
   for (const { path: filePath } of toScan) {
-    if (shouldSkipSelfReferentialFile(filePath)) {
-      skipped++
-      continue
-    }
+    if (shouldSkip(filePath)) { skipped++; continue }
 
     const content = readStagedContent(filePath)
     if (!content) continue
@@ -219,7 +96,7 @@ function scanStagedFiles(_repoRoot) {
   }
 
   if (skipped > 0) {
-    process.stdout.write(`Skipping ${skipped} self-referential security definition/test file(s).\n`)
+    process.stdout.write(`Skipped ${skipped} self-referential security definition file(s).\n`)
   }
 
   return findings
@@ -230,7 +107,7 @@ function scanStagedFiles(_repoRoot) {
 /**
  * Compare staged vs committed package.json files to find packages that were
  * newly added in this commit (across all dependency fields).
- * @returns {string[]} Array of package names
+ * @returns {string[]}
  */
 function getNewlyAddedPackages() {
   const staged = getStagedNameStatus()
@@ -239,7 +116,6 @@ function getNewlyAddedPackages() {
     && path.endsWith('package.json')
     && !path.includes('node_modules'),
   )
-
   if (pkgFiles.length === 0) return []
 
   const depFields = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']
@@ -256,57 +132,38 @@ function getNewlyAddedPackages() {
       }
       return all
     }
-    catch {
-      return new Set()
-    }
+    catch { return new Set() }
   }
 
   const added = new Set()
-
   for (const { path: pkgFile } of pkgFiles) {
-    const newContent = readStagedContent(pkgFile)
-    const oldContent = runSafe(`git show "HEAD:${pkgFile}"`)
-    const newDeps = extractDepNames(newContent)
-    const oldDeps = extractDepNames(oldContent)
+    const newDeps = extractDepNames(readStagedContent(pkgFile))
+    const oldDeps = extractDepNames(runSafe(`git show "HEAD:${pkgFile}"`))
     for (const name of newDeps) {
       if (!oldDeps.has(name)) added.add(name)
     }
   }
-
   return [...added]
 }
 
-/**
- * @typedef {{ pkg: string, scriptName?: string, patternId: string,
- *             severity: string, message: string, lineContent: string }} SupplyFinding
- */
-
 /**
  * Inspect a single package's install scripts in node_modules.
  * @param {string} pkgName
  * @param {string} repoRoot
- * @returns {SupplyFinding[]}
  */
 function checkInstallScripts(pkgName, repoRoot) {
   const pkgJsonPath = join(repoRoot, 'node_modules', pkgName, 'package.json')
   if (!existsSync(pkgJsonPath)) return []
 
   let pkg
-  try {
-    pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'))
-  }
-  catch {
-    return []
-  }
+  try { pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8')) }
+  catch { return [] }
 
   const findings = []
-  const scriptFields = ['preinstall', 'install', 'postinstall']
-
-  for (const scriptName of scriptFields) {
+  for (const scriptName of ['preinstall', 'install', 'postinstall']) {
     const script = pkg.scripts?.[scriptName]
     if (!script) continue
 
-    // Always surface that an install script exists (medium — for awareness)
     findings.push({
       pkg: pkgName,
       scriptName,
@@ -316,7 +173,6 @@ function checkInstallScripts(pkgName, repoRoot) {
       lineContent: script.slice(0, 120),
     })
 
-    // Check for specific dangerous patterns (high/critical)
     for (const pattern of INSTALL_SCRIPT_PATTERNS) {
       if (pattern.regex.test(script)) {
         findings.push({
@@ -330,15 +186,12 @@ function checkInstallScripts(pkgName, repoRoot) {
       }
     }
   }
-
   return findings
 }
 
 /**
- * Run the full supply-chain scan: typosquatting + install-script analysis
- * for every newly added package.
+ * Run the full supply-chain scan: typosquatting + install-script analysis.
  * @param {string} repoRoot
- * @returns {SupplyFinding[]}
  */
 function scanNewDependencies(repoRoot) {
   const newPkgs = getNewlyAddedPackages()
@@ -346,10 +199,8 @@ function scanNewDependencies(repoRoot) {
 
   process.stdout.write(`\nSupply-chain scan: ${newPkgs.length} newly added package(s)...\n`)
 
-  const findings = []
-
-  for (const pkgName of newPkgs) {
-    // 1. Typosquatting
+  return newPkgs.flatMap((pkgName) => {
+    const findings = []
     const similar = detectTyposquat(pkgName)
     if (similar) {
       findings.push({
@@ -360,49 +211,18 @@ function scanNewDependencies(repoRoot) {
         lineContent: `"${pkgName}" is 1 edit away from "${similar}"`,
       })
     }
-
-    // 2. Install scripts
-    const scriptFindings = checkInstallScripts(pkgName, repoRoot)
-    findings.push(...scriptFindings)
-  }
-
-  return findings
+    return [...findings, ...checkInstallScripts(pkgName, repoRoot)]
+  })
 }
 
 // ─── Optional: pnpm/npm audit ─────────────────────────────────────────────────
 
-/**
- * Run `pnpm audit --audit-level=high` when SECURITY_AUDIT=1 is set.
- * Non-fatal: output is printed but does not block the commit so it doesn't
- * slow down normal developer workflows.
- */
 function runAudit(repoRoot) {
   if (process.env.SECURITY_AUDIT !== '1') return
 
   process.stdout.write(`\nRunning pnpm audit (SECURITY_AUDIT=1)...\n`)
   const result = runSafe('pnpm audit --audit-level=high 2>&1')
-  if (result) {
-    process.stdout.write(`${DIM}${result}${R}\n`)
-  }
-}
-
-// ─── Output helpers ────────────────────────────────────────────────────────────
-
-function printFileFinding(f) {
-  console.log(`\n  ${badge(f.severity)} ${DIM}${f.file}:${f.line}${R}`)
-  console.log(`  ${BOLD}${f.message}${R}`)
-  console.log(`  ${DIM}│${R}  ${f.lineContent}`)
-}
-
-function printSupplyFinding(f) {
-  if (f.patternId === 'install-script-present') {
-    console.log(`  ${DIM}⚑${R}  ${BOLD}${f.pkg}${R} — ${f.scriptName}: ${DIM}${f.lineContent}${R}`)
-    return
-  }
-  const scriptLabel = f.scriptName ? ` (${DIM}${f.scriptName}${R})` : ''
-  console.log(`\n  ${badge(f.severity)} ${BOLD}${f.pkg}${R}${scriptLabel}`)
-  console.log(`  ${f.message}`)
-  console.log(`  ${DIM}│${R}  ${f.lineContent}`)
+  if (result) process.stdout.write(`${DIM}${result}${R}\n`)
 }
 
 // ─── Entry point ───────────────────────────────────────────────────────────────
@@ -418,16 +238,15 @@ function main() {
 
   const repoRoot = getRepoRoot()
 
-  console.log(`\n${HR}`)
-  console.log(`  ${BOLD}@archipelago/security-scan${R}  ${DIM}socket.dev-style pre-commit guard${R}`)
-  console.log(HR)
+  printScanHeader('@archipelago/security-scan', 'socket.dev-style pre-commit guard')
 
-  const fileFindings = scanStagedFiles(repoRoot)
+  const fileFindings   = scanStagedFiles()
   const supplyFindings = scanNewDependencies(repoRoot)
 
   runAudit(repoRoot)
 
-  const allFindings = [...fileFindings, ...supplyFindings]
+  const allFindings = sortFindings([...fileFindings, ...supplyFindings])
+  const { blocking, warnings } = partitionFindings(allFindings)
 
   if (fileFindings.length > 0) {
     console.log(`\n${BOLD}Source-code findings:${R}`)
@@ -439,27 +258,7 @@ function main() {
     supplyFindings.forEach(printSupplyFinding)
   }
 
-  const blocking = allFindings.filter(f => isBlocking(f.severity))
-  const warnings = allFindings.filter(f => !isBlocking(f.severity))
-
-  console.log(`\n${HR}`)
-
-  if (blocking.length === 0) {
-    const warnNote = warnings.length > 0 ? `  ${DIM}(${warnings.length} warning(s) — review recommended)${R}` : ''
-    console.log(`  ${GRN}${BOLD}✔  Security scan passed${R}${warnNote}`)
-    console.log(HR)
-    console.log()
-    return
-  }
-
-  console.log(
-    `  ${RED}${BOLD}✖  COMMIT BLOCKED${R} — ${blocking.length} critical/high security issue(s) found`,
-  )
-  console.log(`  ${DIM}To bypass (emergencies only): SKIP_SECURITY_SCAN=1 git commit …${R}`)
-  console.log(HR)
-  console.log()
-
-  process.exit(1)
+  printScanFooter(blocking, warnings, 'COMMIT BLOCKED', 'SKIP_SECURITY_SCAN=1 git commit …')
 }
 
 main()

package/tools/security/scanner.mjs

@@ -0,0 +1,233 @@
+/**
+ * @archipelago/security — shared scanner utilities
+ *
+ * Single source of truth for all functions used by both the pre-commit scanner
+ * (tools/security/scan.mjs) and the pre-push scanner
+ * (tools/git-hooks/pre-push.mjs).
+ *
+ * Nothing here is an entry-point — every export is consumed by those two
+ * callers; do not add main() logic here.
+ */
+
+import { CONFIG_FILE_PATTERNS, FILE_PATTERNS, POPULAR_PACKAGES } from './patterns.mjs'
+
+// ─── ANSI colours ──────────────────────────────────────────────────────────────
+
+export const R    = '\x1b[0m'
+export const RED  = '\x1b[31m'
+export const YLW  = '\x1b[33m'
+export const CYN  = '\x1b[36m'
+export const GRN  = '\x1b[32m'
+export const BOLD = '\x1b[1m'
+export const DIM  = '\x1b[2m'
+export const HR   = `\x1b[2m${'─'.repeat(62)}\x1b[0m`
+
+// ─── Severity badge ────────────────────────────────────────────────────────────
+
+/** @param {'critical'|'high'|'medium'|'low'} severity */
+export function badge(severity) {
+  switch (severity) {
+    case 'critical': return `${RED}${BOLD}[CRITICAL]${R}`
+    case 'high':     return `${RED}[HIGH]    ${R}`
+    case 'medium':   return `${YLW}[MEDIUM]  ${R}`
+    default:         return `${CYN}[LOW]     ${R}`
+  }
+}
+
+// ─── Self-referential exclusions ───────────────────────────────────────────────
+
+/**
+ * Files that intentionally contain dangerous-pattern literals for lint/security
+ * rule definitions and scanner fixture tests. Scanning them causes self-referential
+ * false positives and blocks commits.
+ */
+export const SELF_REFERENTIAL_SCAN_EXCLUSIONS = [
+  'packages/eslint-config/eslint.config.mjs',
+  'packages/eslint-config/tools/git-hooks/pre-push.mjs',
+  'packages/eslint-config/tools/security/patterns.mjs',
+  'packages/eslint-config/tools/security/risks.mjs',
+  'packages/eslint-config/tools/security/scan.mjs',
+  'packages/eslint-config/tools/security/scanner.mjs',
+  'packages/eslint-config/tools/setup/install.mjs',
+  'packages/eslint-config/tools/security/test-patterns.mjs',
+]
+
+/** @param {string} filePath */
+export function shouldSkip(filePath) {
+  const normalized = filePath.replaceAll('\\', '/')
+  return SELF_REFERENTIAL_SCAN_EXCLUSIONS.some(excluded => normalized.endsWith(excluded))
+}
+
+// ─── Config-file detection ─────────────────────────────────────────────────────
+
+/** @param {string} filePath */
+export function isConfigFile(filePath) {
+  return CONFIG_FILE_PATTERNS.some(p => p.test(filePath))
+}
+
+// ─── Pattern-based finding collectors ─────────────────────────────────────────
+
+/**
+ * @typedef {{ file: string, line: number, lineContent: string,
+ *             patternId: string, severity: string, message: string,
+ *             category?: string }} FileFinding
+ */
+
+/**
+ * Scan `lines` against FILE_PATTERNS and return findings.
+ * @param {string[]} lines
+ * @param {boolean}  isConfig  Whether the file is a build-config file
+ * @param {string}   filePath
+ * @returns {FileFinding[]}
+ */
+export function collectPatternFindings(lines, isConfig, filePath) {
+  const findings = []
+  for (const pattern of FILE_PATTERNS) {
+    if (pattern.configOnly && !isConfig) continue
+    for (let i = 0; i < lines.length; i++) {
+      if (pattern.regex.test(lines[i])) {
+        findings.push({
+          file: filePath,
+          line: i + 1,
+          lineContent: lines[i].trim().slice(0, 120),
+          patternId: pattern.id,
+          severity: pattern.severity,
+          message: pattern.message,
+          category: pattern.category ?? 'general',
+        })
+      }
+    }
+  }
+  return findings
+}
+
+/**
+ * Flag lines that are suspiciously long AND have high symbol density —
+ * the hallmark of an embedded base64/shuffled-string payload (dropper pattern).
+ * @param {string[]} lines
+ * @param {string}   filePath
+ * @returns {FileFinding[]}
+ */
+export function collectObfuscatedLineFindings(lines, filePath) {
+  const findings = []
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (line.length <= 800) continue
+    const nonWord = (line.match(/[^a-zA-Z0-9\s.,;:(){}[\]=<>+\-*/'"_]/g) || []).length
+    const density = nonWord / line.length
+    if (density <= 0.18) continue
+    findings.push({
+      file: filePath,
+      line: i + 1,
+      lineContent: `[${line.length} chars] ${line.trim().slice(0, 80)}…`,
+      patternId: 'long-obfuscated-line',
+      severity: 'critical',
+      message: `Line is ${line.length} chars with high symbol density (${(density * 100).toFixed(0)}%) — likely an embedded payload (dropper pattern)`,
+      category: 'obfuscation',
+    })
+  }
+  return findings
+}
+
+// ─── Typosquatting ─────────────────────────────────────────────────────────────
+
+/**
+ * Levenshtein distance between two strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function levenshtein(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i])
+  for (let j = 0; j <= b.length; j++) dp[0][j] = j
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
+    }
+  }
+  return dp[a.length][b.length]
+}
+
+/**
+ * Returns the popular package name that `pkgName` is likely a typosquat of
+ * (edit-distance === 1), or null if no match.
+ * @param {string} pkgName
+ * @returns {string|null}
+ */
+export function detectTyposquat(pkgName) {
+  const bare = pkgName.startsWith('@') ? (pkgName.split('/')[1] ?? pkgName) : pkgName
+  if (bare.length < 3) return null
+  for (const popular of POPULAR_PACKAGES) {
+    if (bare === popular) return null
+    if (levenshtein(bare.toLowerCase(), popular.toLowerCase()) === 1) return popular
+  }
+  return null
+}
+
+// ─── Output helpers ────────────────────────────────────────────────────────────
+
+/** @param {FileFinding} f */
+export function printFileFinding(f) {
+  console.log(`\n  ${badge(f.severity)} ${DIM}${f.file}:${f.line}${R}`)
+  console.log(`  ${BOLD}${f.message}${R}`)
+  console.log(`  ${DIM}│${R}  ${f.lineContent}`)
+  if (f.category && f.category !== 'general') {
+    console.log(`  ${DIM}category: ${f.category}${R}`)
+  }
+}
+
+/**
+ * @param {{ pkg?: string, file?: string, patternId: string,
+ *            severity: string, message: string, lineContent: string,
+ *            scriptName?: string }} f
+ */
+export function printSupplyFinding(f) {
+  if (f.patternId === 'install-script-present') {
+    console.log(`  ${DIM}⚑${R}  ${BOLD}${f.pkg}${R} — ${f.scriptName}: ${DIM}${f.lineContent}${R}`)
+    return
+  }
+  const scriptLabel = f.scriptName ? ` (${DIM}${f.scriptName}${R})` : ''
+  console.log(`\n  ${badge(f.severity)} ${BOLD}${f.pkg ?? f.file}${R}${scriptLabel}`)
+  console.log(`  ${f.message}`)
+  console.log(`  ${DIM}│${R}  ${f.lineContent}`)
+}
+
+// ─── Scan result output ────────────────────────────────────────────────────────
+
+/**
+ * Print the scan header banner.
+ * @param {string} title
+ * @param {string} subtitle
+ */
+export function printScanHeader(title, subtitle) {
+  console.log(`\n${HR}`)
+  console.log(`  ${BOLD}${title}${R}  ${DIM}${subtitle}${R}`)
+  console.log(HR)
+}
+
+/**
+ * Print the summary footer and exit(1) if there are blocking findings.
+ * @param {import('../security/risks.mjs').FileFinding[]} blocking
+ * @param {import('../security/risks.mjs').FileFinding[]} warnings
+ * @param {string} blockMessage   e.g. 'COMMIT BLOCKED' or 'PUSH BLOCKED'
+ * @param {string} bypassHint     e.g. 'SKIP_SECURITY_SCAN=1 git commit …'
+ */
+export function printScanFooter(blocking, warnings, blockMessage, bypassHint) {
+  console.log(`\n${HR}`)
+  if (blocking.length === 0) {
+    const warnNote = warnings.length > 0
+      ? `  ${DIM}(${warnings.length} warning(s) — review recommended)${R}`
+      : ''
+    console.log(`  ${GRN}${BOLD}✔  Security scan passed${R}${warnNote}`)
+    console.log(HR)
+    console.log()
+    return
+  }
+  console.log(`  ${RED}${BOLD}✖  ${blockMessage}${R} — ${blocking.length} critical/high security issue(s) found`)
+  console.log(`  ${DIM}To bypass (emergencies only): ${bypassHint}${R}`)
+  console.log(HR)
+  console.log()
+  process.exit(1)
+}