@clear-capabilities/agentic-security-scanner 0.74.0

package/src/posture/deploy-platform.js

@@ -0,0 +1,204 @@
+// Deployment-platform security checklist.
+//
+// Detects which hosting platform a project targets from config files and
+// returns platform-specific security findings: missing headers, public previews,
+// no health checks, unsafe infra settings.
+//
+// Platforms: Vercel, Railway, Fly.io, Render, Netlify, AWS Amplify, Cloudflare
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function _readJson(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return null; }
+}
+function _readText(filePath) {
+  try { return fs.readFileSync(filePath, 'utf8'); } catch { return null; }
+}
+function _exists(filePath) {
+  try { fs.accessSync(filePath); return true; } catch { return false; }
+}
+
+// ── Vercel ────────────────────────────────────────────────────────────────────
+
+function checkVercel(root) {
+  const cfgPath = path.join(root, 'vercel.json');
+  const cfg = _readJson(cfgPath);
+  const findings = [];
+
+  // Check next.config.js / next.config.ts for security headers
+  const nextCfgPath = ['next.config.js','next.config.ts','next.config.mjs'].map(f=>path.join(root,f)).find(_exists);
+  const nextCfg = nextCfgPath ? _readText(nextCfgPath) : null;
+
+  const hasSecurityHeaders = (cfg && cfg.headers && JSON.stringify(cfg.headers).includes('X-Frame-Options')) ||
+    (nextCfg && /X-Frame-Options|Content-Security-Policy|X-Content-Type-Options/.test(nextCfg));
+
+  if (!hasSecurityHeaders) {
+    findings.push({
+      id: `deploy-platform:VERCEL_NO_SECURITY_HEADERS:${cfgPath || 'vercel.json'}:1`,
+      title: 'Vercel deployment missing security headers',
+      severity: 'medium',
+      file: cfgPath || 'vercel.json',
+      line: 1,
+      description: 'No X-Frame-Options, Content-Security-Policy, or X-Content-Type-Options headers are configured. These headers block clickjacking, MIME sniffing, and XSS attacks at the CDN layer for zero performance cost.',
+      remediation: 'Add a `headers` array to vercel.json or a `headers()` function in next.config.js:\n  { key: "X-Frame-Options", value: "DENY" }\n  { key: "X-Content-Type-Options", value: "nosniff" }\n  { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }',
+      cwe: 'CWE-693',
+    });
+  }
+
+  // Preview deployments expose the app publicly by default
+  const hasPasswordProtection = cfg && (cfg.password || (cfg.passwordProtection));
+  if (!hasPasswordProtection && _exists(path.join(root, '.vercel'))) {
+    findings.push({
+      id: `deploy-platform:VERCEL_PUBLIC_PREVIEWS:vercel.json:1`,
+      title: 'Vercel preview deployments are publicly accessible',
+      severity: 'low',
+      file: 'vercel.json',
+      line: 1,
+      description: 'Preview deployments on Vercel are publicly accessible by default. Staging data, admin interfaces, and unreleased features are visible to anyone with the URL.',
+      remediation: 'Enable Vercel\'s Deployment Protection (passwordProtection or Vercel Authentication) for preview branches in your project settings, or add `"protection": { "deploymentType": "all" }` to vercel.json (Vercel Pro).',
+      cwe: 'CWE-284',
+    });
+  }
+
+  return findings;
+}
+
+// ── Railway ───────────────────────────────────────────────────────────────────
+
+function checkRailway(root) {
+  const cfgPath = path.join(root, 'railway.json');
+  const tomlPath = path.join(root, 'railway.toml');
+  const cfg = _readJson(cfgPath);
+  const tomlRaw = _readText(tomlPath);
+  const findings = [];
+
+  const hasHealthCheck = (cfg && (cfg.deploy?.healthcheckPath || cfg.healthcheck)) ||
+    (tomlRaw && /healthcheck/.test(tomlRaw));
+
+  if (!hasHealthCheck && (cfg || tomlRaw)) {
+    findings.push({
+      id: `deploy-platform:RAILWAY_NO_HEALTHCHECK:${cfgPath || tomlPath}:1`,
+      title: 'Railway deployment missing health check',
+      severity: 'low',
+      file: cfgPath || tomlPath || 'railway.json',
+      line: 1,
+      description: 'No health check endpoint is configured. Without one, Railway cannot detect a crashed or deadlocked process and will continue routing traffic to an unhealthy instance.',
+      remediation: 'Add a health check to railway.json:\n  { "deploy": { "healthcheckPath": "/api/health", "healthcheckTimeout": 10 } }\nAnd implement a GET /api/health endpoint that returns 200 when the app is ready.',
+      cwe: 'CWE-400',
+    });
+  }
+
+  return findings;
+}
+
+// ── Fly.io ────────────────────────────────────────────────────────────────────
+
+function checkFly(root) {
+  const cfgPath = path.join(root, 'fly.toml');
+  const raw = _readText(cfgPath);
+  if (!raw) return [];
+  const findings = [];
+
+  // Check for services exposed without auto_stop_machines
+  if (/\[services\]/.test(raw) && !/auto_stop_machines\s*=\s*true/.test(raw)) {
+    findings.push({
+      id: `deploy-platform:FLY_NO_SCALE_TO_ZERO:fly.toml:1`,
+      title: 'Fly.io app keeps machines running indefinitely',
+      severity: 'low',
+      file: 'fly.toml',
+      line: 1,
+      description: 'auto_stop_machines is not enabled. Idle machines continue running and accumulating cost, and a compromised idle machine persists longer than necessary.',
+      remediation: 'Set `auto_stop_machines = true` and `auto_start_machines = true` in the [http_service] section of fly.toml to enable scale-to-zero.',
+      cwe: 'CWE-400',
+    });
+  }
+
+  // Check for HTTP→HTTPS redirect
+  if (!/force_https\s*=\s*true/.test(raw)) {
+    findings.push({
+      id: `deploy-platform:FLY_NO_HTTPS_REDIRECT:fly.toml:1`,
+      title: 'Fly.io app does not enforce HTTPS',
+      severity: 'medium',
+      file: 'fly.toml',
+      line: 1,
+      description: 'force_https is not set. HTTP requests are served unencrypted, exposing session cookies and auth tokens to network interception.',
+      remediation: 'Add `force_https = true` to the [[services]] section in fly.toml.',
+      cwe: 'CWE-319',
+    });
+  }
+
+  return findings;
+}
+
+// ── Netlify ───────────────────────────────────────────────────────────────────
+
+function checkNetlify(root) {
+  const cfgPath = path.join(root, 'netlify.toml');
+  const raw = _readText(cfgPath);
+  if (!raw) return [];
+  const findings = [];
+
+  if (!/X-Frame-Options|Content-Security-Policy/.test(raw)) {
+    findings.push({
+      id: `deploy-platform:NETLIFY_NO_SECURITY_HEADERS:netlify.toml:1`,
+      title: 'Netlify deployment missing security headers',
+      severity: 'medium',
+      file: 'netlify.toml',
+      line: 1,
+      description: 'No security headers (X-Frame-Options, CSP) are configured in netlify.toml. These are free protections against clickjacking and XSS.',
+      remediation: 'Add to netlify.toml:\n  [[headers]]\n    for = "/*"\n    [headers.values]\n      X-Frame-Options = "DENY"\n      X-Content-Type-Options = "nosniff"\n      Referrer-Policy = "strict-origin-when-cross-origin"',
+      cwe: 'CWE-693',
+    });
+  }
+
+  return findings;
+}
+
+// ── Cloudflare ────────────────────────────────────────────────────────────────
+
+function checkCloudflare(root) {
+  const wranglerPath = ['wrangler.toml','wrangler.json'].map(f=>path.join(root,f)).find(_exists);
+  if (!wranglerPath) return [];
+  const raw = _readText(wranglerPath);
+  const findings = [];
+
+  // Workers with no compatibility_date are using legacy APIs
+  if (raw && !/compatibility_date/.test(raw)) {
+    findings.push({
+      id: `deploy-platform:CF_NO_COMPAT_DATE:${wranglerPath}:1`,
+      title: 'Cloudflare Worker missing compatibility_date',
+      severity: 'low',
+      file: wranglerPath,
+      line: 1,
+      description: 'Without compatibility_date, your Worker uses Cloudflare\'s oldest runtime behaviour, which may include known-insecure APIs.',
+      remediation: `Set compatibility_date = "${new Date().toISOString().slice(0,10)}" in wrangler.toml to opt into the latest, most secure runtime semantics.`,
+      cwe: 'CWE-1104',
+    });
+  }
+
+  return findings;
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+function scanDeployPlatform(scanRoot) {
+  const findings = [];
+  if (!scanRoot) return findings;
+
+  const vercelIndicators = ['vercel.json', '.vercel', 'next.config.js', 'next.config.ts', 'next.config.mjs'];
+  const railwayIndicators = ['railway.json', 'railway.toml'];
+  const flyIndicators = ['fly.toml'];
+  const netlifyIndicators = ['netlify.toml'];
+  const cfIndicators = ['wrangler.toml', 'wrangler.json'];
+
+  if (vercelIndicators.some(f => _exists(path.join(scanRoot, f)))) findings.push(...checkVercel(scanRoot));
+  if (railwayIndicators.some(f => _exists(path.join(scanRoot, f)))) findings.push(...checkRailway(scanRoot));
+  if (flyIndicators.some(f => _exists(path.join(scanRoot, f)))) findings.push(...checkFly(scanRoot));
+  if (netlifyIndicators.some(f => _exists(path.join(scanRoot, f)))) findings.push(...checkNetlify(scanRoot));
+  if (cfIndicators.some(f => _exists(path.join(scanRoot, f)))) findings.push(...checkCloudflare(scanRoot));
+
+  return findings;
+}
+
+export { scanDeployPlatform };

package/src/posture/detector-fuzz.js

@@ -0,0 +1,61 @@
+// FR-ADV-6 — Adversarial fuzzing of detectors.
+//
+// Take a known-vuln fixture, mutate it across N strategies (using the
+// adversarial-self-test mutator), and ask "does the scanner still catch
+// every mutation?" Mutations that escape detection become regression fixtures.
+//
+// This module is the bench-side orchestrator. The mutation library lives in
+// adversarial-self-test.js. The runner here is purely structural — it does
+// NOT execute the scanner against the mutated text; that's the caller's
+// responsibility (the runner has access to the scanner; this module is pure
+// data).
+//
+// Public API:
+//   prepareFuzzCorpus(fixtures)  → returns the mutation matrix ready to run
+//   recordOutcome(matrixEntry, detected) → folds result back into matrix
+//   summarize(matrix) → per-family escape rate
+
+import { mutateSnippet } from './adversarial-self-test.js';
+
+export function prepareFuzzCorpus(fixtures) {
+  if (!Array.isArray(fixtures)) return [];
+  const out = [];
+  for (const fx of fixtures) {
+    if (!fx || !fx.family || !fx.code) continue;
+    const mutations = mutateSnippet(fx.code, fx.family);
+    for (let i = 0; i < mutations.length; i++) {
+      out.push({
+        fixtureId: fx.id || `${fx.family}-${fx.file || 'inline'}`,
+        family: fx.family,
+        mutationIndex: i,
+        mutationStrategy: `mut-${i + 1}`,
+        mutatedCode: mutations[i],
+        detected: null,
+      });
+    }
+  }
+  return out;
+}
+
+export function recordOutcome(entry, detected) {
+  if (!entry || typeof entry !== 'object') return;
+  entry.detected = !!detected;
+}
+
+export function summarize(matrix) {
+  if (!Array.isArray(matrix)) return { perFamily: {}, totalEscaped: 0 };
+  const perFamily = {};
+  let totalEscaped = 0;
+  for (const e of matrix) {
+    if (e.detected === null) continue;
+    if (!perFamily[e.family]) perFamily[e.family] = { run: 0, escaped: 0, detected: 0 };
+    perFamily[e.family].run++;
+    if (e.detected) perFamily[e.family].detected++;
+    else { perFamily[e.family].escaped++; totalEscaped++; }
+  }
+  for (const k of Object.keys(perFamily)) {
+    const v = perFamily[k];
+    v.escapeRate = v.run ? Number((v.escaped / v.run).toFixed(2)) : 0;
+  }
+  return { perFamily, totalEscaped };
+}

package/src/posture/deterministic.js

@@ -0,0 +1,99 @@
+// Deterministic mode + rule version lockfile.
+//
+// `--deterministic` makes scan output byte-stable for the same input:
+//   - stable-sorts every findings array by (file, line, vuln, id)
+//   - strips timing/scanId variance from meta
+//   - sets AGENTIC_SECURITY_DETERMINISTIC=1 so other modules (network calls,
+//     KEV cache invalidation, EPSS fetches, blast-radius timestamps) can opt
+//     into deterministic behavior
+//
+// `agentic-security rules lock` writes .agentic-security/rules.lock.json
+// pinning the active rule-pack hash + scanner version. Subsequent scans with
+// `--deterministic` verify the lock matches before running.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { PACKS } from './rule-packs.js';
+
+export const SCANNER_VERSION = '0.39.2';
+const LOCK_FILE = 'rules.lock.json';
+
+// Hash the union of pack CWE sets — stable across runs as long as PACKS is unchanged.
+export function computeRulePackHash() {
+  const sorted = Object.entries(PACKS)
+    .map(([name, p]) => [name, [...p.cwes].sort()])
+    .sort(([a], [b]) => a.localeCompare(b));
+  return crypto.createHash('sha256').update(JSON.stringify(sorted)).digest('hex').slice(0, 16);
+}
+
+export function buildLockfile() {
+  return {
+    schema: 1,
+    scannerVersion: SCANNER_VERSION,
+    rulePackHash: computeRulePackHash(),
+    rulePacks: Object.fromEntries(
+      Object.entries(PACKS).map(([n, p]) => [n, { cweCount: p.cwes.length }])
+    ),
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+export function writeLockfile(scanRoot) {
+  const dir = path.join(scanRoot, '.agentic-security');
+  fs.mkdirSync(dir, { recursive: true });
+  const fp = path.join(dir, LOCK_FILE);
+  const lock = buildLockfile();
+  fs.writeFileSync(fp, JSON.stringify(lock, null, 2));
+  return { path: fp, lock };
+}
+
+export function readLockfile(scanRoot) {
+  const fp = path.join(scanRoot, '.agentic-security', LOCK_FILE);
+  if (!fs.existsSync(fp)) return null;
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
+}
+
+// Verify the current engine matches a previously-written lockfile.
+// Returns { ok, mismatches: [...] }.
+export function verifyLockfile(scanRoot) {
+  const lock = readLockfile(scanRoot);
+  if (!lock) return { ok: false, mismatches: ['no lockfile present'] };
+  const mismatches = [];
+  if (lock.scannerVersion !== SCANNER_VERSION) {
+    mismatches.push(`scanner version: lock=${lock.scannerVersion} current=${SCANNER_VERSION}`);
+  }
+  const currentHash = computeRulePackHash();
+  if (lock.rulePackHash !== currentHash) {
+    mismatches.push(`rule-pack hash: lock=${lock.rulePackHash} current=${currentHash}`);
+  }
+  return { ok: mismatches.length === 0, mismatches };
+}
+
+// Stable-sort all findings arrays in a scan in place. Stable across runs.
+function sortFn(a, b) {
+  const af = (a.file || ''), bf = (b.file || '');
+  if (af !== bf) return af.localeCompare(bf);
+  const al = a.line || 0, bl = b.line || 0;
+  if (al !== bl) return al - bl;
+  const av = (a.vuln || a.title || ''), bv = (b.vuln || b.title || '');
+  if (av !== bv) return av.localeCompare(bv);
+  return String(a.id || '').localeCompare(String(b.id || ''));
+}
+
+export function makeDeterministic(scan, meta) {
+  for (const k of ['findings', 'secrets', 'logicVulns', 'supplyChain']) {
+    if (Array.isArray(scan[k])) scan[k].sort(sortFn);
+  }
+  if (meta) {
+    meta.scanId = 'deterministic';
+    meta.startedAt = '1970-01-01T00:00:00.000Z';
+    meta.durationMs = 0;
+    meta.deterministic = true;
+  }
+  return { scan, meta };
+}
+
+export function isDeterministic() {
+  return process.env.AGENTIC_SECURITY_DETERMINISTIC === '1';
+}

package/src/posture/drift.js

@@ -0,0 +1,165 @@
+// 0.6.0 Feat-4: Drift report — diff two scans (or two refs) and surface
+// posture changes: new/removed endpoints, new/removed deps, lost or added
+// auth boundaries, severity deltas, data-class deltas.
+//
+// Inputs are two scan JSONs (the result of toJSON or runFullScan). The output
+// is a structured object that the HTML report renders as a "Drift" tab and the
+// PR-comment script renders as a Markdown summary.
+
+function _routeKey(r) { return `${r.method || 'ANY'} ${r.path || '(file)'} @ ${r.file}:${r.line}`; }
+function _depKey(c)   { return `${c.ecosystem}:${c.name}@${c.version}`; }
+function _findingKey(f) { return `${f.kind}:${f.file}:${f.line}:${(f.vuln||'').slice(0,80)}`; }
+
+function _toMap(arr, keyFn) {
+  const m = new Map();
+  for (const x of arr || []) m.set(keyFn(x), x);
+  return m;
+}
+
+function _diffSets(a, b, keyFn) {
+  const ma = _toMap(a, keyFn), mb = _toMap(b, keyFn);
+  const added = [], removed = [], unchanged = [];
+  for (const [k, v] of mb) (ma.has(k) ? unchanged : added).push(v);
+  for (const [k, v] of ma) if (!mb.has(k)) removed.push(v);
+  return { added, removed, unchanged };
+}
+
+// Severity-tier deltas: count by tier on each side, take diff.
+function _severityDelta(a, b) {
+  const counts = (arr) => {
+    const c = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+    for (const f of arr || []) c[f.severity] = (c[f.severity] || 0) + 1;
+    return c;
+  };
+  const ca = counts(a), cb = counts(b);
+  const delta = {};
+  for (const k of Object.keys(ca)) delta[k] = (cb[k] || 0) - (ca[k] || 0);
+  return { from: ca, to: cb, delta };
+}
+
+// Auth boundary deltas: a route is an auth boundary iff hasAuth === true.
+// Lost: was authed, no longer is. Added: now authed, wasn't.
+function _authBoundaryDelta(routesA, routesB) {
+  const k = (r) => `${r.method} ${r.path} @ ${r.file}`;
+  const a = _toMap(routesA, k);
+  const b = _toMap(routesB, k);
+  const lost = [], added = [];
+  for (const [key, ra] of a) {
+    const rb = b.get(key);
+    if (ra.hasAuth && rb && !rb.hasAuth) lost.push(rb);
+    if (!ra.hasAuth && rb && rb.hasAuth) added.push(rb);
+  }
+  return { lost, added };
+}
+
+// Data-class deltas across routes: "now exposed PII", "no longer exposes PHI".
+function _dataClassDelta(routesA, routesB) {
+  const aClasses = new Set();
+  const bClasses = new Set();
+  for (const r of routesA || []) for (const c of r.classifications || []) aClasses.add(c);
+  for (const r of routesB || []) for (const c of r.classifications || []) bClasses.add(c);
+  const newlyExposed = [...bClasses].filter(c => !aClasses.has(c));
+  const noLongerExposed = [...aClasses].filter(c => !bClasses.has(c));
+  return { newlyExposed, noLongerExposed };
+}
+
+export function driftBetween(scanA, scanB) {
+  const routes = _diffSets(scanA.routes || [], scanB.routes || [], _routeKey);
+  const deps = _diffSets(scanA.components || [], scanB.components || [], _depKey);
+  const sca = _diffSets((scanA.supplyChain || []).filter(s => s.type === 'vulnerable_dep'),
+                        (scanB.supplyChain || []).filter(s => s.type === 'vulnerable_dep'),
+                        s => `${s.ecosystem}:${s.name}@${s.version}:${s.osvId || s.advisory || ''}`);
+  // Findings — use kind+file+line+vuln as the stable key.
+  const allFindingsA = [...(scanA.findings || []), ...(scanA.logicVulns || [])];
+  const allFindingsB = [...(scanB.findings || []), ...(scanB.logicVulns || [])];
+  const findings = _diffSets(allFindingsA, allFindingsB, _findingKey);
+  const severity = _severityDelta(allFindingsA, allFindingsB);
+  const authBoundaries = _authBoundaryDelta(scanA.routes || [], scanB.routes || []);
+  const dataClasses = _dataClassDelta(scanA.routes || [], scanB.routes || []);
+
+  const totalChanged =
+    routes.added.length + routes.removed.length +
+    deps.added.length + deps.removed.length +
+    sca.added.length + sca.removed.length +
+    findings.added.length + findings.removed.length +
+    authBoundaries.lost.length + authBoundaries.added.length;
+
+  // Headline tier: critical if ANY auth boundary lost, OR a critical finding added,
+  // OR a vulnerable dep added at high+ severity. High if any finding added or any
+  // auth boundary added without authn improvements. Otherwise informational.
+  let tier = 'info';
+  if (authBoundaries.lost.length > 0) tier = 'critical';
+  else if (findings.added.some(f => f.severity === 'critical')) tier = 'critical';
+  else if (sca.added.some(s => /critical|high/.test(s.severity || ''))) tier = 'high';
+  else if (findings.added.length > 0 || routes.added.some(r => !r.hasAuth)) tier = 'high';
+  else if (deps.added.length > 0 || routes.added.length > 0) tier = 'medium';
+  else if (totalChanged > 0) tier = 'low';
+
+  return {
+    tier,
+    routes, deps, sca, findings,
+    severity, authBoundaries, dataClasses,
+    totalChanged,
+  };
+}
+
+export function driftToMarkdown(drift) {
+  const lines = [];
+  lines.push(`### Posture drift — tier: **${drift.tier}**`);
+  lines.push('');
+  if (drift.tier === 'info' && drift.totalChanged === 0) {
+    lines.push('No posture changes detected between the two scans.');
+    return lines.join('\n');
+  }
+  if (drift.authBoundaries.lost.length) {
+    lines.push(`**Auth boundaries LOST: ${drift.authBoundaries.lost.length}**`);
+    for (const r of drift.authBoundaries.lost) lines.push(`- \`${r.method} ${r.path}\` (\`${r.file}:${r.line}\`)`);
+    lines.push('');
+  }
+  if (drift.authBoundaries.added.length) {
+    lines.push(`**Auth boundaries ADDED: ${drift.authBoundaries.added.length}**`);
+    for (const r of drift.authBoundaries.added) lines.push(`- \`${r.method} ${r.path}\` (\`${r.file}:${r.line}\`)`);
+    lines.push('');
+  }
+  if (drift.routes.added.length) {
+    lines.push(`**New endpoints (${drift.routes.added.length}):**`);
+    for (const r of drift.routes.added.slice(0, 10)) {
+      const auth = r.hasAuth ? '🔒' : '⚠️ unauthenticated';
+      lines.push(`- ${auth} \`${r.method} ${r.path}\` (\`${r.file}:${r.line}\`)`);
+    }
+    if (drift.routes.added.length > 10) lines.push(`- … and ${drift.routes.added.length - 10} more`);
+    lines.push('');
+  }
+  if (drift.routes.removed.length) {
+    lines.push(`**Removed endpoints: ${drift.routes.removed.length}**`);
+    lines.push('');
+  }
+  if (drift.deps.added.length) {
+    lines.push(`**New dependencies (${drift.deps.added.length}):**`);
+    for (const c of drift.deps.added.slice(0, 10)) lines.push(`- \`${c.ecosystem}:${c.name}@${c.version}\``);
+    if (drift.deps.added.length > 10) lines.push(`- … and ${drift.deps.added.length - 10} more`);
+    lines.push('');
+  }
+  if (drift.deps.removed.length) {
+    lines.push(`**Removed dependencies: ${drift.deps.removed.length}**`);
+    lines.push('');
+  }
+  if (drift.sca.added.length) {
+    lines.push(`**New CVEs introduced (${drift.sca.added.length}):**`);
+    for (const s of drift.sca.added.slice(0, 10)) lines.push(`- \`${s.severity}\` ${s.osvId || s.advisory || s.name} (${s.name}@${s.version})`);
+    lines.push('');
+  }
+  if (drift.findings.added.length) {
+    lines.push(`**New findings: ${drift.findings.added.length}** (severity delta: ${Object.entries(drift.severity.delta).filter(([,v])=>v!==0).map(([k,v])=>`${k} ${v>0?'+':''}${v}`).join(', ')||'none'})`);
+    lines.push('');
+  }
+  if (drift.findings.removed.length) {
+    lines.push(`**Findings fixed: ${drift.findings.removed.length}**`);
+    lines.push('');
+  }
+  if (drift.dataClasses.newlyExposed.length) {
+    lines.push(`**Newly exposed data classes: ${drift.dataClasses.newlyExposed.join(', ')}**`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/src/posture/epss.js

@@ -0,0 +1,156 @@
+// EPSS exploit-prediction enrichment.
+//
+// EPSS (Exploit Prediction Scoring System, FIRST.org) gives every CVE a
+// probability of being exploited in the next 30 days plus a percentile rank.
+// Layered on top of CISA KEV, this lets us distinguish "theoretical" CVEs
+// from those attackers are actively weaponizing.
+//
+// Decoration shape (added to each SCA finding with a CVE):
+//   epss: 0.92345
+//   epssPercentile: 0.987
+//   exploitedNow: true   ← percentile >= 0.95
+//
+// Source: https://api.first.org/data/v1/epss?cve=CVE-...,CVE-...
+// Cached on disk: ~/.claude/agentic-security/epss-cache/<sha256>.json
+// 24-hour TTL. Falls back gracefully when offline.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+
+const CACHE_DIR = path.join(os.homedir(), '.claude', 'agentic-security', 'epss-cache');
+const TTL_MS = 24 * 60 * 60 * 1000;
+const EXPLOITED_NOW_THRESHOLD = 0.95; // percentile
+
+function ensureCache() { try { fs.mkdirSync(CACHE_DIR, { recursive: true }); } catch {} }
+function cachePath(cveListKey) {
+  const h = crypto.createHash('sha256').update(cveListKey).digest('hex');
+  return path.join(CACHE_DIR, h + '.json');
+}
+
+function readCache(key) {
+  const fp = cachePath(key);
+  if (!fs.existsSync(fp)) return null;
+  try {
+    const stat = fs.statSync(fp);
+    if (Date.now() - stat.mtimeMs > TTL_MS) return null;
+    return JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch { return null; }
+}
+
+function writeCache(key, data) {
+  ensureCache();
+  try { fs.writeFileSync(cachePath(key), JSON.stringify(data)); } catch {}
+}
+
+// Returns Map<CVE, {epss: number, percentile: number}> for the supplied CVE IDs.
+// Batched in groups of 100 to keep URLs short.
+export async function fetchEPSS(cveIds) {
+  const out = new Map();
+  if (!cveIds || cveIds.length === 0) return out;
+  if (process.env.AGENTIC_SECURITY_OFFLINE === '1') {
+    // Try cache anyway — return whatever we have.
+    const k = [...cveIds].sort().join(',');
+    const c = readCache(k);
+    if (c) for (const [cve, v] of Object.entries(c)) out.set(cve, v);
+    return out;
+  }
+  const unique = [...new Set(cveIds)].filter(c => /^CVE-\d{4}-\d{4,}$/i.test(c));
+  if (!unique.length) return out;
+
+  const cached = readCache([...unique].sort().join(','));
+  if (cached) {
+    for (const [cve, v] of Object.entries(cached)) out.set(cve, v);
+    return out;
+  }
+
+  const fresh = {};
+  for (let i = 0; i < unique.length; i += 100) {
+    const batch = unique.slice(i, i + 100);
+    const url = `https://api.first.org/data/v1/epss?cve=${encodeURIComponent(batch.join(','))}`;
+    try {
+      const res = await fetch(url, { headers: { 'User-Agent': 'agentic-security' } });
+      if (!res.ok) continue;
+      const body = await res.json();
+      for (const row of (body.data || [])) {
+        const epss = parseFloat(row.epss);
+        const percentile = parseFloat(row.percentile);
+        if (Number.isFinite(epss) && Number.isFinite(percentile)) {
+          const v = { epss, percentile };
+          out.set(row.cve, v);
+          fresh[row.cve] = v;
+        }
+      }
+    } catch { /* network error → caller continues without enrichment */ }
+  }
+  if (Object.keys(fresh).length) writeCache([...unique].sort().join(','), fresh);
+  return out;
+}
+
+// Extract CVE IDs from a finding regardless of where they live in the schema.
+function cvesIn(finding) {
+  const found = new Set();
+  if (typeof finding.cve === 'string') found.add(finding.cve.toUpperCase());
+  if (Array.isArray(finding.cves)) for (const c of finding.cves) found.add(String(c).toUpperCase());
+  if (Array.isArray(finding.vulnerabilities)) {
+    for (const v of finding.vulnerabilities) {
+      if (typeof v.id === 'string' && v.id.startsWith('CVE-')) found.add(v.id.toUpperCase());
+      if (Array.isArray(v.aliases)) for (const a of v.aliases) {
+        if (typeof a === 'string' && a.startsWith('CVE-')) found.add(a.toUpperCase());
+      }
+    }
+  }
+  // Fallback: scan title/description for CVE refs.
+  for (const k of ['title', 'description', 'vuln']) {
+    const v = finding[k];
+    if (typeof v === 'string') {
+      const m = v.match(/\bCVE-\d{4}-\d{4,}\b/gi);
+      if (m) for (const c of m) found.add(c.toUpperCase());
+    }
+  }
+  return [...found];
+}
+
+// Decorate every SCA finding (and any other finding with a CVE) in place.
+// Returns { decorated, exploitedNow }.
+export async function enrichWithEPSS(scan) {
+  const buckets = ['supplyChain', 'findings'];
+  const allCves = new Set();
+  for (const b of buckets) {
+    for (const f of (scan[b] || [])) {
+      for (const c of cvesIn(f)) allCves.add(c);
+    }
+  }
+  if (allCves.size === 0) return { decorated: 0, exploitedNow: 0 };
+
+  const epssMap = await fetchEPSS([...allCves]);
+  let decorated = 0, exploitedNow = 0;
+
+  for (const b of buckets) {
+    for (const f of (scan[b] || [])) {
+      const cves = cvesIn(f);
+      let bestEpss = 0, bestPct = 0, bestCve = null;
+      for (const c of cves) {
+        const v = epssMap.get(c);
+        if (v && v.epss > bestEpss) { bestEpss = v.epss; bestPct = v.percentile; bestCve = c; }
+      }
+      if (bestCve) {
+        f.epssScore = bestEpss;
+        f.epssPercentile = bestPct;
+        f.epssCve = bestCve;
+        if (bestPct >= EXPLOITED_NOW_THRESHOLD) {
+          f.exploitedNow = true;
+          exploitedNow++;
+          // Bump severity one notch for actively-exploited CVEs (medium → high → critical).
+          if (f.severity === 'medium') f.severity = 'high';
+          else if (f.severity === 'high') f.severity = 'critical';
+          if (!Array.isArray(f.tags)) f.tags = [];
+          if (!f.tags.includes('exploited-now')) f.tags.push('exploited-now');
+        }
+        decorated++;
+      }
+    }
+  }
+  return { decorated, exploitedNow };
+}