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

package/src/posture/compliance-policy.js

@@ -0,0 +1,218 @@
+// Compliance-as-code DSL — Recommendation #9 of the world-class+2 plan.
+//
+// Customers declare their compliance policy in
+// .agentic-security/compliance.policy.yml. The scanner reads the policy,
+// runs verification (each rule is a deterministic check against scanner
+// findings + config files + state) and emits a structured JSON-LD
+// evidence file consumable by Vanta / Drata / SecureFrame / auditors.
+//
+// DSL shape:
+//
+//   framework: "SOC2 Type II"
+//   controls:
+//     CC6.1:
+//       title: "Logical access controls"
+//       requires:
+//         - finding-family: "auth-missing"
+//           must-be: zero
+//         - file-exists: ".github/dependabot.yml"
+//         - documented: ".agentic-security/auth-policy.md"
+//       evidence:
+//         - "Scanner finds 0 auth-missing findings on the current release"
+//         - "Dependency-update automation present"
+//     CC7.2:
+//       title: "Security incident response"
+//       requires:
+//         - file-exists: "INCIDENT-PLAN.md"
+//
+// Verifier primitives in v1:
+//   finding-family: <name>     must-be: zero | min: <n> | max: <n>
+//   file-exists: <relative-path>
+//   documented: <relative-path>  (alias for file-exists)
+//   env-var-set: <name>
+//   sca-policy-has-entry: <type>  (e.g. accept-risk, sla)
+//
+// Output:
+//   .agentic-security/compliance-evidence.json — JSON-LD compliant
+//     structured artifact
+//   .agentic-security/compliance-evidence.md — human-readable summary
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+
+const POLICY_FILE = 'compliance.policy.yml';
+
+export function loadPolicy(scanRoot) {
+  const fp = path.join(scanRoot, '.agentic-security', POLICY_FILE);
+  if (!fs.existsSync(fp)) return null;
+  try {
+    const raw = fs.readFileSync(fp, 'utf8');
+    const doc = yaml.load(raw);
+    return _normalize(doc);
+  } catch (e) {
+    return { _error: `Failed to parse ${fp}: ${e.message}` };
+  }
+}
+
+function _normalize(doc) {
+  if (!doc) return null;
+  return {
+    framework: doc.framework || 'Custom',
+    version: doc.version || '1.0',
+    controls: Object.entries(doc.controls || {}).map(([id, c]) => ({
+      id,
+      title: c.title || id,
+      requires: Array.isArray(c.requires) ? c.requires : [],
+      evidence: Array.isArray(c.evidence) ? c.evidence : [],
+      not_applicable: !!c['not-applicable'],
+    })),
+  };
+}
+
+/**
+ * Run a single primitive check against the scanner state.
+ *   { passed, reason }
+ */
+function _runCheck(check, ctx) {
+  if (check['finding-family']) {
+    const family = check['finding-family'];
+    const matching = (ctx.findings || []).filter(f => f.family === family);
+    if (check['must-be'] === 'zero') {
+      if (matching.length === 0) return { passed: true, reason: '0 findings' };
+      return { passed: false, reason: `${matching.length} findings in family '${family}'` };
+    }
+    if (typeof check.min === 'number') {
+      if (matching.length >= check.min) return { passed: true, reason: `${matching.length} ≥ ${check.min}` };
+      return { passed: false, reason: `${matching.length} < ${check.min}` };
+    }
+    if (typeof check.max === 'number') {
+      if (matching.length <= check.max) return { passed: true, reason: `${matching.length} ≤ ${check.max}` };
+      return { passed: false, reason: `${matching.length} > ${check.max}` };
+    }
+    return { passed: false, reason: 'finding-family check has no must-be/min/max' };
+  }
+  if (check['file-exists'] || check['documented']) {
+    const rel = check['file-exists'] || check['documented'];
+    const fp = path.join(ctx.scanRoot, rel);
+    if (fs.existsSync(fp)) return { passed: true, reason: `${rel} exists` };
+    return { passed: false, reason: `${rel} not found` };
+  }
+  if (check['env-var-set']) {
+    const name = check['env-var-set'];
+    if (process.env[name]) return { passed: true, reason: `$${name} set` };
+    return { passed: false, reason: `$${name} not set` };
+  }
+  if (check['sca-policy-has-entry']) {
+    const type = check['sca-policy-has-entry'];
+    const policyPath = path.join(ctx.scanRoot, '.agentic-security', 'sca-policy.yml');
+    if (!fs.existsSync(policyPath)) return { passed: false, reason: 'sca-policy.yml not found' };
+    try {
+      const policy = yaml.load(fs.readFileSync(policyPath, 'utf8'));
+      if (type === 'accept-risk' && Array.isArray(policy['accept-risk']) && policy['accept-risk'].length) {
+        return { passed: true, reason: `${policy['accept-risk'].length} accept-risk entries` };
+      }
+      if (type === 'sla' && policy.sla && Object.keys(policy.sla).length) {
+        return { passed: true, reason: `${Object.keys(policy.sla).length} SLA buckets defined` };
+      }
+      return { passed: false, reason: `no ${type} entries in sca-policy.yml` };
+    } catch (e) {
+      return { passed: false, reason: 'sca-policy.yml parse error: ' + e.message };
+    }
+  }
+  return { passed: false, reason: 'unknown check primitive' };
+}
+
+/**
+ * Run all controls in the policy and emit a verification report.
+ */
+export function verifyPolicy(policy, ctx) {
+  if (!policy || !policy.controls) return { controls: [], status: 'no-policy' };
+  const results = [];
+  for (const control of policy.controls) {
+    if (control.not_applicable) {
+      results.push({ ...control, status: 'not-applicable', checks: [] });
+      continue;
+    }
+    const checkResults = control.requires.map(c => ({ check: c, result: _runCheck(c, ctx) }));
+    const allPassed = checkResults.every(r => r.result.passed);
+    results.push({
+      ...control,
+      status: allPassed ? 'compliant' : 'non-compliant',
+      checks: checkResults,
+    });
+  }
+  const summary = {
+    total: results.length,
+    compliant: results.filter(r => r.status === 'compliant').length,
+    nonCompliant: results.filter(r => r.status === 'non-compliant').length,
+    notApplicable: results.filter(r => r.status === 'not-applicable').length,
+  };
+  return { framework: policy.framework, version: policy.version, controls: results, summary };
+}
+
+/**
+ * Emit JSON-LD compliance evidence (the Vanta/Drata-shape artifact).
+ */
+export function emitEvidenceJsonLd(report, scanRoot) {
+  if (!report) return null;
+  const jsonld = {
+    '@context': {
+      '@vocab': 'https://agentic-security.io/compliance/v1/',
+      'schema': 'https://schema.org/',
+    },
+    '@type': 'ComplianceEvidence',
+    framework: report.framework,
+    version: report.version,
+    generatedAt: new Date().toISOString(),
+    summary: report.summary,
+    controls: report.controls.map(c => ({
+      '@type': 'Control',
+      id: c.id, title: c.title, status: c.status,
+      checks: c.checks.map(ck => ({
+        '@type': 'Check',
+        rule: ck.check,
+        passed: ck.result.passed,
+        reason: ck.result.reason,
+      })),
+      narrative_evidence: c.evidence || [],
+    })),
+  };
+  try {
+    fs.mkdirSync(path.join(scanRoot, '.agentic-security'), { recursive: true });
+    fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'compliance-evidence.json'), JSON.stringify(jsonld, null, 2));
+  } catch {}
+  return jsonld;
+}
+
+/**
+ * Emit a human-readable markdown summary.
+ */
+export function emitEvidenceMarkdown(report, scanRoot) {
+  const lines = [];
+  lines.push(`# Compliance evidence — ${report.framework}`);
+  lines.push('');
+  lines.push(`Generated by agentic-security on ${new Date().toISOString().slice(0,10)}.`);
+  lines.push('');
+  lines.push(`Compliant: **${report.summary.compliant}** / Non-compliant: **${report.summary.nonCompliant}** / Not applicable: **${report.summary.notApplicable}** of ${report.summary.total} controls.`);
+  lines.push('');
+  for (const c of report.controls) {
+    lines.push(`## ${c.id} — ${c.title}  (${c.status})`);
+    for (const ck of c.checks) {
+      const mark = ck.result.passed ? '✓' : '✗';
+      lines.push(`- ${mark} \`${JSON.stringify(ck.check)}\` — ${ck.result.reason}`);
+    }
+    if (c.evidence && c.evidence.length) {
+      lines.push('');
+      lines.push('**Narrative evidence:**');
+      for (const e of c.evidence) lines.push(`- ${e}`);
+    }
+    lines.push('');
+  }
+  try {
+    fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'compliance-evidence.md'), lines.join('\n'));
+  } catch {}
+  return lines.join('\n');
+}
+
+export const _internals = { _normalize, _runCheck };

