@clear-capabilities/agentic-security-scanner 0.140.0 → 0.141.0

package/src/posture/compliance-frameworks/owasp-llm-top-10.json

@@ -4,66 +4,135 @@
   "publisher": "OWASP Foundation",
   "license": "Creative Commons Attribution-ShareAlike 4.0",
   "url": "https://owasp.org/www-project-top-10-for-large-language-model-applications/",
+  "scope": "FULL TOP-10. All ten categories are present. Each category is a broad class rather than a single testable requirement, so a mapping indicates a detector exists for part of the class, not that the class is fully covered.",
+  "controlsDigest": "0a0351a9536790e4",
+  "controlCount": 10,
   "controls": [
     {
       "id": "LLM01",
       "summary": "Prompt Injection — controls preventing injected instructions from overriding the system prompt.",
-      "evidence": ["Zero open findings in family prompt-injection / llm-app-security.", "Prompt-template integrity check passing."],
-      "mapsTo": ["family:prompt-injection", "family:llm-app-security", "family:prompt-integrity"]
+      "codeTestable": "yes",
+      "evidence": [
+        "Zero open findings in family prompt-injection / llm-app-security.",
+        "Prompt-template integrity check passing."
+      ],
+      "mapsTo": [
+        "family:prompt-injection",
+        "family:llm-app-security",
+        "family:prompt-integrity"
+      ]
     },
     {
       "id": "LLM02",
       "summary": "Insecure Output Handling — LLM output is not directly piped to dangerous sinks (eval/shell/SQL/HTML).",
-      "evidence": ["Zero open findings in subfamily llm-output-untrusted-sink."],
-      "mapsTo": ["family:llm-app-security:llm-output-untrusted-sink"]
+      "codeTestable": "yes",
+      "evidence": [
+        "Zero open findings in subfamily llm-output-untrusted-sink."
+      ],
+      "mapsTo": [
+        "family:llm-app-security:llm-output-untrusted-sink"
+      ]
     },
     {
       "id": "LLM03",
       "summary": "Training Data Poisoning — provenance and integrity controls on training/fine-tuning data.",
-      "evidence": ["No streaming-dataset-url findings.", "datasets.load_dataset uses pinned revisions."],
-      "mapsTo": ["family:streaming-dataset-url", "family:hf-datasets-rce"]
+      "codeTestable": "yes",
+      "evidence": [
+        "No streaming-dataset-url findings.",
+        "datasets.load_dataset uses pinned revisions."
+      ],
+      "mapsTo": [
+        "family:streaming-dataset-url",
+        "family:hf-datasets-rce"
+      ]
     },
     {
       "id": "LLM04",
       "summary": "Model Denial of Service — rate-limit / token-cap controls.",
-      "evidence": ["LLM API calls in source carry an explicit max_tokens cap (bodyguard rule no-max-tokens)."],
-      "mapsTo": ["rule:no-max-tokens"]
+      "codeTestable": "no",
+      "evidence": [
+        "LLM API calls in source carry an explicit max_tokens cap (bodyguard rule no-max-tokens)."
+      ],
+      "mapsTo": [
+        "rule:no-max-tokens"
+      ]
     },
     {
       "id": "LLM05",
       "summary": "Supply Chain — model & dataset supply-chain integrity.",
-      "evidence": ["No mlflow-untrusted-uri / model-format / hf-endpoint-override findings.", "Sigstore provenance verification configured if opt-in."],
-      "mapsTo": ["family:mlflow-untrusted-uri", "family:model-format", "family:hf-endpoint-override"]
+      "codeTestable": "yes",
+      "evidence": [
+        "No mlflow-untrusted-uri / model-format / hf-endpoint-override findings.",
+        "Sigstore provenance verification configured if opt-in."
+      ],
+      "mapsTo": [
+        "family:mlflow-untrusted-uri",
+        "family:model-format",
+        "family:hf-endpoint-override"
+      ]
     },
     {
       "id": "LLM06",
       "summary": "Sensitive Information Disclosure — output filters prevent leakage.",
-      "evidence": ["Zero findings in subfamily llm-credential-in-prompt.", "Redact module covers prompt + response."],
-      "mapsTo": ["family:llm-app-security:llm-credential-in-prompt"]
+      "codeTestable": "yes",
+      "evidence": [
+        "Zero findings in subfamily llm-credential-in-prompt.",
+        "Redact module covers prompt + response."
+      ],
+      "mapsTo": [
+        "family:llm-app-security:llm-credential-in-prompt"
+      ]
     },
     {
       "id": "LLM07",
       "summary": "Insecure Plugin / Tool Design — tools the LLM can invoke are narrowly scoped.",
-      "evidence": ["Zero llm-app-security:llm-tool-exec findings.", "Agent tool definitions reviewed for excessive agency."],
-      "mapsTo": ["family:agent-tool-exec", "family:llm-app-security:llm-tool-exec"]
+      "codeTestable": "yes",
+      "evidence": [
+        "Zero llm-app-security:llm-tool-exec findings.",
+        "Agent tool definitions reviewed for excessive agency."
+      ],
+      "mapsTo": [
+        "family:agent-tool-exec",
+        "family:llm-app-security:llm-tool-exec"
+      ]
     },
     {
       "id": "LLM08",
       "summary": "Excessive Agency — agent autonomy is bounded by explicit guards.",
-      "evidence": ["MCP server config limits write-tools to confirm:true + reserved-write-path refusal.", "Apply-fix path requires HMAC-verified scan."],
-      "mapsTo": ["module:mcp-tools", "module:apply-fix"]
+      "codeTestable": "partial",
+      "evidence": [
+        "MCP server config limits write-tools to confirm:true + reserved-write-path refusal.",
+        "Apply-fix path requires HMAC-verified scan."
+      ],
+      "mapsTo": [
+        "module:mcp-tools",
+        "module:apply-fix"
+      ]
     },
     {
       "id": "LLM09",
       "summary": "Overreliance — human review checkpoints exist.",
-      "evidence": ["security-fixer agent has Stop-on-verify-fail loop.", "PreToolUse bodyguard exists."],
-      "mapsTo": ["module:security-fixer", "module:pre-edit-bodyguard"]
+      "codeTestable": "partial",
+      "evidence": [
+        "security-fixer agent has Stop-on-verify-fail loop.",
+        "PreToolUse bodyguard exists."
+      ],
+      "mapsTo": [
+        "module:security-fixer",
+        "module:pre-edit-bodyguard"
+      ]
     },
     {
       "id": "LLM10",
       "summary": "Model Theft — model access controls.",
-      "evidence": ["No private-key-in-frontend or rpc-key-inline findings in client code."],
-      "mapsTo": ["family:private-key-in-frontend", "family:rpc-key-inline"]
+      "codeTestable": "yes",
+      "evidence": [
+        "No private-key-in-frontend or rpc-key-inline findings in client code."
+      ],
+      "mapsTo": [
+        "family:private-key-in-frontend",
+        "family:rpc-key-inline"
+      ]
     }
   ]
 }

