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

package/src/posture/git-history.js

@@ -0,0 +1,141 @@
+// Git-history-aware finding annotation.
+//
+// For each finding, looks up the introducing commit via `git blame -L
+// <line>,<line>`. Adds:
+//
+//   introducedBy        — author name (or 'AI' if commit message marks it)
+//   introducedIn        — commit SHA (12 chars)
+//   introducedAt        — commit ISO date
+//   introducedInMessage — commit subject line (cap 120 chars)
+//   originatingPrompt   — extracted from commit body when present
+//
+// Then can render a Slack-ready / PR-comment-ready author-ping draft.
+//
+// Conservative: any subprocess error / non-git repo / file-not-tracked
+// leaves the finding unannotated. Caps blame to 1 line per finding (so
+// 200 findings = 200 blame calls). Set AGENTIC_SECURITY_NO_GIT_HISTORY=1
+// to skip entirely.
+
+import * as cp from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const MAX_BLAME_PER_SCAN = 500;
+const SUBPROC_TIMEOUT_MS = 1500;
+const PROMPT_MARKER_RE = /(?:^|\n)(?:Prompt|User asked|Original request|Co-Authored-By:\s*Claude)/i;
+
+function _isGitRepo(scanRoot) {
+  try {
+    cp.execFileSync('git', ['rev-parse', '--git-dir'], { cwd: scanRoot, stdio: 'ignore', timeout: SUBPROC_TIMEOUT_MS });
+    return true;
+  } catch { return false; }
+}
+
+function _blame(scanRoot, file, line) {
+  if (!file || !line || line < 1) return null;
+  const rel = path.isAbsolute(file) ? path.relative(scanRoot, file) : file;
+  if (rel.startsWith('..')) return null;
+  try {
+    const stdout = cp.execFileSync(
+      'git',
+      ['blame', '-L', `${line},${line}`, '--porcelain', '--', rel],
+      { cwd: scanRoot, encoding: 'utf8', timeout: SUBPROC_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    return _parsePorcelain(stdout);
+  } catch { return null; }
+}
+
+function _parsePorcelain(out) {
+  if (!out) return null;
+  const lines = out.split('\n');
+  // First line: <sha> <orig-line> <final-line> <num-lines>
+  const head = lines[0].split(' ');
+  const sha = head[0];
+  if (!sha || sha === '0000000000000000000000000000000000000000') return null;
+  const meta = { sha: sha.slice(0, 12) };
+  for (const ln of lines) {
+    if (ln.startsWith('author '))         meta.author = ln.slice(7);
+    else if (ln.startsWith('author-mail '))  meta.email = ln.slice(12).replace(/[<>]/g, '');
+    else if (ln.startsWith('author-time '))  meta.ts = parseInt(ln.slice(12), 10);
+    else if (ln.startsWith('summary '))      meta.summary = ln.slice(8);
+  }
+  if (meta.ts) meta.at = new Date(meta.ts * 1000).toISOString();
+  return meta;
+}
+
+function _fullMessage(scanRoot, sha) {
+  try {
+    return cp.execFileSync(
+      'git', ['show', '-s', '--format=%B', sha],
+      { cwd: scanRoot, encoding: 'utf8', timeout: SUBPROC_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+  } catch { return ''; }
+}
+
+function _extractPrompt(body) {
+  if (!body || !PROMPT_MARKER_RE.test(body)) return null;
+  // Take the line(s) that follow a "Prompt:" or "User asked:" marker, up to
+  // the next blank line. Truncate to 280 chars.
+  const m = body.match(/(?:Prompt|User asked|Original request)\s*[:\-]\s*([\s\S]*?)(?=\n\s*\n|$)/i);
+  if (!m) return null;
+  return m[1].trim().slice(0, 280);
+}
+
+/**
+ * Annotate findings with git blame + commit context. Returns
+ * { annotated, cached, skipped } counts.
+ */
+export function annotateGitHistory(scanRoot, findings) {
+  if (process.env.AGENTIC_SECURITY_NO_GIT_HISTORY === '1') return { annotated: 0 };
+  if (!Array.isArray(findings) || findings.length === 0) return { annotated: 0 };
+  if (!_isGitRepo(scanRoot)) return { annotated: 0, reason: 'not-a-git-repo' };
+
+  const messageCache = new Map();  // sha → body
+  let annotated = 0, skipped = 0;
+
+  for (let i = 0; i < findings.length && i < MAX_BLAME_PER_SCAN; i++) {
+    const f = findings[i];
+    if (!f || !f.file || !f.line) { skipped++; continue; }
+    const blame = _blame(scanRoot, f.file, f.line);
+    if (!blame) { skipped++; continue; }
+
+    f.introducedBy = blame.author || null;
+    f.introducedIn = blame.sha;
+    f.introducedAt = blame.at || null;
+
+    let body = messageCache.get(blame.sha);
+    if (body === undefined) {
+      body = _fullMessage(scanRoot, blame.sha);
+      messageCache.set(blame.sha, body);
+    }
+    if (body) {
+      const subj = body.split('\n')[0].slice(0, 120);
+      f.introducedInMessage = subj;
+      const prompt = _extractPrompt(body);
+      if (prompt) f.originatingPrompt = prompt;
+      // Mark AI-authored when commit message carries the Claude co-author trailer.
+      if (/Co-Authored-By:\s*Claude/i.test(body)) f.aiAuthored = true;
+    }
+    annotated++;
+  }
+  return { annotated, skipped, capped: findings.length > MAX_BLAME_PER_SCAN };
+}
+
+/**
+ * Generate a Slack-ready / PR-comment author-ping for a finding. Returns
+ * a Markdown string with a per-finding callout.
+ */
+export function generateAuthorPing(finding) {
+  if (!finding || !finding.introducedBy) return null;
+  const where = `${finding.file || '?'}:${finding.line || 0}`;
+  const lines = [];
+  lines.push(`Hey @${finding.introducedBy.replace(/\s+/g, '.')} — heads-up on \`${where}\`:`);
+  lines.push('');
+  lines.push(`- **${(finding.severity || '?').toUpperCase()}** ${finding.vuln || finding.family || 'finding'}`);
+  if (finding.introducedIn) lines.push(`- Introduced in \`${finding.introducedIn}\`${finding.introducedInMessage ? ` — _"${finding.introducedInMessage}"_` : ''}`);
+  if (finding.originatingPrompt) lines.push(`- Originating prompt: _"${finding.originatingPrompt}"_`);
+  lines.push(`- Could you take a look?`);
+  return lines.join('\n');
+}
+
+export const _internals = { _parsePorcelain, _extractPrompt, _isGitRepo };

package/src/posture/intent-context.js

@@ -0,0 +1,175 @@
+// Intent-aware false-positive suppression.
+//
+// Reads project / file / Claude-session context to detect when code is
+// deliberately vulnerable (CTF challenge, sandbox, tutorial, example,
+// fixture) so the scanner can demote findings rather than presenting them
+// as production-grade issues.
+//
+// Signal sources (in order of strength):
+//
+//   1. .agentic-security/current-intent.md
+//      A file Claude (or the user) writes to declare the current
+//      session's intent. The PreToolUse / SessionStart hook can populate
+//      this from the recent transcript. Format:
+//        # Intent
+//        - tutorial: building an intentional SQLi demo for our security training
+//        - excluded-paths: ["examples/sqli-demo/**"]
+//
+//   2. File header comments (first ~1500 chars):
+//      @sandbox / @example / @intentionally-vulnerable / @ctf-challenge /
+//      @demo / @tutorial / // INTENTIONALLY VULNERABLE
+//
+//   3. Path patterns: examples/, demo/, demos/, tutorial/, sandbox/,
+//      playground/, challenges/, ctf/
+//
+//   4. CLAUDE.md section headed "Intentionally vulnerable" / "Out of scope"
+//
+// Opt-out: AGENTIC_SECURITY_NO_INTENT_CTX=1
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const INTENT_PATH_RE = /(?:^|\/)(?:examples?|demos?|tutorials?|sandbox|playground|challenges?|ctf)(?:\/|$)/i;
+
+const FILE_HEADER_MARKERS = [
+  /@sandbox\b/i,
+  /@example\b/i,
+  /@intentionally[-_]?vulnerable\b/i,
+  /@ctf[-_]?challenge\b/i,
+  /@demo\b/i,
+  /@tutorial\b/i,
+  /(?:^|[^A-Za-z])INTENTIONALLY[- ]?VULNERABLE(?:[^A-Za-z]|$)/,
+  /(?:^|[^A-Za-z])DELIBERATELY[- ]?UNSAFE(?:[^A-Za-z]|$)/,
+];
+
+const HEADER_BUDGET = 1500;
+
+function _readSafely(fp) {
+  try { return fs.readFileSync(fp, 'utf8'); } catch { return ''; }
+}
+
+function _readIntentDeclaration(scanRoot) {
+  const fp = path.join(scanRoot, '.agentic-security', 'current-intent.md');
+  if (!fs.existsSync(fp)) return null;
+  const body = _readSafely(fp);
+  if (!body) return null;
+  const exMatch = body.match(/excluded-paths\s*:\s*\[([\s\S]*?)\]/);
+  let excludedPaths = [];
+  if (exMatch) {
+    excludedPaths = (exMatch[1].match(/"([^"]+)"|'([^']+)'/g) || [])
+      .map(s => s.replace(/['"]/g, ''));
+  }
+  return { body, excludedPaths };
+}
+
+function _claudeMdHasOutOfScope(scanRoot) {
+  const fp = path.join(scanRoot, 'CLAUDE.md');
+  if (!fs.existsSync(fp)) return [];
+  const body = _readSafely(fp);
+  const out = [];
+  const re = /^#{1,3}\s+(?:Out[- ]of[- ]scope|Intentionally vulnerable|Sandbox|Examples?)[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/gim;
+  let m;
+  while ((m = re.exec(body))) {
+    const sec = m[0];
+    // Pull file globs / paths from the section.
+    const paths = (sec.match(/`([^`]+)`/g) || []).map(s => s.replace(/`/g, ''));
+    out.push(...paths.filter(p => /\/|\*/.test(p)));
+  }
+  return out;
+}
+
+function _fileHeaderHasIntent(file) {
+  if (!file) return false;
+  try {
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(HEADER_BUDGET);
+    fs.readSync(fd, buf, 0, HEADER_BUDGET, 0);
+    fs.closeSync(fd);
+    const head = buf.toString('utf8');
+    return FILE_HEADER_MARKERS.some(re => re.test(head));
+  } catch { return false; }
+}
+
+function _globMatch(pattern, p) {
+  // Minimal glob: `**` → `.*`, `*` → `[^/]*`. Path separators normalized.
+  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);
+}
+
+/**
+ * Extract intent signals once per scan.
+ */
+export function extractIntentSignals(scanRoot) {
+  if (process.env.AGENTIC_SECURITY_NO_INTENT_CTX === '1') {
+    return { declaredExcludedPaths: [], claudeMdExcludedPaths: [], intent: null };
+  }
+  const decl = _readIntentDeclaration(scanRoot);
+  const claudeMdPaths = _claudeMdHasOutOfScope(scanRoot);
+  return {
+    declaredExcludedPaths: decl ? decl.excludedPaths : [],
+    claudeMdExcludedPaths: claudeMdPaths,
+    intent: decl ? decl.body : null,
+  };
+}
+
+/**
+ * Per-finding suppression. Returns the count of findings demoted.
+ * Findings are mutated in place — sets `intentSuppressed=true`, drops
+ * confidence by 50%, adds 'intent-suppressed' tag.
+ */
+export function suppressByIntent(scanRoot, findings) {
+  if (process.env.AGENTIC_SECURITY_NO_INTENT_CTX === '1') return { applied: 0 };
+  if (!Array.isArray(findings) || findings.length === 0) return { applied: 0 };
+  const signals = extractIntentSignals(scanRoot);
+  const allExcluded = [...signals.declaredExcludedPaths, ...signals.claudeMdExcludedPaths];
+
+  let applied = 0;
+  const fileHeaderCache = new Map();
+
+  for (const f of findings) {
+    const file = f.file || '';
+    const rel = path.isAbsolute(file) ? path.relative(scanRoot, file) : file;
+    let suppress = false;
+    let reason = null;
+
+    if (INTENT_PATH_RE.test(rel)) { suppress = true; reason = 'intent-path-pattern'; }
+
+    if (!suppress && allExcluded.length) {
+      for (const pat of allExcluded) {
+        if (_globMatch(pat, rel)) { suppress = true; reason = 'intent-declared-exclusion'; break; }
+      }
+    }
+
+    if (!suppress && file) {
+      let hdr = fileHeaderCache.get(file);
+      if (hdr === undefined) {
+        hdr = _fileHeaderHasIntent(file);
+        fileHeaderCache.set(file, hdr);
+      }
+      if (hdr) { suppress = true; reason = 'intent-file-header'; }
+    }
+
+    if (suppress) {
+      f.intentSuppressed = true;
+      f.intentReason = reason;
+      if (typeof f.confidence === 'number') f.confidence = Math.max(0.15, f.confidence * 0.5);
+      f.tags = Array.isArray(f.tags) ? f.tags : [];
+      if (!f.tags.includes('intent-suppressed')) f.tags.push('intent-suppressed');
+      applied++;
+    }
+  }
+  return { applied, total: findings.length };
+}
+
+export const _internals = {
+  INTENT_PATH_RE, FILE_HEADER_MARKERS,
+  _readIntentDeclaration, _claudeMdHasOutOfScope, _fileHeaderHasIntent, _globMatch,
+};

package/src/posture/model-rescan.js

@@ -0,0 +1,76 @@
+// Model-of-the-month re-scan delta.
+//
+// Re-runs the LLM validator (already opt-in via AGENTIC_SECURITY_LLM_VALIDATE)
+// with a different model and produces a delta report: which findings the
+// newer model marked TP that the prior model marked FP (or vice versa),
+// what newer reasoning catches that older reasoning missed.
+//
+// Use case: every time Anthropic ships a new Claude model (or you want to
+// A/B against gpt-5 / a custom finetune), re-validate the last scan and see
+// which findings change verdict.
+//
+// Output: .agentic-security/model-rescan/<from>-vs-<to>.json with:
+//   { from, to, changed: [{ finding_id, before, after, why }], ts }
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const STATE = '.agentic-security';
+
+function _readJson(scanRoot, name) {
+  try { return JSON.parse(fs.readFileSync(path.join(scanRoot, STATE, name), 'utf8')); } catch { return null; }
+}
+
+/**
+ * Compare two validator runs by finding_id. Each run is a JSON like:
+ *   { model: 'claude-sonnet-4', results: { findingId: { verdict, reason }, ... } }
+ */
+export function diffValidatorRuns(runA, runB) {
+  const a = runA && runA.results ? runA.results : {};
+  const b = runB && runB.results ? runB.results : {};
+  const ids = new Set([...Object.keys(a), ...Object.keys(b)]);
+  const changed = [];
+  for (const id of ids) {
+    const av = (a[id] && a[id].verdict) || null;
+    const bv = (b[id] && b[id].verdict) || null;
+    if (av !== bv) {
+      changed.push({
+        finding_id: id,
+        before: av,
+        after: bv,
+        before_reason: a[id]?.reason || null,
+        after_reason: b[id]?.reason || null,
+      });
+    }
+  }
+  return changed;
+}
+
+/**
+ * Persist a model-rescan report. Returns the file path.
+ */
+export function persistRescanReport(scanRoot, from, to, changed) {
+  const dir = path.join(scanRoot, STATE, 'model-rescan');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  const safe = (s) => String(s || 'unknown').replace(/[^\w.-]/g, '-');
+  const fp = path.join(dir, `${safe(from)}-vs-${safe(to)}.json`);
+  const report = { from, to, ts: new Date().toISOString(), changed };
+  try { fs.writeFileSync(fp, JSON.stringify(report, null, 2)); } catch {}
+  return fp;
+}
+
+/**
+ * Build a quick natural-language summary of the delta.
+ */
+export function summarizeDelta(changed) {
+  if (!Array.isArray(changed) || !changed.length) return 'No changes — validators agree on every finding.';
+  const flipsToTP = changed.filter(c => c.before === 'fp' && c.after === 'tp');
+  const flipsToFP = changed.filter(c => c.before === 'tp' && c.after === 'fp');
+  const lines = [];
+  lines.push(`${changed.length} verdict change(s) between models:`);
+  if (flipsToTP.length) lines.push(`  ${flipsToTP.length} finding(s) now confirmed TP (newer model caught what older missed)`);
+  if (flipsToFP.length) lines.push(`  ${flipsToFP.length} finding(s) now FP (newer model recognized as safe)`);
+  return lines.join('\n');
+}
+
+export const _internals = {};

package/src/posture/pattern-propagation.js

@@ -0,0 +1,39 @@
+// Pattern propagation — annotator that surfaces cross-repo signals on
+// findings. For each finding, queries the cross-repo store for past
+// fixes and triage decisions on the same family from sibling repos and
+// stamps the finding with a crossRepoSignal field.
+//
+// The /show-findings command / PR-augment / explain_finding MCP tool
+// can render the signal alongside the finding so the developer sees
+// "you already fixed this exact shape in repo X."
+//
+// Pure annotator — no LLM calls. Opt-out via the cross-repo-memory
+// AGENTIC_SECURITY_NO_CROSS_REPO=1 flag.
+
+import { findSiblingSignals, renderSiblingNote } from './cross-repo-memory.js';
+
+export function annotateCrossRepoSignals(scanRoot, findings) {
+  if (process.env.AGENTIC_SECURITY_NO_CROSS_REPO === '1') return { annotated: 0 };
+  if (!Array.isArray(findings) || findings.length === 0) return { annotated: 0 };
+  let annotated = 0;
+  // De-duplicate signal lookups per family — many findings share a family.
+  const sigCache = new Map();
+  for (const f of findings) {
+    const fam = f.family;
+    if (!fam) continue;
+    let signals = sigCache.get(fam);
+    if (signals === undefined) {
+      signals = findSiblingSignals(scanRoot, f);
+      sigCache.set(fam, signals);
+    }
+    if (signals.siblingFixes.length || signals.siblingTriage.length) {
+      f.crossRepoSignal = {
+        fixes:  signals.siblingFixes.length,
+        triage: signals.siblingTriage.length,
+        note:   renderSiblingNote(signals),
+      };
+      annotated++;
+    }
+  }
+  return { annotated, total: findings.length };
+}

package/src/posture/pr-augment.js

@@ -0,0 +1,234 @@
+// PR-description auto-augmentation.
+//
+// Reads the current last-scan vs a baseline (git base branch or
+// a stored snapshot), and produces a Markdown block suitable for
+// injecting into a PR body via `gh pr edit --body` or chaining into
+// `gh pr create`.
+//
+// Output sections:
+//   1. Security delta summary (added / removed / changed by severity)
+//   2. ATT&CK tactics covered by new findings
+//   3. Suggested reviewers by class (auth changes → security; PII → privacy)
+//   4. Links to relevant artifacts (threat-model, compliance-evidence,
+//      PQC plan, exploit bundles) when present
+//
+// Pure render — does not call git or gh; caller orchestrates that.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { diffScans, summarizeDiff } from './baseline-compare.js';
+
+const REVIEWER_TRIGGERS = [
+  { family: /^auth/,                team: 'security', why: 'Auth-related findings' },
+  { family: /^crypto/,              team: 'security', why: 'Cryptography findings' },
+  { family: /^pii|gdpr|hipaa/i,     team: 'privacy',  why: 'PII / data-handling findings' },
+  { family: /^iam|cloud|k8s/,       team: 'platform', why: 'Cloud / Kubernetes posture findings' },
+  { family: /^supply|license|vuln/, team: 'platform', why: 'Supply-chain findings' },
+  { family: /^llm|prompt|ml/,       team: 'ml',       why: 'LLM / ML supply-chain findings' },
+  { family: /^web3|defi/,           team: 'security', why: 'Smart-contract findings' },
+];
+
+function _stateFile(scanRoot, name) {
+  return path.join(scanRoot, '.agentic-security', name);
+}
+
+function _readJson(fp) {
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
+}
+
+function _baselinePath(scanRoot, ref) {
+  const safe = String(ref || 'main').replace(/[^\w.-]/g, '-');
+  return path.join(scanRoot, '.agentic-security', 'scan-baselines', `${safe}.json`);
+}
+
+/**
+ * Persist a scan snapshot under .agentic-security/scan-baselines/<ref>.json
+ * so subsequent PRs can diff against it.
+ */
+export function persistBaseline(scanRoot, ref, scan) {
+  const fp = _baselinePath(scanRoot, ref);
+  try { fs.mkdirSync(path.dirname(fp), { recursive: true }); } catch {}
+  try { fs.writeFileSync(fp, JSON.stringify({ ref, ts: new Date().toISOString(), findings: scan.findings || [] }, null, 2)); } catch {}
+  return fp;
+}
+
+export function loadBaseline(scanRoot, ref) {
+  return _readJson(_baselinePath(scanRoot, ref));
+}
+
+/**
+ * Recommended reviewers derived from the diff's added-findings.
+ */
+function _suggestReviewers(addedFindings) {
+  const hits = new Map();  // team → {why: Set, count: number}
+  for (const f of addedFindings) {
+    for (const t of REVIEWER_TRIGGERS) {
+      if (t.family.test(f.family || '')) {
+        if (!hits.has(t.team)) hits.set(t.team, { why: new Set(), count: 0 });
+        const ent = hits.get(t.team);
+        ent.why.add(t.why);
+        ent.count++;
+        break;
+      }
+    }
+  }
+  return Array.from(hits.entries()).map(([team, ent]) => ({
+    team, count: ent.count, why: Array.from(ent.why),
+  })).sort((a, b) => b.count - a.count);
+}
+
+/**
+ * ATT&CK techniques surfaced by added findings (attack-taxonomy annotator
+ * must have run for this to be populated).
+ */
+function _addedAttckSummary(addedFindings) {
+  const map = new Map();
+  for (const f of addedFindings) {
+    for (const t of (f.attck || [])) {
+      if (!map.has(t)) map.set(t, { count: 0, name: f.attckName || t });
+      map.get(t).count++;
+    }
+  }
+  return Array.from(map.entries())
+    .sort((a, b) => b[1].count - a[1].count)
+    .slice(0, 8)
+    .map(([id, v]) => ({ id, name: v.name, count: v.count }));
+}
+
+/**
+ * Artifact links — pull file paths that exist under .agentic-security/.
+ */
+function _artifactLinks(scanRoot) {
+  const candidates = [
+    { name: 'Threat model',         file: 'threat-model.md' },
+    { name: 'Compliance evidence',  file: 'compliance-evidence.md' },
+    { name: 'PQC migration plan',   file: 'pqc-migration-plan.md' },
+    { name: 'DPIA',                 file: 'dpia.md' },
+    { name: 'ATTRIBUTIONS',         file: 'ATTRIBUTIONS.md' },
+    { name: 'NOTICE',               file: 'NOTICE' },
+  ];
+  const out = [];
+  for (const c of candidates) {
+    const fp = path.join(scanRoot, '.agentic-security', c.file);
+    if (fs.existsSync(fp)) out.push({ name: c.name, path: `.agentic-security/${c.file}` });
+  }
+  return out;
+}
+
+/**
+ * Render a Markdown PR-body augmentation block.
+ *
+ * @param {string} scanRoot
+ * @param {object} opts
+ *   - baselineRef: string  (default 'main')
+ *   - title: string        section title (default 'Security review')
+ *   - blocking: bool       if true, prepend a 🛑 block-merge banner when new criticals added
+ */
+export function augmentPrBody(scanRoot, opts = {}) {
+  const baselineRef = opts.baselineRef || 'main';
+  const title = opts.title || 'Security review (automated)';
+  const blocking = opts.blocking !== false;
+
+  const current = _readJson(_stateFile(scanRoot, 'last-scan.json'));
+  if (!current) return { ok: false, error: 'No .agentic-security/last-scan.json — run a scan first.' };
+
+  const baseline = loadBaseline(scanRoot, baselineRef);
+  const diff = baseline ? diffScans(baseline, current) : { added: current.findings || [], removed: [], changed: [], unchanged: 0 };
+  const summary = summarizeDiff(diff);
+
+  const lines = [];
+  lines.push(`## ${title}`);
+  lines.push('');
+
+  if (!baseline) {
+    lines.push(`> Baseline against \`${baselineRef}\` not found — showing the full current scan as added. Run \`/pr-augment --persist-baseline ${baselineRef}\` from \`${baselineRef}\` to enable diff mode.`);
+    lines.push('');
+  }
+
+  const newCriticals = summary.bySeverity.critical?.added || 0;
+  const newHighs    = summary.bySeverity.high?.added || 0;
+
+  if (blocking && newCriticals > 0) {
+    lines.push(`> 🛑 **${newCriticals} new critical finding(s)** — recommend blocking merge until resolved.`);
+    lines.push('');
+  } else if (newHighs > 0) {
+    lines.push(`> ⚠️  **${newHighs} new high-severity finding(s)** — review before merging.`);
+    lines.push('');
+  } else if (summary.addedCount === 0) {
+    lines.push('> ✅ No new findings vs baseline.');
+    lines.push('');
+  }
+
+  // Delta table
+  lines.push('### Findings delta vs `' + baselineRef + '`');
+  lines.push('');
+  lines.push('| Severity | Added | Removed |');
+  lines.push('|---|---:|---:|');
+  for (const sev of ['critical', 'high', 'medium', 'low']) {
+    const s = summary.bySeverity[sev] || { added: 0, removed: 0 };
+    lines.push(`| ${sev} | ${s.added} | ${s.removed} |`);
+  }
+  lines.push('');
+
+  // ATT&CK tactics
+  const attck = _addedAttckSummary(diff.added);
+  if (attck.length) {
+    lines.push('### MITRE ATT&CK techniques (new findings)');
+    lines.push('');
+    for (const t of attck) lines.push(`- \`${t.id}\` ${t.name} (${t.count})`);
+    lines.push('');
+  }
+
+  // Suggested reviewers
+  const reviewers = _suggestReviewers(diff.added);
+  if (reviewers.length) {
+    lines.push('### Suggested reviewers');
+    lines.push('');
+    for (const r of reviewers) lines.push(`- **${r.team}** — ${r.why.join('; ')} (${r.count})`);
+    lines.push('');
+  }
+
+  // Top 5 added findings
+  if (diff.added.length) {
+    const top = diff.added
+      .slice()
+      .sort((a, b) => (sevRank(b.severity) - sevRank(a.severity)) || ((b.confidence || 0) - (a.confidence || 0)))
+      .slice(0, 5);
+    lines.push('### Top added findings');
+    lines.push('');
+    for (const f of top) {
+      const where = `${f.file || '?'}:${f.line || 0}`;
+      lines.push(`- **[${(f.severity || '?').toUpperCase()}]** ${f.vuln || f.family || 'finding'} — \`${where}\``);
+    }
+    lines.push('');
+  }
+
+  // Artifact links
+  const arts = _artifactLinks(scanRoot);
+  if (arts.length) {
+    lines.push('### Posture artifacts');
+    lines.push('');
+    for (const a of arts) lines.push(`- [${a.name}](${a.path})`);
+    lines.push('');
+  }
+
+  lines.push('_Generated by [agentic-security](https://github.com/Clear-Capabilities/agentic-security)._');
+
+  return {
+    ok: true,
+    body: lines.join('\n'),
+    summary: {
+      newCriticals,
+      newHighs,
+      added: summary.addedCount,
+      removed: summary.removedCount,
+      reviewers,
+    },
+  };
+}
+
+function sevRank(s) {
+  return { critical: 4, high: 3, medium: 2, low: 1, info: 0 }[s] || 0;
+}
+
+export const _internals = { _suggestReviewers, _addedAttckSummary, _artifactLinks, _baselinePath };