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

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/pqc-migration-plan.js

@@ -0,0 +1,158 @@
+// PQC migration-plan artifact emitter.
+//
+// Aggregates pqc-migration findings (emitted by sast/post-quantum-crypto.js)
+// into a structured plan suitable for an engineering organization to use as
+// a project tracker:
+//
+//   .agentic-security/pqc-migration-plan.json
+//   .agentic-security/pqc-migration-plan.md
+//
+// Buckets findings by:
+//   - HNDL criticality (high-priority — data captured today is harvest-now-decrypt-later
+//     exposure when a CRQC arrives)
+//   - Use case (signing / encryption / KEX) — drives the replacement primitive
+//   - Recommended replacement (ML-KEM-768, ML-DSA-65, etc.)
+//   - File / package locality so the plan can be carved into milestones.
+//
+// Cleartext markdown summarises the top recommendations and milestone
+// suggestions; JSON-LD-shaped structured output is consumable by Vanta /
+// Drata / SecureFrame or any custom rollup dashboard.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function _byHndl(findings) {
+  return {
+    hndlCritical: findings.filter(f => f.hndlCritical),
+    standard: findings.filter(f => !f.hndlCritical),
+  };
+}
+
+function _byUseCase(findings) {
+  const map = new Map();
+  for (const f of findings) {
+    const k = f.pqcRecommendation?.primary || 'unspecified';
+    if (!map.has(k)) map.set(k, []);
+    map.get(k).push(f);
+  }
+  return map;
+}
+
+function _byFile(findings) {
+  const map = new Map();
+  for (const f of findings) {
+    const k = f.file || 'unknown';
+    if (!map.has(k)) map.set(k, []);
+    map.get(k).push(f);
+  }
+  return map;
+}
+
+export function buildMigrationPlan(allFindings) {
+  const pqc = (allFindings || []).filter(f => f.family === 'pqc-migration');
+  if (!pqc.length) return null;
+  const bySev = _byHndl(pqc);
+  const byPrimitive = _byUseCase(pqc);
+  const byFile = _byFile(pqc);
+  const summary = {
+    total: pqc.length,
+    hndlCritical: bySev.hndlCritical.length,
+    standard: bySev.standard.length,
+    filesAffected: byFile.size,
+    primitivesNeeded: Array.from(byPrimitive.keys()),
+  };
+  const milestones = [
+    {
+      id: 'M1',
+      title: 'Inventory & policy',
+      target: '90 days',
+      owner: 'security',
+      items: [
+        'Confirm scanner findings against design docs',
+        'Adopt PQC migration policy (CNSA 2.0 / NIST IR 8547 alignment)',
+        'Establish KMS support for hybrid keys',
+      ],
+    },
+    {
+      id: 'M2',
+      title: 'HNDL-critical paths to PQ-hybrid',
+      target: '180 days',
+      owner: 'platform',
+      items: bySev.hndlCritical.slice(0, 25).map(f => ({
+        finding: f.id, file: f.file, line: f.line,
+        replacement: f.pqcRecommendation?.hybrid || f.pqcRecommendation?.primary,
+      })),
+    },
+    {
+      id: 'M3',
+      title: 'Standard signing/KEX migration',
+      target: '12 months',
+      owner: 'platform',
+      items: bySev.standard.slice(0, 50).map(f => ({
+        finding: f.id, file: f.file, line: f.line,
+        replacement: f.pqcRecommendation?.primary,
+      })),
+    },
+    {
+      id: 'M4',
+      title: 'Deprecate classical primitives',
+      target: '24 months',
+      owner: 'security',
+      items: ['Remove dual-stack libraries once peers are PQ-capable', 'Rotate root CA / long-lived signing keys to ML-DSA'],
+    },
+  ];
+  return {
+    generatedAt: new Date().toISOString(),
+    summary,
+    milestones,
+    perFile: Object.fromEntries(
+      Array.from(byFile.entries()).map(([file, fs]) => [file, {
+        count: fs.length,
+        subfamilies: Array.from(new Set(fs.map(f => f.subfamily))),
+        hndlCritical: fs.some(f => f.hndlCritical),
+      }]),
+    ),
+  };
+}
+
+export function persistMigrationPlan(scanRoot, plan) {
+  if (!plan) return null;
+  try { fs.mkdirSync(path.join(scanRoot, '.agentic-security'), { recursive: true }); } catch {}
+  try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'pqc-migration-plan.json'), JSON.stringify(plan, null, 2)); } catch {}
+  try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'pqc-migration-plan.md'), _markdown(plan)); } catch {}
+  return plan;
+}
+
+function _markdown(plan) {
+  const lines = [];
+  lines.push('# Post-quantum cryptography migration plan');
+  lines.push('');
+  lines.push(`Generated ${plan.generatedAt.slice(0, 10)}.`);
+  lines.push('');
+  lines.push(`**${plan.summary.total}** pre-quantum primitive sites across **${plan.summary.filesAffected}** files.  `);
+  lines.push(`HNDL-critical: **${plan.summary.hndlCritical}** | Standard: **${plan.summary.standard}**`);
+  lines.push('');
+  lines.push('## Recommended PQ primitives');
+  for (const p of plan.summary.primitivesNeeded) lines.push(`- ${p}`);
+  lines.push('');
+  for (const m of plan.milestones) {
+    lines.push(`## ${m.id} — ${m.title} (target ${m.target}, owner ${m.owner})`);
+    if (Array.isArray(m.items) && m.items.length) {
+      for (const it of m.items.slice(0, 20)) {
+        if (typeof it === 'string') lines.push(`- ${it}`);
+        else lines.push(`- \`${it.file}:${it.line}\` → ${it.replacement || '(see finding)'}`);
+      }
+      if (m.items.length > 20) lines.push(`- … ${m.items.length - 20} more`);
+    }
+    lines.push('');
+  }
+  lines.push('## References');
+  lines.push('- NIST FIPS 203 (ML-KEM), FIPS 204 (ML-DSA), FIPS 205 (SLH-DSA)');
+  lines.push('- NIST IR 8547 — Transition to Post-Quantum Cryptographic Standards');
+  lines.push('- CNSA 2.0 — Commercial National Security Algorithm Suite, Sept 2022');
+  lines.push('- RFC 9794 — X25519MLKEM768 hybrid key exchange for TLS 1.3');
+  lines.push('- Open Quantum Safe project (liboqs, oqs-provider for OpenSSL 3)');
+  return lines.join('\n');
+}
+
+export const _internals = { _byHndl, _byUseCase, _byFile, _markdown };

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 };