package/src/posture/concurrency-checker.js

@@ -264,7 +264,7 @@ export function scanConcurrency(fileContents) {
           // label. Found while auditing the wrong-CWE bucket: 57% of findings
           // on a Go/Ruby sample had no cwe at all.
           cwe: 'CWE-667',
-          family: 'concurrency-bug',
+          family: 'concurrency-bug', parser: 'CONCURRENCY',
           confidence: 0.5,
           remediation: bug.remediation || 'Release the lock on every exit path (defer / try-finally / context manager).',
         });
@@ -277,7 +277,7 @@ export function scanConcurrency(fileContents) {
           vuln: `Concurrency: fire-and-forget async call in ${fn.name}() — result not awaited`,
           severity: 'low',
           cwe: 'CWE-703', // Improper Check or Handling of Exceptional Conditions
-          family: 'concurrency-bug',
+          family: 'concurrency-bug', parser: 'CONCURRENCY',
           confidence: 0.4,
           remediation: 'Await the promise / call .get() on the future / use asyncio.gather.',
         });
@@ -292,7 +292,7 @@ export function scanConcurrency(fileContents) {
         vuln: `Concurrency: potential deadlock — ${bug.order}`,
         severity: 'high',
         cwe: 'CWE-833', // Deadlock
-        family: 'concurrency-bug',
+        family: 'concurrency-bug', parser: 'CONCURRENCY',
         confidence: 0.4,
         remediation: 'Acquire locks in a consistent global order across all call sites.',
       });