package/src/posture/composite-risk.js

@@ -0,0 +1,122 @@
+// Composite risk score — derived 0–100 ordinal for agent + UI ordering.
+//
+// Today three independent ordinals coexist on every finding:
+//   1. f.exploitability ∈ [0,1]  (posture/exploitability.js)
+//   2. f.toxicityScore: integer  (engine.js scoreToxicity — unbounded)
+//   3. f.mitigationVerdict       (posture/mitigation-composite.js — 3-state enum)
+//
+// An agent sorting "which finding first" has no canonical key. This
+// annotator composes the three into one normalized 0–100 ordinal:
+//
+//   compositeRisk           — 0..100 number, sortable
+//   compositeRiskTier       — 'critical' | 'high' | 'medium' | 'low' | 'minimal'
+//   compositeRiskFactors    — provenance strings; same pattern as
+//                             f.exploitabilityFactors. The reader can audit
+//                             how the score was assembled.
+//
+// IMPORTANT — this is NOT a probability.
+//
+// The plan calls it a derived field on purpose: the three upstream signals
+// are themselves not calibrated probabilities. compositeRisk inherits that
+// limitation. Treat it as a triage key for "show me top 10," not as a
+// number to render as "65% likely to be exploited."
+//
+// The annotator NEVER modifies the inputs (exploitability, toxicityScore,
+// mitigationVerdict). They retain their independent shapes for callers
+// that depend on them.
+
+// Tier thresholds. Calibrated against the SEVERITY_BASE constants from
+// exploitability.js so that:
+//   - a critical sev + reachable + KEV produces a 'critical' tier
+//   - a medium sev with no extra signals produces 'low' or 'medium'
+// These can move once we have a held-out labeled corpus; for now they are
+// hand-picked.
+const TIER_THRESHOLDS = [
+  { min: 85, name: 'critical' },
+  { min: 65, name: 'high'     },
+  { min: 35, name: 'medium'   },
+  { min: 15, name: 'low'      },
+  { min:  0, name: 'minimal'  },
+];
+
+function tierFor(score) {
+  for (const t of TIER_THRESHOLDS) if (score >= t.min) return t.name;
+  return 'minimal';
+}
+
+function scoreOne(f) {
+  const factors = [];
+  // Base: exploitability is the most informative single signal. Scale 0–1
+  // to 0–100. Findings with no exploitability fall back to severity-only
+  // ordinals via toxicityScore below.
+  let base = 0;
+  if (typeof f.exploitability === 'number' && Number.isFinite(f.exploitability)) {
+    base = f.exploitability * 100;
+    factors.push(`exploit:${f.exploitability}`);
+  } else if (f.severity) {
+    // Conservative fallback: rough severity-only mapping. Stops the score
+    // from being 0 on findings that bypassed annotateExploitability.
+    const sevBase = { critical: 70, high: 55, medium: 35, low: 20, info: 10 }[f.severity];
+    if (typeof sevBase === 'number') {
+      base = sevBase;
+      factors.push(`sev-only:${f.severity}`);
+    }
+  }
+
+  // Mitigation verdict adjusts the base. 'mitigated-in-prod' and
+  // 'unreachable-in-prod' are demoting; 'exposed-in-prod' is neutral.
+  // The multipliers err conservative — even an unreachable critical KEV
+  // keeps a floor (mitigations might be wrong; the finding still merits
+  // a human glance).
+  if (f.mitigationVerdict === 'mitigated-in-prod') {
+    base *= 0.4;
+    factors.push('mitigated-in-prod');
+  } else if (f.mitigationVerdict === 'unreachable-in-prod') {
+    base *= 0.2;
+    factors.push('unreachable-in-prod');
+  } else if (f.mitigationVerdict === 'exposed-in-prod') {
+    factors.push('exposed-in-prod');
+  }
+
+  // Toxicity nudge: toxicityScore is unbounded but typically caps around
+  // 150 on the noisiest findings. Scale by /10 and cap at +15 so it can
+  // tie-break peers but never dominate.
+  if (typeof f.toxicityScore === 'number' && Number.isFinite(f.toxicityScore) && f.toxicityScore > 0) {
+    const nudge = Math.min(15, f.toxicityScore / 10);
+    base += nudge;
+    factors.push(`toxicity+${nudge.toFixed(1)}`);
+  }
+
+  // KEV / EPSS-now overrides — even when other signals are weak, an
+  // actively-weaponized CVE deserves attention. Floor at high-tier.
+  if (f.kev === true || f.kevListed === true || f.weaponized === true) {
+    base = Math.max(base, 80);
+    factors.push('kev-floor:80');
+  }
+  if (f.exploitedNow === true) {
+    base = Math.max(base, 75);
+    factors.push('exploited-now-floor:75');
+  }
+
+  const score = Math.round(Math.max(0, Math.min(100, base)));
+  return { score, factors };
+}
+
+export function annotateCompositeRisk(findings) {
+  if (!Array.isArray(findings)) return findings;
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    try {
+      const { score, factors } = scoreOne(f);
+      f.compositeRisk = score;
+      f.compositeRiskTier = tierFor(score);
+      f.compositeRiskFactors = factors;
+    } catch (_) {
+      // No-throw contract for posture annotators (see posture/CLAUDE.md).
+      f.compositeRisk = null;
+      f.compositeRiskTier = null;
+      f.compositeRiskFactors = [];
+    }
+  }
+  return findings;
+}