package/src/posture/reachability-filter.js

@@ -5,6 +5,11 @@
 // module turns that signal into a precision lever: findings marked reachable=
 // false are demoted to severity 'info' with f.unreachable = true.
 //
+// Phase 2 / Item 4 (SCA improvement plan): also demote SCA findings whose
+// reachabilityTier indicates the vulnerable code is not reached by any route
+// handler. Critical+manifest-only on a 500-dep transitive graph would
+// otherwise drown out real reachable bugs.
+//
 // Disabled when scanRoot/--include-unreachable signals are present, or when
 // AGENTIC_SECURITY_INCLUDE_UNREACHABLE=1 is set.
 
@@ -15,6 +20,19 @@ const SEVERITY_DEMOTE = {
   low: 'info',
 };
 
+// SCA reachability tiers, ordered from highest urgency to lowest. A tier
+// in DEMOTE_SCA_TIERS triggers severity demotion; a tier NOT in the set
+// keeps full severity. route-reachable-via-function and function-reachable
+// both keep full severity because the vulnerable function is provably
+// called; import-reachable also keeps full severity (imported = uncertain
+// but plausible). The lower three tiers get demoted.
+const DEMOTE_SCA_TIERS = new Set([
+  'unreachable',       // function never called from project
+  'build-only',        // dev/build-time dependency only
+  'manifest-only',     // declared, but no use observed
+  'transitive-only',   // transitive dep, scope unclear
+]);
+
 export function demoteUnreachable(findings, opts = {}) {
   if (!Array.isArray(findings)) return;
   if (opts.includeUnreachable || process.env.AGENTIC_SECURITY_INCLUDE_UNREACHABLE === '1') return;
@@ -26,9 +44,22 @@ export function demoteUnreachable(findings, opts = {}) {
   if (!haveRoutes) return;
   for (const f of findings) {
     if (!f || typeof f !== 'object') continue;
-    if (f.reachable !== false) continue;
-    if (f.type === 'vulnerable_dep') continue;
     if (f.unreachable) continue;
+    // SCA findings: demote based on reachabilityTier instead of f.reachable
+    // (the latter isn't meaningful for an SCA finding — components don't
+    // have call sites in the SAST sense).
+    if (f.type === 'vulnerable_dep') {
+      if (!DEMOTE_SCA_TIERS.has(f.reachabilityTier)) continue;
+      const beforeSca = f.severity;
+      const afterSca = SEVERITY_DEMOTE[beforeSca];
+      if (!afterSca || beforeSca === afterSca) continue;
+      f.severity = afterSca;
+      f.unreachable = true;
+      f._reachabilityDemoted = beforeSca;
+      f._reachabilityDemoteReason = `tier:${f.reachabilityTier}`;
+      continue;
+    }
+    if (f.reachable !== false) continue;
     // Source has an explicit HTTP/DOM/Form/URL category → engine is confident
     // it's a user-input source even though no route was linked. Don't demote.
     if (f.source && f.source.category && /HTTP|DOM|Form|URL|Query/i.test(f.source.category)) continue;