package/src/posture/coverage-strength.js

@@ -0,0 +1,182 @@
+// Measured evidence strength for a compliance control (PRD F10.2).
+//
+// THE PROBLEM THIS EXISTS FOR
+// ---------------------------
+// A control mapped to a detector with 5% recall is COVERED in the coverage map
+// and UNCOVERED in reality. The map said "family:sql-injection → checked" and
+// stopped there, so a reader could not tell a control backed by a detector that
+// finds nearly everything from one backed by a detector that finds almost
+// nothing. The PRD calls closing that its highest-integrity change, and this is
+// the closing.
+//
+// THE JOIN
+// --------
+//   control → mapped family
+//           → producing detector        (posture/family-registry.js)
+//           → the CWEs that family carries   (bench/family-producers/OBSERVED.json)
+//           → measured recall for those CWEs (bench/family-producers/RECALL.json)
+//
+// The recall numbers come from bench/independent: advisories mined from public
+// sources, NOT authored here. That matters more than the numbers themselves —
+// a control cannot look well-evidenced because the engine graded its own
+// homework.
+//
+// WHAT "UNMEASURED" MEANS, AND WHY IT IS NOT "FINE"
+// ------------------------------------------------
+// A CWE the independent corpus never exercised has NO recall figure. That is
+// unmeasured, and unmeasured is reported as unmeasured — never silently treated
+// as passing, and never given a default number. Roughly half the observed
+// families are in that state today. Saying so is the honest output; inventing a
+// figure for them would be the failure this module exists to prevent.
+//
+// Every rate is carried as {n, d} and rendered through the caller's formatter,
+// following posture/accuracy-scorecard.js: a percentage must never appear
+// without its denominator, because "50% recall" over two samples is noise.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { producersOf } from './family-registry.js';
+import { resolveFamilyKeys } from './family-resolve.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BENCH = path.join(HERE, '..', '..', '..', 'bench', 'family-producers');
+
+// Thresholds. Deliberately coarse — the underlying denominators are small, and a
+// finer scale would imply a precision the measurement does not have.
+const WEAK_BELOW = 0.25;
+const PARTIAL_BELOW = 0.60;
+
+// Below this many scored entries a rate is reported but flagged as indicative,
+// mirroring accuracy-scorecard.js's `reliable:false` treatment.
+const RELIABLE_MIN_D = 5;
+
+let _cache = null;
+
+function _load() {
+  if (_cache) return _cache;
+  const read = (f, fallback) => {
+    try { return JSON.parse(fs.readFileSync(path.join(BENCH, f), 'utf8')); }
+    catch { return fallback; }
+  };
+  // A missing artifact must degrade to "unmeasured", never to a default rate —
+  // same reasoning as the unmeasured tier itself.
+  const observed = read('OBSERVED.json', { families: {} });
+  const recall = read('RECALL.json', { byCwe: {} });
+  _cache = { families: observed.families || {}, byCwe: recall.byCwe || {}, population: recall.population || null };
+  return _cache;
+}
+
+/** Reset the memo. Tests only. */
+export function _resetCache() { _cache = null; }
+
+/**
+ * The CWEs a family mapping was observed to carry, most frequent first.
+ *
+ * Resolves the mapping the SAME way the evaluator does — exact, alias, or
+ * `<base>-<rule-slug>` suffix — via the shared resolver. Looking `family` up as
+ * a literal key reported "unmeasured" for every aliased mapping: ASVS V5.1 maps
+ * to `family:sqli`, nothing emits `sqli`, and the real family `sql-injection` IS
+ * measured. That would be a false "no evidence" verdict on a control that has
+ * evidence.
+ */
+export function cwesFor(family) {
+  const { families } = _load();
+  const keys = resolveFamilyKeys(family, Object.keys(families));
+  const counts = new Map();
+  for (const k of keys) {
+    for (const [cwe, n] of Object.entries((families[k] || {}).cwes || {})) {
+      counts.set(cwe, (counts.get(cwe) || 0) + n);
+    }
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([c]) => c);
+}
+
+/**
+ * Measured strength of the detector(s) behind `family`.
+ *
+ * Returns { tier, recall:{n,d}|null, cwes, measuredCwes, reliable, producers, reason }.
+ * `tier` ∈ 'measured' | 'partial' | 'weak' | 'unmeasured'.
+ */
+export function strengthOf(family) {
+  const { byCwe } = _load();
+  const cwes = cwesFor(family);
+  const producers = producersOf(family);
+
+  // Aggregate across every CWE this family carries that the independent corpus
+  // actually exercised. Summing {n,d} weights by how much evidence each CWE has,
+  // which is what we want — averaging the percentages would let a 1-of-1 CWE
+  // outvote a 40-of-100 one.
+  let n = 0, d = 0;
+  const measuredCwes = [];
+  for (const c of cwes) {
+    const m = byCwe[c];
+    if (!m || !m.recall || !m.recall.d) continue;
+    n += m.recall.n; d += m.recall.d;
+    measuredCwes.push(c);
+  }
+
+  if (!d) {
+    return {
+      tier: 'unmeasured',
+      recall: null,
+      cwes, measuredCwes: [], reliable: false, producers,
+      reason: cwes.length
+        ? 'no CWE this family carries was exercised by the independent corpus'
+        : 'no CWE observed for this family — nothing to measure against',
+    };
+  }
+
+  const rate = n / d;
+  const tier = rate < WEAK_BELOW ? 'weak' : rate < PARTIAL_BELOW ? 'partial' : 'measured';
+  return {
+    tier,
+    recall: { n, d },
+    cwes, measuredCwes,
+    reliable: d >= RELIABLE_MIN_D,
+    producers,
+    reason: `measured over ${d} independent advisor${d === 1 ? 'y' : 'ies'}`,
+  };
+}
+
+/**
+ * Strength for a control, taken across every family it maps to.
+ *
+ * The WEAKEST backing family wins. A control is only as evidenced as its
+ * flimsiest leg: claiming the average would let a strong mapping hide a
+ * mapping that finds nothing.
+ */
+export function strengthOfControl(control) {
+  const families = (control && Array.isArray(control.mapsTo) ? control.mapsTo : [])
+    .filter(m => typeof m === 'string' && m.startsWith('family:'))
+    .map(m => m.slice('family:'.length).split(':')[0]);
+
+  if (!families.length) return { tier: 'unmeasured', families: [], legs: [], reason: 'control has no family: mapping' };
+
+  const legs = families.map(f => ({ family: f, ...strengthOf(f) }));
+  const ORDER = { unmeasured: 0, weak: 1, partial: 2, measured: 3 };
+  const weakest = legs.reduce((a, b) => (ORDER[b.tier] < ORDER[a.tier] ? b : a));
+  return {
+    tier: weakest.tier,
+    families, legs,
+    reason: `weakest backing family "${weakest.family}": ${weakest.reason}`,
+  };
+}
+
+/**
+ * True when a control should NOT be presented as cleanly evidenced, because the
+ * detector behind it is weak or was never measured. This is the flag the
+ * coverage map carries.
+ */
+export function isPartiallyEvidenced(control) {
+  const s = strengthOfControl(control);
+  return s.tier === 'weak' || s.tier === 'unmeasured';
+}
+
+/** Human-readable, denominator-carrying label for a report. */
+export function formatStrength(s) {
+  if (!s || s.tier === 'unmeasured') return 'unmeasured (no independent evidence)';
+  const { n, d } = s.recall || (s.legs && s.legs.length ? s.legs[0].recall : null) || {};
+  if (n == null) return `${s.tier} (no rate)`;
+  const pct = Math.round((n / d) * 100);
+  return `${s.tier} — recall ${n}/${d} (${pct}%)${s.reliable === false ? ', indicative only' : ''}`;
+}

