@clear-capabilities/agentic-security-scanner 0.79.0 → 0.84.1

package/src/posture/threat-model-auto.js

@@ -0,0 +1,268 @@
+// Auto-generated threat model — Recommendation #2 of the world-class+2 plan.
+//
+// Builds a STRIDE threat model from the scan's findings + IR + privacy
+// taint. Outputs Mermaid diagrams + per-asset attack trees grounded in
+// actual scanner evidence. The model is "live" — regenerated every scan
+// so it can't bit-rot.
+//
+// Pipeline:
+//   1. Identify external entities — every route, message-queue consumer,
+//      file ingest, S3 listener, etc.
+//   2. Identify trust boundaries — entity → handler boundary, internal-
+//      service → external-service boundary
+//   3. Identify assets — every PII/PHI/PCI field, every credential, every
+//      authoritative DB/cache, every secret-bearing service
+//   4. Apply STRIDE per (entity, asset) pair using template-driven rules
+//   5. Generate attack trees rooted at each high-value asset with leaves
+//      grounded in actual scanner findings
+//
+// Output:
+//   { entities, boundaries, assets, threats, attackTrees, mermaid }
+//
+// Persisted to .agentic-security/threat-model.json (machine-readable) and
+// .agentic-security/threat-model.md (human-readable).
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// STRIDE category descriptors
+const STRIDE = {
+  S: { label: 'Spoofing',         control: 'Authentication / Identity' },
+  T: { label: 'Tampering',        control: 'Integrity / Authorization' },
+  R: { label: 'Repudiation',      control: 'Audit logs / Non-repudiation' },
+  I: { label: 'Information Disclosure', control: 'Confidentiality / Encryption' },
+  D: { label: 'Denial of Service',control: 'Availability / Rate limiting' },
+  E: { label: 'Elevation of Privilege', control: 'Authorization / Least privilege' },
+};
+
+// Map CWE → STRIDE categories. Multi-mapping is allowed.
+const CWE_TO_STRIDE = {
+  'CWE-22':  ['I'],            // path-traversal
+  'CWE-78':  ['E', 'T'],       // command-injection
+  'CWE-79':  ['T'],            // xss
+  'CWE-89':  ['T', 'I'],       // sql-injection
+  'CWE-90':  ['T'],            // ldap-injection
+  'CWE-94':  ['E'],            // code-injection
+  'CWE-113': ['T'],            // header injection
+  'CWE-134': ['I'],            // format-string
+  'CWE-200': ['I'],            // information-exposure
+  'CWE-287': ['S'],            // improper authentication
+  'CWE-307': ['S'],            // brute-force
+  'CWE-327': ['I'],            // weak-crypto
+  'CWE-330': ['S'],            // weak-rng
+  'CWE-352': ['T'],            // csrf
+  'CWE-359': ['I'],            // private-info exposure
+  'CWE-415': ['D', 'E'],       // double-free
+  'CWE-416': ['D', 'E'],       // use-after-free
+  'CWE-434': ['E'],            // file upload
+  'CWE-502': ['E'],            // insecure-deserialization
+  'CWE-601': ['T'],            // open-redirect
+  'CWE-611': ['I'],            // xxe
+  'CWE-639': ['E'],            // IDOR
+  'CWE-643': ['T'],            // xpath injection
+  'CWE-798': ['I', 'S'],       // hardcoded-secret
+  'CWE-918': ['I', 'E'],       // ssrf
+  'CWE-1004':['I'],            // missing cookie hardening
+  'CWE-1321':['T', 'E'],       // prototype-pollution
+  'CWE-1333':['D'],            // ReDoS
+  'CWE-1427':['T'],            // prompt injection
+};
+
+function _stridesForFinding(f) {
+  const c = f.cwe || '';
+  if (CWE_TO_STRIDE[c]) return CWE_TO_STRIDE[c];
+  // Family-based fallback
+  if (f.family === 'sql-injection') return ['T', 'I'];
+  if (f.family === 'command-injection') return ['E', 'T'];
+  if (f.family === 'xss') return ['T'];
+  if (f.family === 'hardcoded-secret') return ['I'];
+  return ['T'];
+}
+
+/**
+ * Build the threat-model graph. `scan` is the engine's scan result
+ * structure (findings + routes + supplyChain).
+ */
+export function buildThreatModel(scan, opts = {}) {
+  const entities = [];   // external entities: routes, queue consumers, file ingest
+  const boundaries = []; // trust boundary edges
+  const assets = [];     // valuables: PII, credentials, DBs
+  const threats = [];    // (entity, asset, stride) tuples
+
+  // Step 1: external entities — routes
+  for (const r of (scan.routes || [])) {
+    entities.push({
+      kind: 'http-route',
+      id: `route:${r.method || 'ANY'}:${r.path || r.file + ':' + r.line}`,
+      method: r.method || 'ANY',
+      path: r.path || null,
+      file: r.file, line: r.line,
+      requiresAuth: !!r.requiresAuth,
+    });
+  }
+  // External entities — message queues / consumers / file ingest (best-effort
+  // heuristic from findings).
+  for (const f of (scan.findings || [])) {
+    if (/kafka|sqs|sns|rabbit|pubsub|kinesis/i.test(f.snippet || '')) {
+      entities.push({ kind: 'queue-consumer', id: `queue:${f.file}:${f.line}`, file: f.file, line: f.line });
+    }
+  }
+
+  // Step 2: assets — PII / credentials / DBs
+  for (const f of (scan.findings || [])) {
+    if (f.family === 'hardcoded-secret') {
+      assets.push({ kind: 'credential', id: `cred:${f.file}:${f.line}`, file: f.file, line: f.line, name: (f.vuln||'').slice(0, 80) });
+    }
+    if (f.family === 'pii-exposure') {
+      assets.push({ kind: 'pii', id: `pii:${f.file}:${f.line}`, file: f.file, line: f.line, classes: f.piiClass || [] });
+    }
+  }
+  // DB-shaped assets: routes that touch SQL.
+  const dbAsset = { kind: 'datastore', id: 'datastore:default', name: 'Application Database' };
+  let hasDbFinding = false;
+  for (const f of (scan.findings || [])) {
+    if (f.family === 'sql-injection' || /SqlCommand|prepareStatement|EntityManager/i.test(f.snippet || '')) {
+      hasDbFinding = true; break;
+    }
+  }
+  if (hasDbFinding) assets.push(dbAsset);
+
+  // Step 3: trust boundaries
+  for (const e of entities) {
+    boundaries.push({ from: 'external', to: e.id, kind: 'trust-boundary', requiresAuth: e.requiresAuth });
+  }
+  for (const a of assets) {
+    boundaries.push({ from: 'application', to: a.id, kind: 'asset-boundary' });
+  }
+
+  // Step 4: STRIDE per finding (each finding implies one or more threats)
+  for (const f of (scan.findings || [])) {
+    const sts = _stridesForFinding(f);
+    for (const st of sts) {
+      threats.push({
+        stride: st,
+        strideLabel: STRIDE[st]?.label || st,
+        cwe: f.cwe || null,
+        family: f.family,
+        severity: f.severity,
+        file: f.file, line: f.line,
+        vuln: f.vuln,
+        finding_id: f.id,
+        affectsAsset: assets.find(a =>
+          (a.kind === 'credential' && f.family === 'hardcoded-secret') ||
+          (a.kind === 'pii' && f.family === 'pii-exposure') ||
+          (a.kind === 'datastore' && (f.family === 'sql-injection' || f.family === 'insecure-deserialization'))
+        )?.id || null,
+        atEntity: entities.find(e => e.file === f.file && Math.abs((e.line||0) - (f.line||0)) <= 50)?.id || null,
+      });
+    }
+  }
+
+  // Step 5: attack trees — per high-value asset
+  const attackTrees = assets.map(a => {
+    const leaves = threats
+      .filter(t => t.affectsAsset === a.id)
+      .map(t => ({
+        label: `${t.strideLabel} via ${t.family} (${t.cwe || '—'})`,
+        severity: t.severity,
+        file: t.file, line: t.line,
+        finding_id: t.finding_id,
+      }));
+    return {
+      root: `Compromise ${a.kind}: ${a.name || a.id}`,
+      asset_id: a.id,
+      leaves,
+      severity: leaves.some(l => l.severity === 'critical') ? 'critical'
+              : leaves.some(l => l.severity === 'high')     ? 'high' : 'medium',
+    };
+  });
+
+  return { entities, boundaries, assets, threats, attackTrees };
+}
+
+/**
+ * Render the model as a Mermaid flowchart for visual review.
+ */
+export function renderMermaid(model) {
+  const lines = ['flowchart TB'];
+  lines.push('  subgraph External');
+  for (const e of model.entities.slice(0, 30)) {
+    lines.push(`    ${_mid(e.id)}["${e.kind}: ${e.method || ''} ${e.path || (e.file||'') + ':' + (e.line||'')}"]`);
+  }
+  lines.push('  end');
+  lines.push('  subgraph Application');
+  for (const a of model.assets.slice(0, 30)) {
+    lines.push(`    ${_mid(a.id)}{{"${a.kind}: ${a.name || a.id}"}}`);
+  }
+  lines.push('  end');
+  for (const b of model.boundaries.slice(0, 100)) {
+    if (b.kind === 'trust-boundary') {
+      lines.push(`  External --> ${_mid(b.to)}`);
+    } else if (b.kind === 'asset-boundary') {
+      lines.push(`  ${_mid(b.from)} -.-> ${_mid(b.to)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function _mid(id) { return String(id).replace(/[^A-Za-z0-9]/g, '_').slice(0, 60); }
+
+/**
+ * Persist threat model to disk: JSON for tooling, Markdown for review.
+ */
+export function persistThreatModel(scanRoot, model) {
+  const dir = path.join(scanRoot, '.agentic-security');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  try { fs.writeFileSync(path.join(dir, 'threat-model.json'), JSON.stringify(model, null, 2)); } catch {}
+  try { fs.writeFileSync(path.join(dir, 'threat-model.md'), renderMarkdown(model)); } catch {}
+}
+
+function renderMarkdown(model) {
+  const lines = [];
+  lines.push('# Threat Model (auto-generated)');
+  lines.push('');
+  lines.push(`Generated by agentic-security on ${new Date().toISOString().slice(0,10)}.`);
+  lines.push('');
+  lines.push('This threat model is derived from static analysis of the current codebase and is regenerated on every scan. It is intended as a working artifact, not a finished compliance document.');
+  lines.push('');
+  lines.push('## Entities + boundaries');
+  lines.push('');
+  lines.push('```mermaid');
+  lines.push(renderMermaid(model));
+  lines.push('```');
+  lines.push('');
+  lines.push('## Assets');
+  lines.push('');
+  for (const a of model.assets.slice(0, 100)) {
+    lines.push(`- **${a.kind}**: ${a.name || a.id} — at \`${a.file || '(global)'}${a.line ? ':'+a.line : ''}\``);
+  }
+  lines.push('');
+  lines.push('## STRIDE threats');
+  lines.push('');
+  const byStride = {};
+  for (const t of model.threats) (byStride[t.stride] ||= []).push(t);
+  for (const [st, threats] of Object.entries(byStride)) {
+    lines.push(`### ${STRIDE[st]?.label || st} (${threats.length})`);
+    lines.push('');
+    for (const t of threats.slice(0, 25)) {
+      lines.push(`- [${t.severity}] **${t.family}** (${t.cwe || '—'}) at \`${t.file}:${t.line}\` — ${t.vuln}`);
+    }
+    if (threats.length > 25) lines.push(`- … and ${threats.length - 25} more`);
+    lines.push('');
+  }
+  lines.push('## Attack trees');
+  lines.push('');
+  for (const tree of model.attackTrees) {
+    lines.push(`### ${tree.root}`);
+    lines.push(`Severity rollup: **${tree.severity}**`);
+    lines.push('');
+    for (const leaf of tree.leaves.slice(0, 20)) {
+      lines.push(`- [${leaf.severity}] ${leaf.label} — \`${leaf.file}:${leaf.line}\``);
+    }
+    if (tree.leaves.length > 20) lines.push(`- … and ${tree.leaves.length - 20} more leaves`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export const _internals = { STRIDE, CWE_TO_STRIDE };

package/src/posture/threat-model-grounding.js

@@ -0,0 +1,169 @@
+// Threat-model-grounded prioritization.
+//
+// Reads project documentation (CLAUDE.md + docs/THREAT-MODEL.md + AGENTS.md)
+// to extract the project's stated threat model and applies it to finding
+// prioritization:
+//
+//   - **Crown jewels** — file globs listed under "## Crown jewels" or
+//     "## Sensitive surfaces" boost severity by one tier when a finding
+//     lands there.
+//   - **Out-of-scope** — file globs under "## Out of scope" or "## Not in
+//     threat model" demote findings to low.
+//   - **Compliance regime** — declared under "## Compliance" (e.g.
+//     SOC2 / HIPAA / GDPR) adds compliance-tag fields to findings in
+//     matching families (PII → HIPAA/GDPR; auth → SOC2 CC6.1; etc.).
+//   - **Stated attacker** — "## Attacker model" / "## Threat actor"
+//     section sets f.attackerProfile = 'script-kiddie' | 'apt' | 'insider'
+//     for use in downstream prioritization.
+//
+// Opt-out: AGENTIC_SECURITY_NO_THREAT_MODEL_GROUNDING=1
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const DOC_PATHS = [
+  'CLAUDE.md',
+  'docs/THREAT-MODEL.md',
+  'docs/threat-model.md',
+  'docs/THREATMODEL.md',
+  'THREAT-MODEL.md',
+  '.agentic-security/AGENTS.md',
+];
+
+function _readDoc(scanRoot, rel) {
+  try { return fs.readFileSync(path.join(scanRoot, rel), 'utf8'); } catch { return ''; }
+}
+
+function _allDocs(scanRoot) {
+  return DOC_PATHS.map(p => _readDoc(scanRoot, p)).join('\n\n');
+}
+
+function _extractPathsFromSection(body, sectionRegex) {
+  const sec = body.match(sectionRegex);
+  if (!sec) return [];
+  const paths = [];
+  // Match `path/like/this/**`, "path/like", or list-item paths.
+  const re = /[`"]([\w./*?\-]+)[`"]|^\s*-\s+([\w./*?\-]+)/gm;
+  let m;
+  while ((m = re.exec(sec[0]))) {
+    const p = m[1] || m[2];
+    if (p && /[\/.]/.test(p)) paths.push(p);
+  }
+  return Array.from(new Set(paths));
+}
+
+function _extractCompliance(body) {
+  const sec = body.match(/^#{1,3}\s+Compliance[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/im);
+  if (!sec) return [];
+  const found = new Set();
+  const re = /\b(SOC2|HIPAA|PCI[- ]DSS|GDPR|CCPA|FedRAMP|ISO[- ]?27001|NIST(?:[- ]?(?:CSF|800-53|AI 600-1))?|EU AI Act|OWASP (?:ASVS|LLM Top 10))\b/gi;
+  let m;
+  while ((m = re.exec(sec[0]))) found.add(m[1].toUpperCase().replace(/\s+/g, '-'));
+  return Array.from(found);
+}
+
+function _extractAttacker(body) {
+  const sec = body.match(/^#{1,3}\s+(?:Attacker model|Threat actor|Adversary)[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/im);
+  if (!sec) return null;
+  const txt = sec[0].toLowerCase();
+  if (/\bapt\b|nation[- ]?state|sophisticated/.test(txt)) return 'apt';
+  if (/\binsider\b|employee|disgruntled/.test(txt)) return 'insider';
+  if (/script[- ]?kiddie|automated|opportunistic/.test(txt)) return 'script-kiddie';
+  return 'general';
+}
+
+function _globMatch(pattern, p) {
+  const norm = String(p).replace(/\\/g, '/');
+  const re = new RegExp(
+    '^' + String(pattern).replace(/\\/g, '/')
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*\*/g, '###DSTAR###')
+      .replace(/\*/g, '[^/]*')
+      .replace(/###DSTAR###/g, '.*')
+    + '$',
+  );
+  return re.test(norm);
+}
+
+const SEVERITY_RANK = ['info', 'low', 'medium', 'high', 'critical'];
+
+function _bumpSeverity(sev) {
+  const i = SEVERITY_RANK.indexOf(sev);
+  if (i < 0 || i >= SEVERITY_RANK.length - 1) return sev;
+  return SEVERITY_RANK[i + 1];
+}
+
+const FAMILY_TO_REGIME = {
+  'pii-exposure': ['HIPAA', 'GDPR'],
+  'training-data-pii': ['GDPR'],
+  'auth-missing': ['SOC2'],
+  'authz': ['SOC2'],
+  'idor': ['SOC2'],
+  'crypto-weak-cipher': ['PCI-DSS', 'FedRAMP'],
+  'crypto-tls-no-verify': ['PCI-DSS'],
+  'hardcoded-secret': ['SOC2', 'PCI-DSS'],
+  'k8s-rbac-cluster-admin': ['SOC2'],
+  'aws-public-s3': ['SOC2', 'GDPR'],
+};
+
+/**
+ * Read project threat model from documentation. Cached per-scan-root via
+ * a module-level WeakMap-like... actually just pure read each time, since
+ * scan-time overhead is tiny.
+ */
+export function loadThreatModel(scanRoot) {
+  if (process.env.AGENTIC_SECURITY_NO_THREAT_MODEL_GROUNDING === '1') {
+    return { crownJewels: [], outOfScope: [], compliance: [], attacker: null };
+  }
+  const body = _allDocs(scanRoot);
+  return {
+    crownJewels:   _extractPathsFromSection(body, /^#{1,3}\s+(?:Crown jewels|Sensitive surfaces?)[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/im),
+    outOfScope:    _extractPathsFromSection(body, /^#{1,3}\s+(?:Out of scope|Not in threat model)[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/im),
+    compliance:    _extractCompliance(body),
+    attacker:      _extractAttacker(body),
+  };
+}
+
+/**
+ * Annotator: applies the project's threat model to each finding.
+ */
+export function applyThreatModel(scanRoot, findings) {
+  if (process.env.AGENTIC_SECURITY_NO_THREAT_MODEL_GROUNDING === '1') return { applied: 0 };
+  if (!Array.isArray(findings) || findings.length === 0) return { applied: 0 };
+  const tm = loadThreatModel(scanRoot);
+  if (!tm.crownJewels.length && !tm.outOfScope.length && !tm.compliance.length && !tm.attacker) {
+    return { applied: 0, reason: 'no-threat-model-found' };
+  }
+  let applied = 0;
+  for (const f of findings) {
+    const rel = f.file ? (path.isAbsolute(f.file) ? path.relative(scanRoot, f.file) : f.file) : '';
+
+    // Out-of-scope demotion wins over crown-jewel promotion.
+    if (rel && tm.outOfScope.some(g => _globMatch(g, rel))) {
+      f.threatModel = { ...(f.threatModel || {}), outOfScope: true };
+      f.severity = 'low';
+      applied++;
+      continue;
+    }
+    if (rel && tm.crownJewels.some(g => _globMatch(g, rel))) {
+      f.threatModel = { ...(f.threatModel || {}), crownJewel: true };
+      f.severity = _bumpSeverity(f.severity || 'medium');
+      applied++;
+    }
+    // Compliance regime tagging based on family.
+    const regimes = FAMILY_TO_REGIME[f.family];
+    if (regimes && tm.compliance.length) {
+      const matched = regimes.filter(r => tm.compliance.includes(r));
+      if (matched.length) {
+        f.threatModel = { ...(f.threatModel || {}), compliance: matched };
+        applied++;
+      }
+    }
+    if (tm.attacker) {
+      f.threatModel = { ...(f.threatModel || {}), attacker: tm.attacker };
+    }
+  }
+  return { applied, total: findings.length, threatModel: tm };
+}
+
+export const _internals = { _extractPathsFromSection, _extractCompliance, _extractAttacker, _bumpSeverity, _globMatch };

package/src/posture/time-to-fix.js

@@ -0,0 +1,129 @@
+// Time-to-fix estimator.
+//
+// Estimates engineering hours to remediate each finding from:
+//
+//   - family base difficulty (regex auth-missing ≠ deserialization)
+//   - patch shape (single-line vs cross-file refactor) from fix.code if present
+//   - prior fix-history for the same family in this project (learned base)
+//   - reachability tier (tests + verify cost adjusts)
+//
+// Output: f.estimatedFixHours, rolled-up totals + a per-family rollup so
+// the PM/PR view can show "this PR ships ~6 hours of security debt."
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const STATE = '.agentic-security';
+const HISTORY_FILE = 'fix-history/log.json';
+
+// Family base estimates (hours). Tuned from typical patch shapes.
+const FAMILY_BASE_HOURS = {
+  'sqli': 0.5, 'sql-injection': 0.5,           // parameterize one query
+  'xss': 0.5, 'mutation-xss': 1.0,
+  'command-injection': 0.5,
+  'code-injection': 2.0,                        // usually needs refactor
+  'deserialization': 4.0,                       // protocol/serializer swap
+  'auth-missing': 0.5,                          // add middleware
+  'authz': 2.0, 'idor': 2.0,                    // ownership checks across handlers
+  'csrf': 1.0,
+  'ssrf': 1.5, 'ssrf-cloud-metadata': 1.0,
+  'xxe': 0.5,
+  'open-redirect': 0.5,
+  'path-traversal': 1.0,
+  'crypto-weak-cipher': 2.0,                    // algorithm swap + key plumbing
+  'crypto-weak-hash': 1.0,
+  'crypto-tls-no-verify': 0.5,
+  'crypto-tls-version': 1.0,
+  'crypto-jwt-none': 0.5,
+  'crypto-jwt-key-confusion': 0.5,
+  'hardcoded-secret': 1.0,                       // env-var plumbing + rotation
+  'vulnerable-dependency': 0.5,                  // npm install bump
+  'dependency-confusion': 1.0,
+  'iam-overpermissive': 1.5,
+  'k8s-rbac-cluster-admin': 1.0,
+  'k8s-pod-security-privileged': 1.0,
+  'prompt-injection': 3.0,                       // architectural — prompt isolation
+  'agent-tool-exec': 4.0,                        // narrow the tool surface
+  'reentrancy': 4.0,                             // Solidity refactor + tests
+  'pqc-migration': 8.0,                          // multi-quarter project
+  'license-graph': 2.0,                          // dep swap or policy negotiation
+};
+
+function _loadFixHistory(scanRoot) {
+  const fp = path.join(scanRoot, STATE, HISTORY_FILE);
+  if (!fs.existsSync(fp)) return [];
+  try {
+    const arr = JSON.parse(fs.readFileSync(fp, 'utf8'));
+    return Array.isArray(arr) ? arr : [];
+  } catch { return []; }
+}
+
+function _historicalAvg(history, family) {
+  const matches = history.filter(h => h.family === family && typeof h.elapsedHours === 'number');
+  if (!matches.length) return null;
+  const sum = matches.reduce((a, b) => a + b.elapsedHours, 0);
+  return sum / matches.length;
+}
+
+function _patchShapeAdjust(finding) {
+  // If we have the synthesized fix code, estimate complexity from size.
+  const code = finding.fix?.code || finding.fix?.replacement || '';
+  if (!code) return 1.0;
+  const lines = code.split('\n').length;
+  if (lines <= 3)  return 1.0;
+  if (lines <= 10) return 1.4;
+  if (lines <= 30) return 2.0;
+  return 3.0;
+}
+
+function _reachAdjust(finding) {
+  // Higher reachability → more careful testing → slightly higher cost.
+  const tier = finding.reachabilityTier;
+  if (tier === 'reachable-public' || tier === 'public-unauthed') return 1.3;
+  if (tier === 'route-reachable')                                return 1.15;
+  if (tier === 'unreachable')                                    return 0.7;
+  return 1.0;
+}
+
+/**
+ * Annotate findings with estimatedFixHours. Returns
+ *   { perFinding: count, totalHours, perFamily: { fam: hours, ... } }
+ */
+export function annotateTimeToFix(scanRoot, findings) {
+  if (!Array.isArray(findings) || findings.length === 0) {
+    return { perFinding: 0, totalHours: 0, perFamily: {} };
+  }
+  const history = _loadFixHistory(scanRoot);
+  let total = 0;
+  const perFamily = {};
+  for (const f of findings) {
+    const base = _historicalAvg(history, f.family) ?? FAMILY_BASE_HOURS[f.family] ?? 1.5;
+    const patchAdj = _patchShapeAdjust(f);
+    const reachAdj = _reachAdjust(f);
+    const hours = Number((base * patchAdj * reachAdj).toFixed(2));
+    f.estimatedFixHours = hours;
+    f.estimatedFixHoursSource = _historicalAvg(history, f.family) != null ? 'history' : 'family-base';
+    total += hours;
+    perFamily[f.family || 'unknown'] = (perFamily[f.family || 'unknown'] || 0) + hours;
+  }
+  return {
+    perFinding: findings.length,
+    totalHours: Number(total.toFixed(1)),
+    perFamily: Object.fromEntries(
+      Object.entries(perFamily)
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, v]) => [k, Number(v.toFixed(1))]),
+    ),
+  };
+}
+
+/**
+ * Render a one-paragraph PM summary.
+ */
+export function renderTimeSummary(roll) {
+  if (!roll || roll.perFinding === 0) return 'No findings — 0 hours of security debt.';
+  const top = Object.entries(roll.perFamily).slice(0, 3).map(([k, v]) => `${k} (${v}h)`).join(', ');
+  return `${roll.perFinding} finding(s) — ~${roll.totalHours} engineering hours of security debt. Top families: ${top}.`;
+}
+
+export const _internals = { FAMILY_BASE_HOURS, _patchShapeAdjust, _reachAdjust, _historicalAvg };