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

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

package/src/posture/risk-dollars.js

@@ -0,0 +1,158 @@
+// Risk-in-dollars — expected value of exploitation per finding.
+//
+// Combines three signals into an EV estimate:
+//
+//   P(exploited)   from EPSS score on the finding's CVE if present,
+//                  else from family-level base rate
+//   Impact($)      from crown-jewel mapping (data class) and industry
+//                  breach-cost averages
+//   Discount       reachability tier (route-reachable > function-reachable
+//                  > unknown > unreachable)
+//
+// EV per finding = P × Impact × Discount × ConfidenceFloor
+//
+// Industry breach-cost figures used here are sourced from publicly
+// reported aggregates (Ponemon Cost of a Data Breach Report — IBM/Verizon
+// methodology is widely cited but the figures are reported in the public
+// summary; we use rounded estimates as defaults that users can override
+// via .agentic-security/risk-config.yml).
+//
+// Disclaimer: this is an order-of-magnitude estimate for prioritization.
+// It is NOT an actuarial or insurance assessment.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const STATE = '.agentic-security';
+
+// Base rates per family (annual probability of at-least-one exploit given
+// an exposed instance). Rough industry estimates; tune via config.
+const FAMILY_BASE_PROB = {
+  'sqli': 0.18, 'sql-injection': 0.18,
+  'xss': 0.12, 'mutation-xss': 0.10,
+  'command-injection': 0.16,
+  'code-injection': 0.20,
+  'deserialization': 0.15,
+  'auth-missing': 0.25,
+  'authz': 0.18, 'idor': 0.15,
+  'csrf': 0.07,
+  'ssrf': 0.10, 'ssrf-cloud-metadata': 0.22,
+  'xxe': 0.08,
+  'open-redirect': 0.05,
+  'path-traversal': 0.10,
+  'crypto-weak-cipher': 0.04, 'crypto-weak-hash': 0.03,
+  'crypto-tls-no-verify': 0.10, 'crypto-tls-version': 0.05,
+  'crypto-jwt-none': 0.20, 'crypto-jwt-key-confusion': 0.18,
+  'hardcoded-secret': 0.30,
+  'vulnerable-dependency': 0.08,
+  'dependency-confusion': 0.06,
+  'iam-overpermissive': 0.10,
+  'k8s-rbac-cluster-admin': 0.12,
+  'k8s-pod-security-privileged': 0.10,
+  'prompt-injection': 0.20,
+  'agent-tool-exec': 0.25,
+  'reentrancy': 0.30,
+  'signature-replay': 0.15,
+  'eth-sign-used': 0.30,
+  'unlimited-approval': 0.18,
+};
+
+// Default impact (USD) per crown-jewel / data-class tier.
+const IMPACT_USD = {
+  'PII':           250_000,
+  'PHI':           400_000,
+  'PCI':           500_000,
+  'Confidential':  150_000,
+  'crown-jewel':   300_000,
+  'default':        50_000,
+};
+
+const REACH_DISCOUNT = {
+  'reachable-public':                1.0,
+  'public-unauthed':                 1.0,
+  'route-reachable':                 0.9,
+  'route-reachable-via-function':    0.7,
+  'function-reachable':              0.5,
+  'unknown':                         0.3,
+  'unreachable':                     0.05,
+  'function-reachable-but-not-route':0.4,
+};
+
+function _loadConfig(scanRoot) {
+  const fp = path.join(scanRoot, STATE, 'risk-config.yml');
+  if (!fs.existsSync(fp)) return null;
+  try {
+    const body = fs.readFileSync(fp, 'utf8');
+    // Tiny YAML — look for impactUSD / familyBaseProb overrides
+    const cfg = {};
+    const impactMatch = body.match(/^impactUSD\s*:\s*\n((?:\s+\w+\s*:\s*\d+\s*\n?)+)/m);
+    if (impactMatch) {
+      cfg.impactUSD = {};
+      for (const m of impactMatch[1].matchAll(/(\w+)\s*:\s*(\d+)/g)) cfg.impactUSD[m[1]] = parseInt(m[2], 10);
+    }
+    return cfg;
+  } catch { return null; }
+}
+
+function _baseProb(family) {
+  if (!family) return 0.05;
+  return FAMILY_BASE_PROB[family] || FAMILY_BASE_PROB[String(family).toLowerCase()] || 0.05;
+}
+
+function _impactFor(finding, cfg) {
+  const table = cfg && cfg.impactUSD ? { ...IMPACT_USD, ...cfg.impactUSD } : IMPACT_USD;
+  const dc = Array.isArray(finding.dataClasses) ? finding.dataClasses : [];
+  if (dc.includes('PHI')) return table.PHI;
+  if (dc.includes('PCI')) return table.PCI;
+  if (dc.includes('PII')) return table.PII;
+  if (dc.includes('Confidential')) return table.Confidential;
+  if (finding.threatModel?.crownJewel) return table['crown-jewel'];
+  return table.default;
+}
+
+function _reachDiscount(finding) {
+  const tier = finding.reachabilityTier || finding.routeReachable && 'route-reachable' || 'unknown';
+  return REACH_DISCOUNT[tier] || 0.3;
+}
+
+function _epssProb(finding) {
+  if (typeof finding.epssScore === 'number') return finding.epssScore;
+  if (typeof finding.epss === 'number') return finding.epss;
+  return null;
+}
+
+/**
+ * Compute EV per finding. Mutates the finding in place: adds
+ * .riskDollars = { ev, prob, impact, discount }.
+ */
+export function annotateRiskDollars(scanRoot, findings) {
+  if (!Array.isArray(findings) || findings.length === 0) return { total: 0, sumEv: 0 };
+  const cfg = _loadConfig(scanRoot);
+  let sumEv = 0;
+  let critEv = 0, highEv = 0;
+  for (const f of findings) {
+    const epss = _epssProb(f);
+    const prob = epss != null ? epss : _baseProb(f.family);
+    const impact = _impactFor(f, cfg);
+    const discount = _reachDiscount(f);
+    const confidenceFloor = Math.max(0.4, f.confidence || 0.8);
+    const ev = Math.round(prob * impact * discount * confidenceFloor);
+    f.riskDollars = { ev, prob: Number(prob.toFixed(3)), impact, discount, confidenceFloor: Number(confidenceFloor.toFixed(2)) };
+    sumEv += ev;
+    if (f.severity === 'critical') critEv += ev;
+    else if (f.severity === 'high') highEv += ev;
+  }
+  return { total: findings.length, sumEv, critEv, highEv };
+}
+
+/**
+ * Format a USD figure for display.
+ */
+export function fmtUsd(n) {
+  if (typeof n !== 'number' || !isFinite(n)) return '$?';
+  if (n >= 1_000_000) return `$${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `$${(n / 1_000).toFixed(0)}k`;
+  return `$${n}`;
+}
+
+export const _internals = { FAMILY_BASE_PROB, IMPACT_USD, REACH_DISCOUNT, _baseProb, _impactFor, _reachDiscount };

package/src/posture/runtime-correlation.js

@@ -0,0 +1,174 @@
+// eBPF runtime instrumentation correlation — Recommendation #5 of the
+// world-class roadmap.
+//
+// The hardest false-positive class is "this code path is technically
+// reachable but is DEAD in production." Static analysis can't distinguish
+// dead code from reachable code; runtime observation can. This module
+// consumes an eBPF trace dataset (produced by an out-of-band collector
+// running in the customer's prod environment) and demotes findings
+// whose call-graph paths were unobserved.
+//
+// Trace format (JSONL, one record per observation):
+//
+//   { "ts": "2026-05-28T...", "host": "prod-host-1",
+//     "kind": "function-call", "qid": "com.acme.UserController.getUser",
+//     "fileRel": "src/main/java/com/acme/UserController.java", "line": 42,
+//     "count": 1234, "lastSeen": "2026-05-28T..." }
+//
+// Common record kinds:
+//   - "function-call":   QID was invoked at least once in the trace window
+//   - "route-hit":       HTTP route received traffic
+//   - "syscall":         filesystem / network / process syscall fired
+//   - "file-touch":      file was read / written
+//
+// The trace file lives at one of:
+//   .agentic-security/runtime-trace.jsonl (per-project, committed)
+//   $AGENTIC_SECURITY_RUNTIME_TRACE_PATH    (override)
+//
+// Output: every finding gets a `runtimeObserved: true|false|unknown` field.
+//   true   — at least one node on the finding's call-graph path appears in trace
+//   false  — none of the nodes appear (finding's path is dead in observed window)
+//   unknown — no trace data available
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+import { createReadStream } from 'node:fs';
+
+const DEFAULT_TRACE_NAMES = ['runtime-trace.jsonl', 'runtime.jsonl', 'ebpf-trace.jsonl'];
+const DEFAULT_OBSERVATION_WINDOW_DAYS = 30;
+
+export async function loadTrace(scanRoot, opts = {}) {
+  const explicit = opts.tracePath || process.env.AGENTIC_SECURITY_RUNTIME_TRACE_PATH;
+  const candidates = explicit ? [explicit] : DEFAULT_TRACE_NAMES.map(n => path.join(scanRoot, '.agentic-security', n));
+  let chosen = null;
+  for (const c of candidates) {
+    if (fs.existsSync(c)) { chosen = c; break; }
+  }
+  if (!chosen) return null;
+  const trace = {
+    path: chosen,
+    qidsObserved: new Set(),
+    routesObserved: new Set(),
+    filesObserved: new Set(),
+    fileLinesObserved: new Map(), // file → Set<line>
+    syscallsObserved: new Set(),
+    recordCount: 0,
+  };
+  const window = (opts.windowDays || DEFAULT_OBSERVATION_WINDOW_DAYS) * 86400_000;
+  const now = Date.now();
+  const stream = createReadStream(chosen, { encoding: 'utf8' });
+  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    let r;
+    try { r = JSON.parse(line); } catch { continue; }
+    if (r.ts) {
+      const tsMs = Date.parse(r.ts);
+      if (Number.isFinite(tsMs) && now - tsMs > window) continue;
+    }
+    trace.recordCount++;
+    switch (r.kind) {
+      case 'function-call':
+        if (r.qid) trace.qidsObserved.add(r.qid);
+        if (r.fileRel && typeof r.line === 'number') {
+          let set = trace.fileLinesObserved.get(r.fileRel);
+          if (!set) { set = new Set(); trace.fileLinesObserved.set(r.fileRel, set); }
+          set.add(r.line);
+        }
+        if (r.fileRel) trace.filesObserved.add(r.fileRel);
+        break;
+      case 'route-hit':
+        if (r.route) trace.routesObserved.add(r.route);
+        break;
+      case 'syscall':
+        if (r.name) trace.syscallsObserved.add(r.name);
+        break;
+      case 'file-touch':
+        if (r.fileRel) trace.filesObserved.add(r.fileRel);
+        break;
+    }
+  }
+  return trace;
+}
+
+/**
+ * Test whether a finding's call-graph path was observed in trace.
+ * Checks:
+ *   1. The finding's file appears in filesObserved (necessary condition)
+ *   2. AT LEAST ONE line on the finding's chain (source, sink, intermediate
+ *      nodes) was observed in that file
+ *   3. The finding's containing function's qid appears in qidsObserved
+ */
+export function findingObservedInRuntime(finding, trace) {
+  if (!trace) return 'unknown';
+  // qid match (most specific)
+  if (finding.scope && trace.qidsObserved.has(finding.scope)) return true;
+  if (finding.functionQid && trace.qidsObserved.has(finding.functionQid)) return true;
+  // file + any-line on the chain match
+  const file = finding.file || (finding.sink && finding.sink.file);
+  if (file && trace.filesObserved.has(file)) {
+    const linesObserved = trace.fileLinesObserved.get(file);
+    if (linesObserved) {
+      const chainLines = [
+        finding.line,
+        ...(finding.chain || []).map(s => s.line),
+        ...(finding.taintPath || []).map(s => s.line),
+      ].filter(n => typeof n === 'number');
+      for (const ln of chainLines) {
+        // Allow ±2 line tolerance for compiler reordering / minor inlining.
+        for (let off = -2; off <= 2; off++) {
+          if (linesObserved.has(ln + off)) return true;
+        }
+      }
+    }
+    // File appears but no line match — partial evidence. Don't claim
+    // observed; don't claim dead.
+    return 'unknown';
+  }
+  // route match — every finding inside a route handler whose route was hit.
+  if (finding._inRoute && finding._inRoute.path && trace.routesObserved.has(finding._inRoute.path)) return true;
+  if (finding.routeRooted && finding._inRoute && trace.routesObserved.size > 0) {
+    for (const r of trace.routesObserved) {
+      if (finding._inRoute.path && r.includes(finding._inRoute.path)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Annotate all findings with runtimeObserved + demote unobserved findings.
+ * Demotion: critical → high, high → medium, medium → low.
+ *
+ * Findings classified as unknown are left alone (no demotion). This is
+ * the principled position — absence of observation in a partial trace
+ * is not evidence of dead code.
+ */
+export async function annotateRuntimeCorrelation(scanRoot, findings, opts = {}) {
+  if (!Array.isArray(findings)) return { observed: 0, dead: 0, unknown: 0 };
+  const trace = await loadTrace(scanRoot, opts);
+  if (!trace) {
+    for (const f of findings) f.runtimeObserved = 'unknown';
+    return { observed: 0, dead: 0, unknown: findings.length, trace: null };
+  }
+  let observed = 0, dead = 0, unknown = 0;
+  const demoteLadder = { critical: 'high', high: 'medium', medium: 'low', low: 'info' };
+  for (const f of findings) {
+    const v = findingObservedInRuntime(f, trace);
+    f.runtimeObserved = v;
+    if (v === true) observed++;
+    else if (v === false) {
+      dead++;
+      // Demote one tier — the finding is real but unobserved in 30 days
+      // of production traffic, so it's not P0.
+      const next = demoteLadder[f.severity];
+      if (next) {
+        f._runtimeDemoted = f.severity;
+        f.severity = next;
+      }
+    } else unknown++;
+  }
+  return { observed, dead, unknown, trace: { recordCount: trace.recordCount, path: trace.path } };
+}
+
+export const _internals = { DEFAULT_TRACE_NAMES, DEFAULT_OBSERVATION_WINDOW_DAYS };