package/src/posture/epss.js

@@ -38,12 +38,28 @@ function cachePath(cveListKey) {
   return path.join(CACHE_DIR, h + '.json');
 }
 
+// PRD F3.4 — record how old the EPSS data actually is.
+//
+// EPSS scores decay in relevance: a probability computed months ago describes a
+// threat landscape that has moved. Unlike KEV, a stale EPSS score can err in
+// EITHER direction, so the age is reported rather than the value suppressed.
+let _epssMeta = { source: 'not-loaded', ageDays: null, stale: null };
+const EPSS_STALE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
+export function epssCacheMeta() { return { ..._epssMeta }; }
+
 function readCache(key) {
   const fp = cachePath(key);
   if (!fs.existsSync(fp)) return null;
   try {
     const stat = fs.statSync(fp);
-    if (Date.now() - stat.mtimeMs > TTL_MS) return null;
+    const age = Date.now() - stat.mtimeMs;
+    if (age > TTL_MS) return null;
+    _epssMeta = {
+      source: 'cache',
+      ageDays: Math.floor(age / 86400000),
+      stale: age > EPSS_STALE_AFTER_MS,
+      meaning: 'EPSS is a decaying probability; an old score describes a threat landscape that has moved.',
+    };
     return JSON.parse(fs.readFileSync(fp, 'utf8'));
   } catch { return null; }
 }

