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

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/threat-model-grounding.js

@@ -0,0 +1,169 @@
+// Threat-model-grounded prioritization.
+//
+// Reads project documentation (CLAUDE.md + docs/THREAT-MODEL.md + AGENTS.md)
+// to extract the project's stated threat model and applies it to finding
+// prioritization:
+//
+//   - **Crown jewels** — file globs listed under "## Crown jewels" or
+//     "## Sensitive surfaces" boost severity by one tier when a finding
+//     lands there.
+//   - **Out-of-scope** — file globs under "## Out of scope" or "## Not in
+//     threat model" demote findings to low.
+//   - **Compliance regime** — declared under "## Compliance" (e.g.
+//     SOC2 / HIPAA / GDPR) adds compliance-tag fields to findings in
+//     matching families (PII → HIPAA/GDPR; auth → SOC2 CC6.1; etc.).
+//   - **Stated attacker** — "## Attacker model" / "## Threat actor"
+//     section sets f.attackerProfile = 'script-kiddie' | 'apt' | 'insider'
+//     for use in downstream prioritization.
+//
+// Opt-out: AGENTIC_SECURITY_NO_THREAT_MODEL_GROUNDING=1
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const DOC_PATHS = [
+  'CLAUDE.md',
+  'docs/THREAT-MODEL.md',
+  'docs/threat-model.md',
+  'docs/THREATMODEL.md',
+  'THREAT-MODEL.md',
+  '.agentic-security/AGENTS.md',
+];
+
+function _readDoc(scanRoot, rel) {
+  try { return fs.readFileSync(path.join(scanRoot, rel), 'utf8'); } catch { return ''; }
+}
+
+function _allDocs(scanRoot) {
+  return DOC_PATHS.map(p => _readDoc(scanRoot, p)).join('\n\n');
+}
+
+function _extractPathsFromSection(body, sectionRegex) {
+  const sec = body.match(sectionRegex);
+  if (!sec) return [];
+  const paths = [];
+  // Match `path/like/this/**`, "path/like", or list-item paths.
+  const re = /[`"]([\w./*?\-]+)[`"]|^\s*-\s+([\w./*?\-]+)/gm;
+  let m;
+  while ((m = re.exec(sec[0]))) {
+    const p = m[1] || m[2];
+    if (p && /[\/.]/.test(p)) paths.push(p);
+  }
+  return Array.from(new Set(paths));
+}
+
+function _extractCompliance(body) {
+  const sec = body.match(/^#{1,3}\s+Compliance[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/im);
+  if (!sec) return [];
+  const found = new Set();
+  const re = /\b(SOC2|HIPAA|PCI[- ]DSS|GDPR|CCPA|FedRAMP|ISO[- ]?27001|NIST(?:[- ]?(?:CSF|800-53|AI 600-1))?|EU AI Act|OWASP (?:ASVS|LLM Top 10))\b/gi;
+  let m;
+  while ((m = re.exec(sec[0]))) found.add(m[1].toUpperCase().replace(/\s+/g, '-'));
+  return Array.from(found);
+}
+
+function _extractAttacker(body) {
+  const sec = body.match(/^#{1,3}\s+(?:Attacker model|Threat actor|Adversary)[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/im);
+  if (!sec) return null;
+  const txt = sec[0].toLowerCase();
+  if (/\bapt\b|nation[- ]?state|sophisticated/.test(txt)) return 'apt';
+  if (/\binsider\b|employee|disgruntled/.test(txt)) return 'insider';
+  if (/script[- ]?kiddie|automated|opportunistic/.test(txt)) return 'script-kiddie';
+  return 'general';
+}
+
+function _globMatch(pattern, p) {
+  const norm = String(p).replace(/\\/g, '/');
+  const re = new RegExp(
+    '^' + String(pattern).replace(/\\/g, '/')
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*\*/g, '###DSTAR###')
+      .replace(/\*/g, '[^/]*')
+      .replace(/###DSTAR###/g, '.*')
+    + '$',
+  );
+  return re.test(norm);
+}
+
+const SEVERITY_RANK = ['info', 'low', 'medium', 'high', 'critical'];
+
+function _bumpSeverity(sev) {
+  const i = SEVERITY_RANK.indexOf(sev);
+  if (i < 0 || i >= SEVERITY_RANK.length - 1) return sev;
+  return SEVERITY_RANK[i + 1];
+}
+
+const FAMILY_TO_REGIME = {
+  'pii-exposure': ['HIPAA', 'GDPR'],
+  'training-data-pii': ['GDPR'],
+  'auth-missing': ['SOC2'],
+  'authz': ['SOC2'],
+  'idor': ['SOC2'],
+  'crypto-weak-cipher': ['PCI-DSS', 'FedRAMP'],
+  'crypto-tls-no-verify': ['PCI-DSS'],
+  'hardcoded-secret': ['SOC2', 'PCI-DSS'],
+  'k8s-rbac-cluster-admin': ['SOC2'],
+  'aws-public-s3': ['SOC2', 'GDPR'],
+};
+
+/**
+ * Read project threat model from documentation. Cached per-scan-root via
+ * a module-level WeakMap-like... actually just pure read each time, since
+ * scan-time overhead is tiny.
+ */
+export function loadThreatModel(scanRoot) {
+  if (process.env.AGENTIC_SECURITY_NO_THREAT_MODEL_GROUNDING === '1') {
+    return { crownJewels: [], outOfScope: [], compliance: [], attacker: null };
+  }
+  const body = _allDocs(scanRoot);
+  return {
+    crownJewels:   _extractPathsFromSection(body, /^#{1,3}\s+(?:Crown jewels|Sensitive surfaces?)[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/im),
+    outOfScope:    _extractPathsFromSection(body, /^#{1,3}\s+(?:Out of scope|Not in threat model)[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/im),
+    compliance:    _extractCompliance(body),
+    attacker:      _extractAttacker(body),
+  };
+}
+
+/**
+ * Annotator: applies the project's threat model to each finding.
+ */
+export function applyThreatModel(scanRoot, findings) {
+  if (process.env.AGENTIC_SECURITY_NO_THREAT_MODEL_GROUNDING === '1') return { applied: 0 };
+  if (!Array.isArray(findings) || findings.length === 0) return { applied: 0 };
+  const tm = loadThreatModel(scanRoot);
+  if (!tm.crownJewels.length && !tm.outOfScope.length && !tm.compliance.length && !tm.attacker) {
+    return { applied: 0, reason: 'no-threat-model-found' };
+  }
+  let applied = 0;
+  for (const f of findings) {
+    const rel = f.file ? (path.isAbsolute(f.file) ? path.relative(scanRoot, f.file) : f.file) : '';
+
+    // Out-of-scope demotion wins over crown-jewel promotion.
+    if (rel && tm.outOfScope.some(g => _globMatch(g, rel))) {
+      f.threatModel = { ...(f.threatModel || {}), outOfScope: true };
+      f.severity = 'low';
+      applied++;
+      continue;
+    }
+    if (rel && tm.crownJewels.some(g => _globMatch(g, rel))) {
+      f.threatModel = { ...(f.threatModel || {}), crownJewel: true };
+      f.severity = _bumpSeverity(f.severity || 'medium');
+      applied++;
+    }
+    // Compliance regime tagging based on family.
+    const regimes = FAMILY_TO_REGIME[f.family];
+    if (regimes && tm.compliance.length) {
+      const matched = regimes.filter(r => tm.compliance.includes(r));
+      if (matched.length) {
+        f.threatModel = { ...(f.threatModel || {}), compliance: matched };
+        applied++;
+      }
+    }
+    if (tm.attacker) {
+      f.threatModel = { ...(f.threatModel || {}), attacker: tm.attacker };
+    }
+  }
+  return { applied, total: findings.length, threatModel: tm };
+}
+
+export const _internals = { _extractPathsFromSection, _extractCompliance, _extractAttacker, _bumpSeverity, _globMatch };

package/src/posture/time-to-fix.js

@@ -0,0 +1,129 @@
+// Time-to-fix estimator.
+//
+// Estimates engineering hours to remediate each finding from:
+//
+//   - family base difficulty (regex auth-missing ≠ deserialization)
+//   - patch shape (single-line vs cross-file refactor) from fix.code if present
+//   - prior fix-history for the same family in this project (learned base)
+//   - reachability tier (tests + verify cost adjusts)
+//
+// Output: f.estimatedFixHours, rolled-up totals + a per-family rollup so
+// the PM/PR view can show "this PR ships ~6 hours of security debt."
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const STATE = '.agentic-security';
+const HISTORY_FILE = 'fix-history/log.json';
+
+// Family base estimates (hours). Tuned from typical patch shapes.
+const FAMILY_BASE_HOURS = {
+  'sqli': 0.5, 'sql-injection': 0.5,           // parameterize one query
+  'xss': 0.5, 'mutation-xss': 1.0,
+  'command-injection': 0.5,
+  'code-injection': 2.0,                        // usually needs refactor
+  'deserialization': 4.0,                       // protocol/serializer swap
+  'auth-missing': 0.5,                          // add middleware
+  'authz': 2.0, 'idor': 2.0,                    // ownership checks across handlers
+  'csrf': 1.0,
+  'ssrf': 1.5, 'ssrf-cloud-metadata': 1.0,
+  'xxe': 0.5,
+  'open-redirect': 0.5,
+  'path-traversal': 1.0,
+  'crypto-weak-cipher': 2.0,                    // algorithm swap + key plumbing
+  'crypto-weak-hash': 1.0,
+  'crypto-tls-no-verify': 0.5,
+  'crypto-tls-version': 1.0,
+  'crypto-jwt-none': 0.5,
+  'crypto-jwt-key-confusion': 0.5,
+  'hardcoded-secret': 1.0,                       // env-var plumbing + rotation
+  'vulnerable-dependency': 0.5,                  // npm install bump
+  'dependency-confusion': 1.0,
+  'iam-overpermissive': 1.5,
+  'k8s-rbac-cluster-admin': 1.0,
+  'k8s-pod-security-privileged': 1.0,
+  'prompt-injection': 3.0,                       // architectural — prompt isolation
+  'agent-tool-exec': 4.0,                        // narrow the tool surface
+  'reentrancy': 4.0,                             // Solidity refactor + tests
+  'pqc-migration': 8.0,                          // multi-quarter project
+  'license-graph': 2.0,                          // dep swap or policy negotiation
+};
+
+function _loadFixHistory(scanRoot) {
+  const fp = path.join(scanRoot, STATE, HISTORY_FILE);
+  if (!fs.existsSync(fp)) return [];
+  try {
+    const arr = JSON.parse(fs.readFileSync(fp, 'utf8'));
+    return Array.isArray(arr) ? arr : [];
+  } catch { return []; }
+}
+
+function _historicalAvg(history, family) {
+  const matches = history.filter(h => h.family === family && typeof h.elapsedHours === 'number');
+  if (!matches.length) return null;
+  const sum = matches.reduce((a, b) => a + b.elapsedHours, 0);
+  return sum / matches.length;
+}
+
+function _patchShapeAdjust(finding) {
+  // If we have the synthesized fix code, estimate complexity from size.
+  const code = finding.fix?.code || finding.fix?.replacement || '';
+  if (!code) return 1.0;
+  const lines = code.split('\n').length;
+  if (lines <= 3)  return 1.0;
+  if (lines <= 10) return 1.4;
+  if (lines <= 30) return 2.0;
+  return 3.0;
+}
+
+function _reachAdjust(finding) {
+  // Higher reachability → more careful testing → slightly higher cost.
+  const tier = finding.reachabilityTier;
+  if (tier === 'reachable-public' || tier === 'public-unauthed') return 1.3;
+  if (tier === 'route-reachable')                                return 1.15;
+  if (tier === 'unreachable')                                    return 0.7;
+  return 1.0;
+}
+
+/**
+ * Annotate findings with estimatedFixHours. Returns
+ *   { perFinding: count, totalHours, perFamily: { fam: hours, ... } }
+ */
+export function annotateTimeToFix(scanRoot, findings) {
+  if (!Array.isArray(findings) || findings.length === 0) {
+    return { perFinding: 0, totalHours: 0, perFamily: {} };
+  }
+  const history = _loadFixHistory(scanRoot);
+  let total = 0;
+  const perFamily = {};
+  for (const f of findings) {
+    const base = _historicalAvg(history, f.family) ?? FAMILY_BASE_HOURS[f.family] ?? 1.5;
+    const patchAdj = _patchShapeAdjust(f);
+    const reachAdj = _reachAdjust(f);
+    const hours = Number((base * patchAdj * reachAdj).toFixed(2));
+    f.estimatedFixHours = hours;
+    f.estimatedFixHoursSource = _historicalAvg(history, f.family) != null ? 'history' : 'family-base';
+    total += hours;
+    perFamily[f.family || 'unknown'] = (perFamily[f.family || 'unknown'] || 0) + hours;
+  }
+  return {
+    perFinding: findings.length,
+    totalHours: Number(total.toFixed(1)),
+    perFamily: Object.fromEntries(
+      Object.entries(perFamily)
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, v]) => [k, Number(v.toFixed(1))]),
+    ),
+  };
+}
+
+/**
+ * Render a one-paragraph PM summary.
+ */
+export function renderTimeSummary(roll) {
+  if (!roll || roll.perFinding === 0) return 'No findings — 0 hours of security debt.';
+  const top = Object.entries(roll.perFamily).slice(0, 3).map(([k, v]) => `${k} (${v}h)`).join(', ');
+  return `${roll.perFinding} finding(s) — ~${roll.totalHours} engineering hours of security debt. Top families: ${top}.`;
+}
+
+export const _internals = { FAMILY_BASE_HOURS, _patchShapeAdjust, _reachAdjust, _historicalAvg };

package/src/posture/triage-memory.js

@@ -0,0 +1,151 @@
+// Triage memory — conversational triage memory layer.
+//
+// When a finding transitions to wont-fix or false-positive (via the
+// triage CLI / MCP tool / agent action), this module:
+//
+//   1. writes a structured entry to AGENTS.md so the lesson is captured
+//      for next session (continual-learning surface),
+//   2. records the decision shape (family + file-glob + reason) into
+//      .agentic-security/triage-memory.jsonl for fast pattern matching,
+//   3. provides suppressByPastDecisions() — an annotator that pre-demotes
+//      findings whose (family, file-glob) was previously marked wont-fix
+//      or false-positive in the same project.
+//
+// This is the dialogue-aware analogue to posture/triage-learning.js,
+// which adjusts confidence calibration from triage counts. triage-memory
+// works on the discrete narrative ("we decided this is fine, here's
+// why") rather than on calibration math.
+//
+// Opt-out: AGENTIC_SECURITY_NO_TRIAGE_MEMORY=1
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const STATE_DIR = '.agentic-security';
+const MEMORY_FILE = 'triage-memory.jsonl';
+const AGENTS_FILE = 'AGENTS.md';
+
+function _stateDir(scanRoot) { return path.join(scanRoot, STATE_DIR); }
+function _memPath(scanRoot)  { return path.join(_stateDir(scanRoot), MEMORY_FILE); }
+function _agentsPath(scanRoot) { return path.join(_stateDir(scanRoot), AGENTS_FILE); }
+
+function _bucketKey(finding) {
+  const file = finding.file || finding.file_path || '';
+  const dir = file.split('/').slice(0, -1).join('/') || '.';
+  return `${finding.family || finding.parser || 'unknown'}::${dir}`;
+}
+
+/**
+ * Record a triage decision into both AGENTS.md (narrative) and
+ * triage-memory.jsonl (structured). Idempotent — repeated calls add a
+ * single new line; existing entries are not deduped (history is a feature).
+ */
+export function recordDecision(scanRoot, finding, decision, reason) {
+  if (!scanRoot || !finding || !decision) return null;
+  if (!['wont-fix', 'false-positive'].includes(decision)) return null;
+  try { fs.mkdirSync(_stateDir(scanRoot), { recursive: true }); } catch {}
+
+  const entry = {
+    at: new Date().toISOString(),
+    decision,
+    reason: String(reason || '').slice(0, 280),
+    bucket: _bucketKey(finding),
+    family: finding.family || null,
+    severity: finding.severity || null,
+    cwe: finding.cwe || null,
+    vuln: (finding.vuln || finding.title || '').slice(0, 160),
+    file: finding.file || finding.file_path || '',
+    line: finding.line || 0,
+    id: finding.id || finding.stableId || null,
+  };
+  try { fs.appendFileSync(_memPath(scanRoot), JSON.stringify(entry) + '\n'); } catch {}
+
+  // Narrative entry in AGENTS.md — short, human-readable, surfaced at SessionStart.
+  const narrative = [
+    `## Triage decision — ${entry.at.slice(0, 10)}  (${decision})`,
+    `- Finding: ${entry.vuln || entry.family || 'unknown'} at ${entry.file}:${entry.line}`,
+    `- Bucket: \`${entry.bucket}\``,
+    reason ? `- Why: ${entry.reason}` : null,
+    `- Future scans should treat similar findings under this bucket as already-reviewed.`,
+    '',
+  ].filter(Boolean).join('\n');
+  try { fs.appendFileSync(_agentsPath(scanRoot), '\n' + narrative); } catch {}
+
+  return entry;
+}
+
+/**
+ * Load past decisions from triage-memory.jsonl.
+ */
+export function loadMemory(scanRoot) {
+  const fp = _memPath(scanRoot);
+  if (!fs.existsSync(fp)) return [];
+  try {
+    return fs.readFileSync(fp, 'utf8')
+      .split('\n').filter(Boolean)
+      .map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+/**
+ * Annotator: for each finding, check if its (family, file-glob) bucket
+ * was previously marked wont-fix or false-positive in this project. If
+ * so, attach `pastDecision` metadata and lower confidence.
+ *
+ * Does NOT remove findings — only annotates. UI / report layer decides
+ * how to display.
+ */
+export function suppressByPastDecisions(scanRoot, findings) {
+  if (process.env.AGENTIC_SECURITY_NO_TRIAGE_MEMORY === '1') return { applied: 0 };
+  if (!Array.isArray(findings) || findings.length === 0) return { applied: 0 };
+  const memory = loadMemory(scanRoot);
+  if (!memory.length) return { applied: 0 };
+
+  // Build bucket → most-recent decision map.
+  const bucketDecision = new Map();
+  for (const e of memory) {
+    if (!bucketDecision.has(e.bucket) || bucketDecision.get(e.bucket).at < e.at) {
+      bucketDecision.set(e.bucket, e);
+    }
+  }
+
+  let applied = 0;
+  for (const f of findings) {
+    const key = _bucketKey(f);
+    const past = bucketDecision.get(key);
+    if (!past) continue;
+    f.pastDecision = {
+      decision: past.decision,
+      at: past.at,
+      reason: past.reason,
+      sameBucket: true,
+    };
+    // Soft demote: drop confidence and add a tag explaining why.
+    if (typeof f.confidence === 'number') f.confidence = Math.max(0.2, f.confidence * 0.5);
+    f.tags = Array.isArray(f.tags) ? f.tags : [];
+    if (!f.tags.includes('past-decision')) f.tags.push('past-decision');
+    applied++;
+  }
+  return { applied, total: findings.length };
+}
+
+/**
+ * Search past triage decisions by natural-language query terms. Naive
+ * keyword match for v1 — sufficient when memory is < 1000 entries.
+ * Future: vector search against an embedding store.
+ */
+export function queryMemory(scanRoot, query) {
+  const memory = loadMemory(scanRoot);
+  if (!query || !memory.length) return memory.slice(-10);
+  const terms = String(query).toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return memory.slice(-10);
+  const scored = memory.map(e => {
+    const haystack = [e.reason, e.vuln, e.family, e.file, e.bucket].join(' ').toLowerCase();
+    const score = terms.reduce((s, t) => s + (haystack.includes(t) ? 1 : 0), 0);
+    return { ...e, score };
+  });
+  return scored.filter(e => e.score > 0).sort((a, b) => b.score - a.score).slice(0, 10);
+}
+
+export const _internals = { _bucketKey, _memPath, _agentsPath };

package/src/posture/triage.js

@@ -6,6 +6,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { statePath, safeWriteState } from './state-dir.js';
 import { appendAcceptRiskFromTriage } from './sca-policy.js';
+import { recordDecision as recordTriageMemory } from './triage-memory.js';
+import { recordTriage as recordCrossRepoTriage } from './cross-repo-memory.js';
 
 export const STATES = ['open', 'in-progress', 'fixed', 'wont-fix', 'false-positive'];
 
@@ -105,7 +107,19 @@ export function transition(scanRoot, id, toState, comment) {
       policyBridge = { ok: false, reason: String(e && e.message || e) };
     }
   }
-  return { ok: true, policyBridge };
+  // Triage-memory bridge — write a narrative entry to AGENTS.md and a
+  // structured entry to triage-memory.jsonl whenever a finding is marked
+  // wont-fix or false-positive. The next scan's suppressByPastDecisions
+  // annotator demotes similar findings by bucket (family + dir).
+  let memoryBridge = null;
+  if (['wont-fix', 'false-positive'].includes(toState)) {
+    try { memoryBridge = recordTriageMemory(scanRoot, cur, toState, comment); }
+    catch (e) { memoryBridge = { ok: false, reason: String(e && e.message || e) }; }
+    // Also mirror into the cross-repo store so sibling repos benefit.
+    try { recordCrossRepoTriage({ scanRoot, finding: cur, decision: toState, reason: comment }); }
+    catch {}
+  }
+  return { ok: true, policyBridge, memoryBridge };
 }
 
 export function comment(scanRoot, id, author, body) {