package/src/posture/cross-repo-memory.js

@@ -0,0 +1,180 @@
+// Cross-repo intelligence — a per-developer store of fix patterns and
+// triage decisions that span every repo this developer has used the
+// plugin against.
+//
+// Location: ~/.claude/agentic-security/cross-repo/
+//   patterns.jsonl    — append-only log of "developer fixed family X
+//                       in repo Y at commit Z using pattern P"
+//   triage.jsonl      — append-only log of "developer marked family X
+//                       in repo Y wont-fix with reason R"
+//
+// When a finding lands in the current repo, surface matching patterns
+// and triage decisions from sibling repos — "you fixed this exact shape
+// in repo-A last week; same fix here?"
+//
+// Privacy:
+//   - All data stored locally under the developer's $HOME
+//   - Nothing transmitted; no network calls
+//   - Repo identifiers are git-remote-derived SHA fingerprints, not
+//     bare names — so the store doesn't accidentally reveal repo names
+//     to anyone reading the local file
+//   - Opt-out: AGENTIC_SECURITY_NO_CROSS_REPO=1
+
+import * as cp from 'node:child_process';
+import * as fs from 'node:fs';
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+
+// Lazy — process.env.HOME may be mutated mid-process (e.g. tests isolating).
+function _storeDir() {
+  const HOME = process.env.HOME || process.env.USERPROFILE || '/tmp';
+  return path.join(HOME, '.claude', 'agentic-security', 'cross-repo');
+}
+function _patternsFile() { return path.join(_storeDir(), 'patterns.jsonl'); }
+function _triageFile()   { return path.join(_storeDir(), 'triage.jsonl'); }
+const MAX_LINES  = 5000;
+
+function _ensureDir() { try { fs.mkdirSync(_storeDir(), { recursive: true }); } catch {} }
+
+/**
+ * Stable, privacy-preserving repo fingerprint: SHA-256 of the git remote
+ * URL (or scan-root absolute path if no remote). Truncated to 12 chars.
+ */
+export function repoFingerprint(scanRoot) {
+  let source = String(scanRoot || '');
+  try {
+    const remote = cp.execFileSync('git', ['remote', 'get-url', 'origin'],
+      { cwd: scanRoot, encoding: 'utf8', timeout: 800, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (remote) source = remote;
+  } catch {}
+  return crypto.createHash('sha256').update(source).digest('hex').slice(0, 12);
+}
+
+function _appendLine(fp, obj) {
+  if (process.env.AGENTIC_SECURITY_NO_CROSS_REPO === '1') return;
+  _ensureDir();
+  try { fs.appendFileSync(fp, JSON.stringify(obj) + '\n'); } catch {}
+  _rotateIfNeeded(fp);
+}
+
+function _rotateIfNeeded(fp) {
+  try {
+    const stat = fs.statSync(fp);
+    if (stat.size < 1_000_000) return;
+    const lines = fs.readFileSync(fp, 'utf8').split('\n').filter(Boolean);
+    if (lines.length <= MAX_LINES) return;
+    fs.writeFileSync(fp, lines.slice(-MAX_LINES).join('\n') + '\n');
+  } catch {}
+}
+
+function _readAll(fp) {
+  if (process.env.AGENTIC_SECURITY_NO_CROSS_REPO === '1') return [];
+  try {
+    return fs.readFileSync(fp, 'utf8')
+      .split('\n').filter(Boolean)
+      .map(ln => { try { return JSON.parse(ln); } catch { return null; } })
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+/**
+ * Record that a finding was fixed. Caller passes the finding object +
+ * a short description of the fix pattern (often extracted from the
+ * synthesize_fix replacement text).
+ */
+export function recordFix({ scanRoot, finding, fixPattern, commitSha }) {
+  if (!finding || !finding.family) return null;
+  const entry = {
+    at: new Date().toISOString(),
+    kind: 'fix',
+    repo: repoFingerprint(scanRoot),
+    family: finding.family,
+    severity: finding.severity || null,
+    cwe: finding.cwe || null,
+    vuln: String(finding.vuln || '').slice(0, 160),
+    fixPattern: String(fixPattern || '').slice(0, 280),
+    commitSha: commitSha || null,
+  };
+  _appendLine(_patternsFile(), entry);
+  return entry;
+}
+
+/**
+ * Record a triage decision into the cross-repo store as well. (The
+ * existing posture/triage-memory.js handles the per-repo case; this
+ * mirrors it cross-repo so sibling repos benefit too.)
+ */
+export function recordTriage({ scanRoot, finding, decision, reason }) {
+  if (!finding || !decision) return null;
+  if (!['wont-fix', 'false-positive'].includes(decision)) return null;
+  const entry = {
+    at: new Date().toISOString(),
+    kind: 'triage',
+    repo: repoFingerprint(scanRoot),
+    family: finding.family || null,
+    cwe: finding.cwe || null,
+    vuln: String(finding.vuln || '').slice(0, 160),
+    decision,
+    reason: String(reason || '').slice(0, 280),
+  };
+  _appendLine(_triageFile(), entry);
+  return entry;
+}
+
+/**
+ * Look up cross-repo signals matching a new finding. Returns:
+ *   { siblingFixes: [], siblingTriage: [] }
+ *
+ * Matching is family + (cwe optional). Same-repo entries are excluded
+ * so the result is genuinely cross-repo learning.
+ */
+export function findSiblingSignals(scanRoot, finding) {
+  if (!finding || !finding.family) return { siblingFixes: [], siblingTriage: [] };
+  const here = repoFingerprint(scanRoot);
+  const fam = finding.family;
+  const fixes  = _readAll(_patternsFile()).filter(e => e.repo !== here && e.family === fam);
+  const triage = _readAll(_triageFile())  .filter(e => e.repo !== here && e.family === fam);
+  return {
+    siblingFixes:  fixes.slice(-5).reverse(),  // most recent 5
+    siblingTriage: triage.slice(-5).reverse(),
+  };
+}
+
+/**
+ * Render a short Markdown note suitable for surfacing on a finding card.
+ */
+export function renderSiblingNote(signals) {
+  if (!signals || (!signals.siblingFixes.length && !signals.siblingTriage.length)) return '';
+  const lines = [];
+  lines.push('### Cross-repo signal');
+  lines.push('');
+  if (signals.siblingFixes.length) {
+    lines.push(`Past fixes for this family in other repos:`);
+    for (const f of signals.siblingFixes) {
+      const ago = _ago(f.at);
+      lines.push(`- \`${f.repo}\` ${ago} — ${f.fixPattern || '(no pattern recorded)'}`);
+    }
+    lines.push('');
+  }
+  if (signals.siblingTriage.length) {
+    lines.push(`Past triage for this family in other repos:`);
+    for (const t of signals.siblingTriage) {
+      const ago = _ago(t.at);
+      lines.push(`- \`${t.repo}\` ${ago} — ${t.decision} (${t.reason || 'no reason'})`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function _ago(iso) {
+  if (!iso) return '';
+  const ms = Date.now() - new Date(iso).getTime();
+  const d  = Math.floor(ms / 86_400_000);
+  if (d <= 1) return 'today';
+  if (d < 7) return `${d}d ago`;
+  if (d < 30) return `${Math.floor(d / 7)}w ago`;
+  if (d < 365) return `${Math.floor(d / 30)}mo ago`;
+  return `${Math.floor(d / 365)}y ago`;
+}
+
+export const _internals = { _storeDir, _ensureDir, _ago };