package/src/posture/family-registry.js

@@ -0,0 +1,103 @@
+// Producer registry (PRD F10.2) — which detector emits which finding family.
+//
+// WHY THIS EXISTS
+// ---------------
+// Compliance controls map to families (`family:sql-injection`). Answering "is
+// this control backed by a real detector, and how good is that detector?"
+// requires knowing the family vocabulary. Nothing could answer that:
+//
+//   - A textual search cannot. Detectors set `family` positionally
+//     (`_shape(file, line, ruleId, vuln, fam, …)`) or from a rule table
+//     (`family: rule.family`), so grepping `family:` misses them entirely. A
+//     search-derived list was used once to declare four families "unevidenceable";
+//     all four had producers, and 15 working controls were suppressed as a result.
+//   - A corpus sweep cannot. It reports only what some fixture triggered — a
+//     LOWER BOUND. `k8s-pod-security-privileged` was absent from a 116-root sweep
+//     and present in a 331-root one; nothing about the engine changed.
+//
+// So the detector declares, in the file that emits: `export const EMITS = [...]`.
+// Colocation is the point — the rule and its declaration are edited together, and
+// the gate below catches the case where they are not.
+//
+// SCOPE, STATED HONESTLY
+// ----------------------
+// Registration is per-module and incremental. 287 detector modules exist; the
+// ones listed here are registered so far, chosen because they set `family`
+// positionally (invisible to every other method) and back compliance mappings.
+//
+// A module that is registered is held to COMPLETENESS: a scan producing a family
+// it did not declare fails the gate. A module that is not registered is not
+// silently passing — it is absent, and `test/family-registry.test.js` reports the
+// undeclared remainder as a ratchet that must not grow. That is the difference
+// between a gate that expands over time and one that gets switched off in week
+// two for failing on day one.
+import { EMITS as CLOUD_IAM } from '../sast/cloud-iam.js';
+import { EMITS as CRYPTO_PROTOCOL } from '../sast/crypto-protocol.js';
+import { EMITS as DAPP_FRONTEND } from '../sast/dapp-frontend.js';
+import { EMITS as K8S_ADMISSION } from '../sast/k8s-admission.js';
+import { EMITS as ML_SUPPLY_CHAIN } from '../sast/ml-supply-chain.js';
+import { EMITS as WEB3_ADVANCED } from '../sast/web3-advanced.js';
+
+// module path -> declared families. Path is the identity a human greps for.
+export const REGISTERED = Object.freeze({
+  'sast/cloud-iam.js': CLOUD_IAM,
+  'sast/crypto-protocol.js': CRYPTO_PROTOCOL,
+  'sast/dapp-frontend.js': DAPP_FRONTEND,
+  'sast/k8s-admission.js': K8S_ADMISSION,
+  'sast/ml-supply-chain.js': ML_SUPPLY_CHAIN,
+  'sast/web3-advanced.js': WEB3_ADVANCED,
+});
+
+// The `parser` field each registered module stamps on its findings. This is how a
+// finding is attributed back to its module at runtime.
+//
+// NOT every parser identifies a module: `REGEX` alone covers 80 distinct
+// families, and `STRUCTURAL` covers 23. Those are shared labels, so a module
+// using one cannot be registered for completeness until it stamps something
+// specific. Only module-specific parsers appear here, and the gate checks
+// attribution only for these.
+export const PARSER_OF = Object.freeze({
+  'sast/cloud-iam.js': 'CLOUD-IAM',
+  'sast/crypto-protocol.js': 'CRYPTO-PROTO',
+  'sast/dapp-frontend.js': 'DAPP-FRONTEND',
+  'sast/k8s-admission.js': 'K8S-ADM',
+  'sast/ml-supply-chain.js': 'ML-SUPPLY',
+  'sast/web3-advanced.js': 'WEB3-ADV',
+});
+
+/** Every family any registered module declares. */
+export function declaredFamilies() {
+  const out = new Set();
+  for (const list of Object.values(REGISTERED)) for (const f of list) out.add(f);
+  return out;
+}
+
+/** Module paths declaring `family`, or [] if none does. */
+export function producersOf(family) {
+  return Object.entries(REGISTERED)
+    .filter(([, list]) => list.includes(family))
+    .map(([mod]) => mod);
+}
+
+/** The module registered for `parser`, or null when the parser is not module-specific. */
+export function moduleForParser(parser) {
+  const hit = Object.entries(PARSER_OF).find(([, p]) => p === parser);
+  return hit ? hit[0] : null;
+}
+
+/**
+ * Families a registered module emitted but never declared — the drift this whole
+ * mechanism exists to catch. `findings` is any array carrying {family, parser}.
+ */
+export function undeclaredFrom(findings) {
+  const out = new Map(); // module -> Set(family)
+  for (const f of findings || []) {
+    if (!f || !f.family || !f.parser) continue;
+    const mod = moduleForParser(f.parser);
+    if (!mod) continue;                       // parser is not module-specific
+    if (REGISTERED[mod].includes(f.family)) continue;
+    if (!out.has(mod)) out.set(mod, new Set());
+    out.get(mod).add(f.family);
+  }
+  return out;
+}

