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

package/src/posture/license-graph.js

@@ -0,0 +1,238 @@
+// License-graph supply-chain analyzer — Item #5 of the world-class+3 plan.
+//
+// Extends posture/license-policy.js (per-component allow/deny/review) with:
+//
+//   1. TRANSITIVE COPYLEFT CONTAMINATION
+//      An MIT-licensed direct dep that pulls in a GPL/AGPL transitive
+//      dep. Today's per-component check passes because the direct dep is
+//      MIT — but the GPL is the actual exposure.
+//
+//   2. RELICENSING-RISK LICENSES
+//      BSL, SSPL, Elastic 2.0, Common Clause, Server Side Public License,
+//      Functional Source License, Sustainable Use License, etc.
+//      Permissive at first install — later versions or downstream usage
+//      may breach the additional terms.
+//
+//   3. DISTRIBUTION-MODE-AWARE POLICY
+//      "SaaS" vs "Binary" vs "Library" have radically different obligations.
+//      AGPL is fine for proprietary internal usage but kills SaaS;
+//      GPL is fine for a SaaS web app but kills a published library;
+//      LGPL static-link concerns only apply to native binary distribution.
+//
+//   4. DUAL-LICENSE TRAP DETECTION
+//      Packages declared as `(MIT OR Apache-2.0)` are usually fine, but
+//      `(GPL-2.0 OR Commercial)` are a contractual trap — the open option
+//      auto-converts your code to GPL unless you've signed a commercial
+//      agreement.
+//
+//   5. LICENSE-CHANGE DETECTION
+//      Packages known to have relicensed (Elastic, Redis, Sentry,
+//      HashiCorp Terraform, MongoDB) — flag the boundary version.
+//
+// Default mode: SaaS. Override via
+// .agentic-security/license-policy.yml `distributionMode:`.
+//
+// Opt-out: AGENTIC_SECURITY_NO_LICENSE_GRAPH=1
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ── License taxonomy ───────────────────────────────────────────────────────
+
+const LICENSE_FAMILIES = {
+  permissive:      new Set(['MIT', 'APACHE-2.0', 'BSD-2-CLAUSE', 'BSD-3-CLAUSE', 'BSD-4-CLAUSE', 'ISC', '0BSD', 'CC0-1.0', 'UNLICENSE', 'WTFPL', 'ZLIB', 'PSF-2.0', 'PYTHON-2.0', 'POSTGRESQL', 'OPENSSL', 'X11']),
+  weak_copyleft:   new Set(['LGPL-2.0', 'LGPL-2.1', 'LGPL-3.0', 'LGPL-2.1-OR-LATER', 'LGPL-3.0-OR-LATER', 'MPL-1.1', 'MPL-2.0', 'EPL-1.0', 'EPL-2.0', 'CDDL-1.0', 'CDDL-1.1']),
+  strong_copyleft: new Set(['GPL-2.0', 'GPL-2.0-ONLY', 'GPL-2.0-OR-LATER', 'GPL-3.0', 'GPL-3.0-ONLY', 'GPL-3.0-OR-LATER']),
+  network_copyleft: new Set(['AGPL-1.0', 'AGPL-3.0', 'AGPL-3.0-ONLY', 'AGPL-3.0-OR-LATER']),
+  source_available: new Set(['BSL-1.1', 'SSPL-1.0', 'ELASTIC-2.0', 'ELASTIC-1.0', 'COMMONS-CLAUSE', 'FSL-1.0', 'FSL-1.1', 'CONFLUENT-COMMUNITY', 'BUSL-1.1', 'PARITY-7.0.0', 'POLYFORM-NONCOMMERCIAL', 'POLYFORM-PERIMETER', 'POLYFORM-INTERNAL-USE']),
+  proprietary:     new Set(['UNLICENSED', 'NOLICENSE', 'PROPRIETARY', 'COMMERCIAL']),
+};
+
+const KNOWN_RELICENSED = [
+  // pkg-name regex → { from, to, atVersion, ecosystem }
+  { pkg: /^elasticsearch$/i,  from: 'Apache-2.0',  to: 'Elastic-2.0 / SSPL', atVersion: '>=7.11.0', ecosystem: 'java/npm' },
+  { pkg: /^@elastic\/elasticsearch$/i, from: 'Apache-2.0', to: 'Elastic-2.0 / SSPL', atVersion: '>=8.0.0', ecosystem: 'npm' },
+  { pkg: /^redis$/i,          from: 'BSD-3-Clause', to: 'RSALv2 / SSPL',     atVersion: '>=7.4',      ecosystem: 'multi' },
+  { pkg: /^@sentry\/.*$/i,    from: 'BSD-3-Clause', to: 'FSL-1.1',           atVersion: '>=8.0.0',    ecosystem: 'npm' },
+  { pkg: /^terraform.*$/i,    from: 'MPL-2.0',      to: 'BSL-1.1',           atVersion: '>=1.6.0',    ecosystem: 'multi' },
+  { pkg: /^mongodb$/i,        from: 'AGPL-3.0',     to: 'SSPL-1.0',          atVersion: '>=4.4',      ecosystem: 'multi' },
+  { pkg: /^vault$/i,          from: 'MPL-2.0',      to: 'BSL-1.1',           atVersion: '>=1.15.0',   ecosystem: 'go' },
+  { pkg: /^consul$/i,         from: 'MPL-2.0',      to: 'BSL-1.1',           atVersion: '>=1.17.0',   ecosystem: 'go' },
+  { pkg: /^cockroachdb?$/i,   from: 'Apache-2.0',   to: 'CCL (modified)',    atVersion: '>=19.2',     ecosystem: 'go' },
+];
+
+function _normLicense(s) { return String(s || '').toUpperCase().replace(/[()]/g, '').trim(); }
+
+function _classify(license) {
+  if (!license) return 'unknown';
+  const l = _normLicense(license);
+  // Compound: pick worst family.
+  if (/\s(?:AND|OR|WITH)\s/i.test(l)) {
+    const parts = l.split(/\s+(?:AND|OR|WITH)\s+/i).map(p => p.trim()).filter(Boolean);
+    const families = parts.map(_classify);
+    // Worst → best: source_available > network_copyleft > strong > weak > permissive > unknown.
+    for (const f of ['source_available', 'network_copyleft', 'strong_copyleft', 'weak_copyleft', 'permissive']) {
+      if (families.includes(f)) return f;
+    }
+    return 'unknown';
+  }
+  for (const [fam, set] of Object.entries(LICENSE_FAMILIES)) {
+    if (set.has(l)) return fam;
+  }
+  return 'unknown';
+}
+
+// ── Distribution-mode policy ───────────────────────────────────────────────
+
+const DEFAULT_DIST_MODE = 'saas';
+
+const DIST_MODE_MATRIX = {
+  saas: {
+    permissive:       { verdict: 'allow', why: 'Compatible with SaaS distribution.' },
+    weak_copyleft:    { verdict: 'allow', why: 'Weak-copyleft (LGPL/MPL/CDDL/EPL) — SaaS distribution does not trigger reciprocity for unmodified usage.' },
+    strong_copyleft:  { verdict: 'review', why: 'GPL/CGPL is compatible with SaaS (no distribution of binary) but propagates if you ever publish the source or a derived binary. Confirm internal-only.' },
+    network_copyleft: { verdict: 'deny', why: 'AGPL "network use as distribution" — SaaS deployment triggers source-disclosure obligations.' },
+    source_available: { verdict: 'deny', why: 'Source-available licenses (BSL/SSPL/Elastic/CommonsClause) restrict competitive SaaS offerings.' },
+    proprietary:      { verdict: 'deny', why: 'Component has no license / declares proprietary — cannot redistribute.' },
+    unknown:          { verdict: 'review', why: 'Unknown license — verify via upstream repo.' },
+  },
+  binary: {
+    permissive:       { verdict: 'allow', why: 'Compatible with binary distribution.' },
+    weak_copyleft:    { verdict: 'review', why: 'LGPL has static-linking obligations; MPL has file-level reciprocity. Confirm linkage model.' },
+    strong_copyleft:  { verdict: 'deny', why: 'GPL copyleft propagates to the entire distributed binary.' },
+    network_copyleft: { verdict: 'deny', why: 'AGPL is even more restrictive than GPL for distribution.' },
+    source_available: { verdict: 'deny', why: 'Source-available licenses (BSL/SSPL/Elastic/CommonsClause) impose use restrictions that often conflict with binary distribution to customers.' },
+    proprietary:      { verdict: 'deny', why: 'Component has no license / declares proprietary — cannot bundle.' },
+    unknown:          { verdict: 'review', why: 'Unknown license — verify via upstream repo.' },
+  },
+  library: {
+    permissive:       { verdict: 'allow', why: 'Compatible with library publishing.' },
+    weak_copyleft:    { verdict: 'review', why: 'LGPL/MPL transitive deps complicate downstream users of YOUR library.' },
+    strong_copyleft:  { verdict: 'deny', why: 'GPL locks all downstream users of your library into GPL.' },
+    network_copyleft: { verdict: 'deny', why: 'AGPL forces downstream users into AGPL.' },
+    source_available: { verdict: 'deny', why: 'Source-available licenses block downstream commercial use of your library.' },
+    proprietary:      { verdict: 'deny', why: 'Component has no license — cannot redistribute via your library.' },
+    unknown:          { verdict: 'review', why: 'Unknown license — verify via upstream repo.' },
+  },
+};
+
+// ── Transitive walker ──────────────────────────────────────────────────────
+
+function _depPathLabel(c) {
+  return `${c.ecosystem || '?'}:${c.name}@${c.version || '?'}`;
+}
+
+/**
+ * Build the dep graph + collect transitive contamination paths.
+ *
+ * components — list of component objects (already produced by the engine).
+ *              expects: { ecosystem, name, version, license, transitive (boolean),
+ *              importedBy: string[] (optional) }.
+ */
+export function analyzeLicenseGraph(components, options) {
+  const opts = options || {};
+  const mode = (opts.distributionMode || DEFAULT_DIST_MODE).toLowerCase();
+  const matrix = DIST_MODE_MATRIX[mode] || DIST_MODE_MATRIX[DEFAULT_DIST_MODE];
+  if (!Array.isArray(components) || components.length === 0) {
+    return { findings: [], summary: { total: 0, deny: 0, review: 0, allow: 0, unknown: 0 }, distributionMode: mode };
+  }
+  const byKey = new Map();
+  for (const c of components) byKey.set(_depPathLabel(c), c);
+  const findings = [];
+  const summary = { total: components.length, deny: 0, review: 0, allow: 0, unknown: 0 };
+
+  for (const c of components) {
+    const family = _classify(c.license);
+    const verdict = matrix[family] || matrix.unknown;
+    summary[verdict.verdict] = (summary[verdict.verdict] || 0) + 1;
+    if (verdict.verdict === 'allow') continue;
+
+    const isTransitive = !!c.transitive;
+    let path = [_depPathLabel(c)];
+    if (isTransitive && Array.isArray(c.importedBy) && c.importedBy.length) {
+      // Walk up the graph (one hop in v1 — sufficient for "direct dep that
+      // pulled in this offender").
+      path = [c.importedBy[0], _depPathLabel(c)];
+    }
+
+    findings.push({
+      id: `license-graph:${_depPathLabel(c)}:${family}:${verdict.verdict}`,
+      kind: 'license', family: 'license-graph',
+      severity: verdict.verdict === 'deny' ? 'high' : 'low',
+      file: c.filePath || 'package.json', line: 0,
+      vuln: `${verdict.verdict === 'deny' ? 'License-incompatible' : 'License-review-needed'}: ${c.name}@${c.version || '?'} (${c.license || 'no license'}) under ${mode} distribution mode`,
+      description: verdict.why + (isTransitive ? ` Transitive dep pulled in via ${path.slice(0, -1).join(' → ')}.` : ''),
+      remediation: verdict.verdict === 'deny'
+        ? `Replace ${c.name}@${c.version || '?'} with a permissively-licensed alternative, OR switch to a different distribution mode (set distributionMode: in .agentic-security/license-policy.yml), OR negotiate a commercial license with the upstream.`
+        : `Have legal review confirm ${c.license} compatibility with ${mode} distribution. Once approved, add ${c.name} to the policy allow-list.`,
+      package: c.name,
+      version: c.version,
+      ecosystem: c.ecosystem,
+      license: c.license || null,
+      licenseFamily: family,
+      distributionMode: mode,
+      isTransitive,
+      depPath: path,
+    });
+  }
+
+  // ── Dual-license trap detection ─────────────────────────────────────────
+  for (const c of components) {
+    if (!c.license) continue;
+    const lic = _normLicense(c.license);
+    if (!/\bOR\b/i.test(lic)) continue;
+    const atoms = lic.split(/\s+OR\s+/i).map(s => s.trim());
+    const hasCommercial = atoms.some(a => /COMMERCIAL|PROPRIETARY|ENTERPRISE/.test(a));
+    const hasStrongCopyleft = atoms.some(a => LICENSE_FAMILIES.strong_copyleft.has(a) || LICENSE_FAMILIES.network_copyleft.has(a));
+    if (hasCommercial && hasStrongCopyleft) {
+      findings.push({
+        id: `license-graph:dual-license-trap:${_depPathLabel(c)}`,
+        kind: 'license', family: 'license-dual-trap',
+        severity: 'high',
+        file: c.filePath || 'package.json', line: 0,
+        vuln: `Dual-license trap: ${c.name}@${c.version} offers ${c.license} — the open option is copyleft, the alternative requires a commercial agreement`,
+        description: 'Dual GPL-OR-Commercial licensing means: if you have not signed a commercial agreement with the upstream, your usage falls under GPL/AGPL and propagates to your codebase. Common pattern with Qt LGPL/Commercial, MongoDB AGPL/Commercial pre-SSPL, GraalVM.',
+        remediation: 'Verify with legal whether a commercial agreement is in place. If not, you are bound by the copyleft option — propagate that to your distribution mode policy.',
+        package: c.name, version: c.version, license: c.license,
+      });
+      summary.deny = (summary.deny || 0) + 1;
+    }
+  }
+
+  // ── Known relicensed packages ───────────────────────────────────────────
+  for (const c of components) {
+    for (const r of KNOWN_RELICENSED) {
+      if (!r.pkg.test(c.name)) continue;
+      findings.push({
+        id: `license-graph:relicensed:${_depPathLabel(c)}`,
+        kind: 'license', family: 'license-relicense',
+        severity: 'medium',
+        file: c.filePath || 'package.json', line: 0,
+        vuln: `${c.name}@${c.version}: upstream relicensed from ${r.from} → ${r.to} (boundary ${r.atVersion})`,
+        description: `Upstream relicensing event for ${c.name}. Older versions were ${r.from}; ${r.atVersion} and later are ${r.to}. Verify which side of the boundary your version is on, and update your policy.`,
+        remediation: `Pin to a pre-relicense version if the new terms are unacceptable, OR adopt a fork (e.g. OpenSearch for Elasticsearch, Valkey for Redis, OpenTofu for Terraform).`,
+        package: c.name, version: c.version, license: c.license, relicenseInfo: r,
+      });
+    }
+  }
+
+  return { findings, summary, distributionMode: mode };
+}
+
+// ── Policy file loader (extends posture/license-policy.js shape) ───────────
+
+export function loadLicenseGraphPolicy(scanRoot) {
+  if (!scanRoot) return { distributionMode: DEFAULT_DIST_MODE };
+  const fp = path.join(scanRoot, '.agentic-security', 'license-policy.yml');
+  if (!fs.existsSync(fp)) return { distributionMode: DEFAULT_DIST_MODE };
+  try {
+    const raw = fs.readFileSync(fp, 'utf8');
+    const m = /\bdistributionMode\s*:\s*['"]?(saas|binary|library)['"]?/i.exec(raw);
+    return { distributionMode: m ? m[1].toLowerCase() : DEFAULT_DIST_MODE };
+  } catch { return { distributionMode: DEFAULT_DIST_MODE }; }
+}
+
+export const _internals = {
+  LICENSE_FAMILIES, DIST_MODE_MATRIX, KNOWN_RELICENSED,
+  _classify, _normLicense,
+};

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

package/src/posture/realtime-cve-monitor.js

@@ -0,0 +1,214 @@
+// Real-time emergent vulnerability monitor — Recommendation #8 of the
+// world-class+2 plan.
+//
+// Polls / streams the OSV.dev feed (and optionally GHSA + vendor
+// advisories) and within minutes of a new CVE matching the customer's
+// SBOM, delivers a push notification via Slack / Discord / generic
+// webhook.
+//
+// Design:
+//   1. Pre-index the project's SBOM by (ecosystem, package) so a new
+//      CVE checks against the index in O(1)
+//   2. Poll OSV's published-vulns endpoint every POLL_INTERVAL_MS
+//      (default 60s)
+//   3. On match: emit a structured alert + write to a state file so
+//      duplicate alerts aren't sent
+//   4. Push delivery via existing webhook utilities; configurable
+//      destinations: AGENTIC_SECURITY_ALERT_WEBHOOK, _SLACK, _DISCORD
+//
+// Out of scope: persistent daemon. This module exposes a `cycle()`
+// function the caller invokes from a cron-shape loop (the existing
+// commands/cve-alerts.md skill is the user-facing wrapper).
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { statePath, safeWriteState } from './state-dir.js';
+
+const STATE_FILE = 'cve-monitor-state.json';
+const DEFAULT_POLL_MS = 60_000;
+const DEFAULT_WINDOW_HOURS = 24;
+const SLA_MINUTES = 5;
+
+const OSV_FEED_URL = 'https://api.osv.dev/v1/vulns/recent';
+
+function _statePath(scanRoot) { return statePath(scanRoot, STATE_FILE); }
+
+function _loadState(scanRoot) {
+  const fp = _statePath(scanRoot);
+  if (!fs.existsSync(fp)) return { alertedIds: [], lastPolledAt: null };
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
+  catch { return { alertedIds: [], lastPolledAt: null }; }
+}
+function _saveState(scanRoot, state) {
+  safeWriteState(_statePath(scanRoot), JSON.stringify(state, null, 2));
+}
+
+/**
+ * Build a name→component index from the project's most recent SBOM.
+ * Accepts the SBOM as parsed from the engine output's `components`
+ * array (each entry: { ecosystem, name, version, … }).
+ */
+export function indexSbom(components) {
+  const index = new Map();   // key: `${ecosystem}:${name}` → component
+  for (const c of components || []) {
+    if (!c || !c.ecosystem || !c.name) continue;
+    const key = `${String(c.ecosystem).toLowerCase()}:${String(c.name).toLowerCase()}`;
+    if (!index.has(key)) index.set(key, []);
+    index.get(key).push(c);
+  }
+  return index;
+}
+
+/**
+ * Pull the recent-published-vulnerabilities feed from OSV. Returns an
+ * array of OSV vulnerability records.
+ */
+export async function pollOsv(opts = {}) {
+  if (process.env.AGENTIC_SECURITY_OFFLINE === '1') return [];
+  const url = opts.feedUrl || OSV_FEED_URL;
+  const since = opts.sinceIso || new Date(Date.now() - DEFAULT_WINDOW_HOURS * 3600_000).toISOString();
+  try {
+    const u = new URL(url);
+    u.searchParams.set('time', since);
+    const res = await fetch(u.toString(), {
+      headers: { 'User-Agent': 'agentic-security/0.1' },
+    });
+    if (!res.ok) return [];
+    const body = await res.json();
+    return Array.isArray(body.vulns) ? body.vulns : (Array.isArray(body) ? body : []);
+  } catch { return []; }
+}
+
+/**
+ * Match a single OSV record against the SBOM index. Returns an array of
+ * (component, vuln) tuples that match.
+ */
+export function matchOsvToSbom(vuln, sbomIndex) {
+  const out = [];
+  for (const aff of (vuln.affected || [])) {
+    const eco = (aff.package?.ecosystem || '').toLowerCase();
+    const name = (aff.package?.name || '').toLowerCase();
+    if (!eco || !name) continue;
+    const key = `${_normalizeEco(eco)}:${name}`;
+    const matches = sbomIndex.get(key);
+    if (!matches) continue;
+    for (const comp of matches) {
+      // Best-effort version-range check — many advisories don't carry
+      // semver ranges in OSV affected objects; we conservatively
+      // include all matches and let the customer triage.
+      out.push({ component: comp, vuln });
+    }
+  }
+  return out;
+}
+
+function _normalizeEco(eco) {
+  const e = eco.toLowerCase();
+  if (e === 'npm' || e === 'node') return 'npm';
+  if (e === 'pypi' || e === 'pip' || e === 'python') return 'pypi';
+  if (e === 'maven') return 'maven';
+  if (e === 'gem' || e === 'rubygems') return 'rubygems';
+  if (e === 'cargo' || e === 'crates.io') return 'cargo';
+  if (e === 'go' || e === 'golang') return 'golang';
+  if (e === 'packagist' || e === 'composer') return 'packagist';
+  if (e === 'pub' || e === 'dart') return 'pub';
+  return e;
+}
+
+/**
+ * Compose the alert payload for delivery.
+ */
+function _composeAlert(matchTuple, ts = new Date().toISOString()) {
+  const { component, vuln } = matchTuple;
+  return {
+    schema: 'agentic-security/cve-alert/v1',
+    ts,
+    cve: (vuln.aliases || []).find(a => /^CVE-/.test(a)) || null,
+    osvId: vuln.id,
+    summary: vuln.summary || vuln.details?.slice(0, 200) || '(no summary)',
+    component: {
+      ecosystem: component.ecosystem,
+      name: component.name,
+      version: component.version,
+    },
+    references: (vuln.references || []).slice(0, 4).map(r => r.url),
+    severity: _inferSeverity(vuln),
+    sla: { promised: `${SLA_MINUTES}m`, ts },
+  };
+}
+
+function _inferSeverity(vuln) {
+  if (Array.isArray(vuln.severity) && vuln.severity.length) {
+    const cvss = vuln.severity.find(s => /^CVSS_V/.test(s.type || ''));
+    if (cvss && cvss.score) return cvss.score;
+  }
+  if (vuln.database_specific?.severity) return String(vuln.database_specific.severity);
+  return 'unknown';
+}
+
+/**
+ * Deliver an alert via every configured channel. Webhook URLs come from
+ * env: AGENTIC_SECURITY_ALERT_WEBHOOK / _SLACK_WEBHOOK / _DISCORD_WEBHOOK.
+ */
+export async function deliverAlert(alert) {
+  const sinks = {
+    generic: process.env.AGENTIC_SECURITY_ALERT_WEBHOOK,
+    slack:   process.env.AGENTIC_SECURITY_SLACK_WEBHOOK,
+    discord: process.env.AGENTIC_SECURITY_DISCORD_WEBHOOK,
+  };
+  const results = {};
+  for (const [name, url] of Object.entries(sinks)) {
+    if (!url) continue;
+    try {
+      const body = name === 'slack'
+        ? { text: `*New CVE affecting your stack*\n• ${alert.cve || alert.osvId} — ${alert.severity}\n• Package: \`${alert.component.ecosystem}:${alert.component.name}@${alert.component.version}\`\n• ${alert.summary}` }
+        : name === 'discord'
+          ? { content: `**New CVE affecting your stack**\n• ${alert.cve || alert.osvId} — ${alert.severity}\n• \`${alert.component.ecosystem}:${alert.component.name}@${alert.component.version}\`\n• ${alert.summary}` }
+          : alert;
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'User-Agent': 'agentic-security/0.1' },
+        body: JSON.stringify(body),
+      });
+      results[name] = { ok: res.ok, status: res.status };
+    } catch (e) {
+      results[name] = { ok: false, error: String(e && e.message || e) };
+    }
+  }
+  return results;
+}
+
+/**
+ * One polling cycle. Caller invokes from a daemon / cron / loop.
+ * - Fetches recent OSV records
+ * - Matches against the SBOM index
+ * - Deduplicates against prior alerts (by OSV id)
+ * - Delivers alerts
+ * - Persists state
+ */
+export async function cycle(scanRoot, sbomComponents, opts = {}) {
+  const state = _loadState(scanRoot);
+  const seen = new Set(state.alertedIds || []);
+  const index = indexSbom(sbomComponents);
+  const recent = await pollOsv({ sinceIso: state.lastPolledAt, ...opts });
+  const matches = [];
+  for (const v of recent) {
+    if (seen.has(v.id)) continue;
+    const m = matchOsvToSbom(v, index);
+    if (m.length === 0) continue;
+    matches.push(...m);
+  }
+  const alerts = matches.map(m => _composeAlert(m));
+  const deliveries = [];
+  for (const alert of alerts) {
+    const d = await deliverAlert(alert);
+    deliveries.push({ alert, delivery: d });
+    seen.add(alert.osvId);
+  }
+  state.alertedIds = [...seen];
+  state.lastPolledAt = new Date().toISOString();
+  _saveState(scanRoot, state);
+  return { recentCount: recent.length, matches: matches.length, alerts: alerts.length, deliveries };
+}
+
+export const _internals = { _normalizeEco, _composeAlert, _inferSeverity, OSV_FEED_URL, DEFAULT_POLL_MS, SLA_MINUTES };