package/src/posture/family-resolve.js

@@ -0,0 +1,47 @@
+// Shared family-name resolution for compliance mappings.
+//
+// Extracted into its own module to break an import CYCLE: the evaluator
+// (auditor-walkthrough.js) needs the resolver to count findings, and
+// coverage-strength.js needs the SAME resolver to measure detector strength. When
+// the resolver lived in the evaluator and the evaluator imported strength back,
+// ESM handed one side an undefined binding and a defensive try/catch turned that
+// into a silently missing `evidence` field — a wrong answer wearing the costume
+// of a working one.
+//
+// One definition, no cycle, both callers import from here.
+
+export const COMPLIANCE_FAMILY_ALIAS = {
+  // ASVS spells it `sqli`; every detector emits `sql-injection` (or a
+  // language-prefixed variant, which the suffix rule below does NOT cover
+  // because the prefix is on the wrong end).
+  'sqli': ['sql-injection', 'dart-sql-injection', 'laravel-sql-injection'],
+  'auth-missing': ['broken-access-control', 'fastapi-missing-auth', 'springboot-missing-authz', 'laravel-missing-auth', 'quarkus-missing-authz'],
+  'authz': ['broken-access-control', 'idor', 'springboot-missing-authz', 'quarkus-missing-authz'],
+  'k8s-pod-security-privileged': ['k8s-pod-privileged'],
+};
+
+/**
+ * The emitted families a `family:X` mapping resolves to, given the families a
+ * scan actually produced.
+ *
+ * Exported because TWO callers must agree: this file's evaluator (does the
+ * control have open findings?) and posture/coverage-strength.js (how good is the
+ * detector behind it?). When only the evaluator knew the rule, the strength
+ * module reported "unmeasured" for every aliased or suffixed mapping — a false
+ * "no evidence" verdict on controls that are in fact measured, which is the
+ * mirror image of the vacuous-pass bug this file already fixes. One rule, one
+ * definition.
+ *
+ * Resolution is exact match, alias, or `<base>-<rule-slug>` suffix. The `-`
+ * separator is load-bearing: without it `nosql-injection` would satisfy a
+ * `sql-injection` mapping.
+ */
+export function resolveFamilyKeys(fam, availableKeys) {
+  const bases = [fam, ...(COMPLIANCE_FAMILY_ALIAS[fam] || [])];
+  const out = [];
+  for (const key of availableKeys) {
+    if (bases.some(b => key === b || key.startsWith(`${b}-`))) out.push(key);
+  }
+  return out;
+}
+

package/src/posture/fix-coverage.js

@@ -0,0 +1,113 @@
+// PRD F6.5 — publish the proportion of findings this engine DECLINES to fix.
+//
+// A remediation feature that silently attempts everything is less trustworthy
+// than one that declines 40% and says so. Before this, the only visible number
+// was about fixes that were attempted; a finding for which synthesis was never
+// even tried simply did not appear, so the denominator quietly excluded every
+// hard case.
+//
+// THE BUCKETS
+//
+//   deterministic — a context-independent literal swap exists (md5 -> sha256,
+//                   TLS verify off -> on). Highest confidence: the patch does
+//                   not depend on reading intent.
+//   model         — no deterministic patch, but the finding is a shape a model
+//                   can be asked to fix. Counted as ATTEMPTABLE, not as fixed:
+//                   whether the attempt succeeds is fix-metrics.js's question.
+//   declined      — synthesis refuses, with a reason. Not a failure; a limit
+//                   stated up front.
+//
+// `declined` and `model` are kept apart for the same reason proof-coverage
+// separates `indeterminate` from `unclassified`: "we will not try" and "we will
+// try and might fail" are different promises, and merging them lets the weaker
+// one borrow the stronger one's credibility.
+import { synthesizeDeterministicPatch } from './deterministic-fix.js';
+
+// Families where a patch cannot be synthesised from the finding alone, with the
+// reason. Stated as DATA so a report can print why, rather than leaving a reader
+// to assume the engine simply has not got round to it.
+export const DECLINED_TO_FIX = Object.freeze({
+  'broken-access-control': 'the correct authorisation rule is a product decision — a scanner that invents one is guessing at intent, and a wrong authz patch fails open.',
+  'idor': 'same as broken-access-control: which identity may read which record is not recoverable from the code.',
+  'broken-authz': 'the rule that was checked wrongly is a product decision; patching it from the code alone guesses at which roles may do what, and guessing fails open.',
+  'business-logic': 'by definition the defect is a mismatch with intent, and intent is not in the file.',
+  'concurrency-bug': 'the correct lock discipline depends on the whole call graph; a local patch can deadlock rather than fix.',
+  'license-graph': 'a licence conflict is resolved by a policy or a dependency decision, not by editing code.',
+  'vulnerable-dep': 'resolved by an upgrade, which is apply_sca_upgrade\'s job, not a source patch.',
+});
+
+/** Bucket a finding: 'deterministic' | 'model' | 'declined'. */
+export function fixBucketOf(finding, fileContent) {
+  const fam = (finding && finding.family) || '';
+  for (const key of Object.keys(DECLINED_TO_FIX)) {
+    if (fam === key || fam.startsWith(`${key}-`)) return 'declined';
+  }
+  if (typeof fileContent === 'string' && fileContent) {
+    try {
+      const p = synthesizeDeterministicPatch(finding, fileContent);
+      if (p && p.ok !== false && (p.patch || p.replacement)) return 'deterministic';
+    } catch { /* fall through — an erroring synthesiser is not a fix */ }
+  }
+  return 'model';
+}
+
+/**
+ * Fix coverage over a finding set.
+ *
+ * Every share carries {n, d}. `fileContents` is optional: without it the
+ * deterministic check cannot run, and rather than guessing, those findings fall
+ * to `model` and `deterministicChecked` reports false so a reader knows the
+ * split is a lower bound on deterministic coverage.
+ */
+export function fixCoverage(findings, fileContents = null) {
+  const list = Array.isArray(findings) ? findings.filter(Boolean) : [];
+  const d = list.length;
+  const buckets = { deterministic: [], model: [], declined: [] };
+  for (const f of list) {
+    const src = fileContents && f.file ? fileContents[f.file] : null;
+    buckets[fixBucketOf(f, src)].push(f);
+  }
+
+  const declinedByFamily = {};
+  for (const f of buckets.declined) {
+    const fam = f.family || '(none)';
+    const key = Object.keys(DECLINED_TO_FIX).find(k => fam === k || fam.startsWith(`${k}-`)) || fam;
+    if (!declinedByFamily[key]) declinedByFamily[key] = { n: 0, reason: DECLINED_TO_FIX[key] || 'declined' };
+    declinedByFamily[key].n += 1;
+  }
+
+  return {
+    total: d,
+    deterministic: { n: buckets.deterministic.length, d },
+    model: { n: buckets.model.length, d },
+    declined: { n: buckets.declined.length, d, byFamily: declinedByFamily },
+    deterministicChecked: !!fileContents,
+    meaning: 'deterministic = a context-independent patch exists; model = attemptable by a model, NOT known to succeed; declined = synthesis refuses with a stated reason.',
+  };
+}
+
+/** Markdown for the scorecard. Denominators always attached. */
+export function renderFixCoverage(cov) {
+  if (!cov || !cov.total) return '_No findings to report fix coverage over._\n';
+  const pct = (n) => `${n}/${cov.total} (${Math.round((n / cov.total) * 100)}%)`;
+  const lines = [
+    '| Bucket | Share | Meaning |',
+    '|---|---|---|',
+    `| Deterministic patch | ${pct(cov.deterministic.n)} | context-independent literal swap |`,
+    `| Model-attemptable | ${pct(cov.model.n)} | can be attempted; success not claimed here |`,
+    `| Declined | ${pct(cov.declined.n)} | synthesis refuses — reasons below |`,
+    '',
+  ];
+  if (!cov.deterministicChecked) {
+    lines.push('_Source was not supplied, so the deterministic check could not run: the'
+      + ' deterministic share is a LOWER bound and those findings are counted as'
+      + ' model-attemptable._', '');
+  }
+  const entries = Object.entries(cov.declined.byFamily).sort((a, b) => b[1].n - a[1].n);
+  if (entries.length) {
+    lines.push('**Why each family is declined**', '');
+    for (const [fam, { n, reason }] of entries) lines.push(`- \`${fam}\` (${n}): ${reason}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}