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

package/src/posture/fix-metrics.js

@@ -195,3 +195,79 @@ export function renderFixDurationSummary(sum) {
 }
 
 export const _internals = { _dist, _pct, RELIABLE_N };
+
+
+// ── PRD F6.1 — score fixes on THREE AXES, not one ──────────────────────────
+//
+// The three axes the PRD names:
+//   (a) does the finding disappear      — the rescan leg
+//   (b) does the project's own suite pass — the tests leg
+//   (c) does an independent verifier agree — the PoC re-check leg
+//
+// All three were already computed by verifyFixCore and then collapsed into one
+// boolean, which is the problem: **(a) alone is satisfiable by deleting code.**
+// A patch that removes the vulnerable function passes the rescan, has nothing
+// left to fail, and — on a project with no detectable test suite — reaches
+// ok:true having proven only that the detector went quiet.
+//
+// Reporting the axes separately makes that visible. `aOnly` is the number that
+// matters most and the one nobody was publishing: attempts that satisfied ONLY
+// the disappearance axis. A high aOnly with a high headline is the shape of a
+// remediation feature that is deleting code and calling it a fix.
+export function summarizeFixAxes(attempts) {
+  const list = Array.isArray(attempts) ? attempts.filter(Boolean) : [];
+  const d = list.length;
+
+  const rate = (pred) => ({ n: list.filter(pred).length, d });
+
+  // Each axis is judged INDEPENDENTLY of the overall verdict, so a leg that
+  // passed inside a failed attempt still counts for its own axis. Reading them
+  // off `ok` would make the three axes three copies of the same number.
+  const findingDisappeared = rate((a) => a.rescanOk === true || (a.ok === true && a.rescanOk !== false));
+  const testsStillPass = rate((a) => a.testsRan === true && a.testsOk !== false);
+  const verifierAgrees = rate((a) => a.pocOk === true);
+
+  const satisfiesAll = rate((a) =>
+    (a.rescanOk === true || (a.ok === true && a.rescanOk !== false))
+    && a.testsRan === true && a.testsOk !== false
+    && a.pocOk === true);
+
+  // The honesty number: disappearance WITHOUT either corroborating axis.
+  const aOnly = rate((a) => {
+    const disappeared = a.rescanOk === true || (a.ok === true && a.rescanOk !== false);
+    const corroborated = (a.testsRan === true && a.testsOk !== false) || a.pocOk === true;
+    return disappeared && !corroborated;
+  });
+
+  return {
+    total: d,
+    findingDisappeared,
+    testsStillPass,
+    verifierAgrees,
+    satisfiesAll,
+    aOnly,
+    meaning:
+      'findingDisappeared = the detector went quiet; testsStillPass = the project suite ran AND passed; '
+      + 'verifierAgrees = an independent PoC re-check confirmed the hole is shut. '
+      + 'aOnly counts attempts that satisfied ONLY disappearance — the shape a code-deleting "fix" produces.',
+    caveat: d === 0
+      ? 'no attempts recorded; every rate is 0/0 and means nothing'
+      : 'rates carry {n,d}; a small d is indicative, not settled',
+  };
+}
+
+/** Markdown for a report. Denominators always attached. */
+export function renderFixAxes(sum) {
+  if (!sum || !sum.total) return '_No fix attempts recorded._\n';
+  const row = (label, r, note) => `| ${label} | ${r.n}/${r.d} | ${note} |`;
+  return [
+    '| Axis | Rate | Meaning |',
+    '|---|---|---|',
+    row('(a) finding disappeared', sum.findingDisappeared, 'the detector went quiet'),
+    row('(b) project tests pass', sum.testsStillPass, 'the suite RAN and passed'),
+    row('(c) verifier agrees', sum.verifierAgrees, 'an independent PoC re-check confirmed it'),
+    row('all three', sum.satisfiesAll, 'the only row that means "fixed"'),
+    row('(a) ALONE', sum.aOnly, 'satisfiable by deleting code — watch this number'),
+    '',
+  ].join('\n');
+}

package/src/posture/mcp-rug-pull.js

@@ -0,0 +1,144 @@
+// PRD F5.2 — rug-pull detection for MCP tool definitions.
+//
+// THE ATTACK
+// ----------
+// A user approves an MCP server by reading what its tools claim to do. The
+// agent then loads those tool DESCRIPTIONS into its context on every session,
+// and acts on them. If a description changes after approval — new instructions
+// appended, the schema widened to accept a path it never took, the stated
+// purpose rewritten — the agent obeys the new text while the human still
+// believes they approved the old one.
+//
+// Nothing in mcp-audit.js could see this. Every rule there judges a definition
+// on its CURRENT content, so a description that is innocuous today and hostile
+// tomorrow passes both times. Rug-pull is a property of the CHANGE, not of any
+// single snapshot, which is why it needs its own mechanism.
+//
+// WHAT IS AND IS NOT A RUG-PULL
+// -----------------------------
+// A NEW tool is not a rug-pull — nobody approved it yet, and mcp-audit judges it
+// on content like any other. A REMOVED tool is not a rug-pull either; it can no
+// longer instruct anything. The finding is specifically: this exact tool name
+// was seen before, and what it says has changed since.
+//
+// The FIRST run records and reports nothing. There is no prior state to compare
+// against, and inventing a finding on first sight would make every new project
+// noisy while teaching people to ignore the rule that matters.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { statePath, stateWritesEnabled, isSafeStateDir } from './state-dir.js';
+
+const BASELINE_FILE = 'mcp-tool-baseline.json';
+
+/**
+ * Fingerprint the parts of a tool definition an agent actually ACTS on.
+ *
+ * Description and input schema, not the name — the name is the identity being
+ * tracked, so folding it in would make every tool its own fingerprint and the
+ * comparison vacuous. Ordering inside the schema is normalised so a formatting
+ * change is not reported as a behavioural one; a reader chasing a false
+ * rug-pull alert stops reading them.
+ */
+export function fingerprintTool(tool) {
+  const payload = JSON.stringify({
+    description: String((tool && tool.description) || ''),
+    inputSchema: _canonical((tool && (tool.inputSchema || tool.input_schema)) || null),
+  });
+  return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 32);
+}
+
+function _canonical(v) {
+  if (Array.isArray(v)) return v.map(_canonical);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = _canonical(v[k]);
+    return out;
+  }
+  return v;
+}
+
+/** { serverName: { toolName: fingerprint } } from an MCP config object. */
+export function fingerprintConfig(config) {
+  const out = {};
+  const servers = (config && (config.mcpServers || config.servers)) || {};
+  for (const [server, def] of Object.entries(servers)) {
+    const tools = (def && def.tools) || [];
+    if (!Array.isArray(tools) || !tools.length) continue;
+    out[server] = {};
+    for (const t of tools) {
+      if (t && t.name) out[server][t.name] = fingerprintTool(t);
+    }
+  }
+  return out;
+}
+
+export function loadBaseline(scanRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(statePath(scanRoot, BASELINE_FILE), 'utf8'));
+  } catch { return null; }
+}
+
+export function saveBaseline(scanRoot, fingerprints) {
+  // Same discipline as every other state writer here: decline rather than
+  // create a stray state dir outside a real project.
+  if (!stateWritesEnabled() || !isSafeStateDir(path.dirname(statePath(scanRoot, BASELINE_FILE)))) return false;
+  try {
+    fs.mkdirSync(path.dirname(statePath(scanRoot, BASELINE_FILE)), { recursive: true });
+    fs.writeFileSync(statePath(scanRoot, BASELINE_FILE),
+      JSON.stringify({ schema: 'mcp-tool-baseline/v1', recordedAt: new Date().toISOString(), fingerprints }, null, 1));
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Compare current tool definitions against the recorded baseline.
+ *
+ * Returns { findings, firstRun, changed, added, removed }. `findings` is empty
+ * on a first run by design.
+ */
+export function detectRugPull(scanRoot, config, { file = '.mcp.json' } = {}) {
+  const current = fingerprintConfig(config);
+  const prior = loadBaseline(scanRoot);
+  const findings = [];
+  const changed = [], added = [], removed = [];
+
+  if (!prior || !prior.fingerprints) {
+    return { findings, firstRun: true, changed, added, removed, current };
+  }
+
+  for (const [server, tools] of Object.entries(current)) {
+    const before = prior.fingerprints[server] || {};
+    for (const [name, fp] of Object.entries(tools)) {
+      if (!(name in before)) { added.push(`${server}/${name}`); continue; }
+      if (before[name] === fp) continue;
+      changed.push(`${server}/${name}`);
+      findings.push({
+        id: `mcp-rug-pull:${file}:${server}:${name}`,
+        file,
+        line: 1,
+        vuln: `MCP: tool "${name}" definition CHANGED after approval (rug-pull)`,
+        severity: 'high',
+        cwe: 'CWE-494',
+        family: 'mcp-rug-pull',
+        parser: 'MCP-RUGPULL',
+        confidence: 0.9,
+        description:
+          `The tool "${name}" on server "${server}" was approved with one definition and now has another. `
+          + 'An agent loads tool descriptions into its context and acts on them, so a changed description is a '
+          + 'changed instruction — the human still believes they approved the previous text. This is the '
+          + 'documented rug-pull shape: benign at review time, hostile afterwards.',
+        remediation:
+          `Re-review "${name}" against what it claimed when approved. If the change is legitimate, refresh the `
+          + `baseline at .agentic-security/${BASELINE_FILE}; if it is not, remove the server before the next agent run.`,
+      });
+    }
+  }
+  for (const [server, tools] of Object.entries(prior.fingerprints)) {
+    for (const name of Object.keys(tools)) {
+      if (!current[server] || !(name in current[server])) removed.push(`${server}/${name}`);
+    }
+  }
+
+  return { findings, firstRun: false, changed, added, removed, current };
+}

package/src/posture/poc-inprocess.js

@@ -38,12 +38,14 @@ const MARKER = 'PROVEN';
 // PoC observes the acceptance and records it. Both are execution-based — code
 // ran and behaved insecurely — but they are proven by different evidence, and
 // conflating them is how a template ends up asserting something it never saw.
-const SUPPORTED = new Set([
+export const SUPPORTED = new Set([
   'command-injection',
   'code-injection',
   'webhook-missing-signature-verification',
   'sql-injection',
   'path-traversal',
+  'ldap-injection',
+  'xxe',
 ]);
 
 // Classes proven by observing the HANDLER's behaviour rather than a payload
@@ -53,6 +55,8 @@ const BEHAVIOURAL = new Map([
   ['webhook-missing-signature-verification', (f, c) => _webhookPoc(f, c)],
   ['sql-injection', (f, c) => _sqlInjectionPoc(f, c)],
   ['path-traversal', (f, c) => _pathTraversalPoc(f, c)],
+  ['ldap-injection', (f, c) => _ldapInjectionPoc(f, c)],
+  ['xxe', (f, c) => _xxePoc(f, c)],
 ]);
 
 // Classes deliberately NOT here, with the reason, so the gap is a decision
@@ -491,6 +495,218 @@ function _sqlInjectionPoc(finding, fileContent) {
 const TRAVERSAL_SENTINEL = 'PROVEN_TRAVERSAL_SENTINEL_CONTENT';
 const READ_SINK = /\b(?:readFile|readFileSync|sendFile|readFileAsync)\s*\(/;
 
+
+// ── LDAP injection (CWE-90) ────────────────────────────────────────────────
+//
+// Added because `ldap-injection` was the largest UNCLASSIFIED family in the
+// published proof-coverage breakdown (10 of 280 corpus findings) and it has the
+// same property that makes SQL provable: a decidable boundary where the
+// question is settled without a running directory server.
+//
+// For SQL the question is "did the payload arrive as query TEXT or as a bound
+// parameter". For LDAP it is "did the payload's filter METACHARACTERS survive".
+// A correctly escaped value still contains the sentinel — `ldap_escape`,
+// `EqualityFilter` and friends escape `(`, `)`, `*` and `\` to `\28`, `\29`,
+// `\2a`, `\5c` — so matching the sentinel alone would call a FIXED handler
+// vulnerable. The proof requires the sentinel AND an unescaped metacharacter in
+// the same filter string.
+const LDAP_SENTINEL = 'PROVEN_LDAPI';
+// RELATIVE, like SQL_LOG. An absolute path (/tmp/...) is denied by the
+// confinement backend, so the recorder silently wrote nothing and the proof
+// came back proof-failed on a genuinely vulnerable handler — the sandbox
+// working exactly as intended, and a reminder that a PoC must live entirely
+// inside the sandbox root.
+const LDAP_LOG = 'ldap-calls.jsonl';
+const LDAP_DRIVERS = ['ldapjs', 'ldap-authentication', 'activedirectory', 'activedirectory2', 'ldapts'];
+const LDAP_DRIVER_RES = LDAP_DRIVERS.map((d) => [
+  d, new RegExp(`require\\(\\s*['"\`]${d}['"\`]|from\\s*['"\`]${d}['"\`]`),
+]);
+
+const LDAP_STUB = [
+  "const fs = require('fs');",
+  'function record(args) {',
+  '  const filters = [];',
+  '  for (const a of args) {',
+  "    if (typeof a === 'string') filters.push(a);",
+  "    else if (a && typeof a === 'object') {",
+  "      if (typeof a.filter === 'string') filters.push(a.filter);",
+  "      if (a.filter && typeof a.filter === 'object' && typeof a.filter.toString === 'function') filters.push(String(a.filter));",
+  '    }',
+  '  }',
+  '  if (filters.length) {',
+  `    try { fs.appendFileSync(${JSON.stringify(LDAP_LOG)}, JSON.stringify({ filters }) + '\\n'); } catch {}`,
+  '  }',
+  '}',
+  'const mk = () => new Proxy(function () {}, {',
+  "  get(t, p) { if (typeof p === 'symbol' || p === 'then' || p === 'inspect') return undefined; return mk(); },",
+  '  apply(t, self, args) {',
+  '    record(args);',
+  "    for (const a of args) if (typeof a === 'function') { try { a(null, { on: () => {} }); } catch {} }",
+  '    return mk();',
+  '  },',
+  '});',
+  'module.exports = mk();',
+].join('\n');
+
+function _ldapInjectionPoc(finding, fileContent) {
+  const driver = (LDAP_DRIVER_RES.find(([, re]) => re.test(fileContent)) || [])[0];
+  if (!driver) {
+    return {
+      ok: false,
+      reason: `no recognised LDAP client is required by this file, so there is no boundary to observe the filter at (looked for: ${LDAP_DRIVERS.join(', ')})`,
+    };
+  }
+  const found = _findHandler(fileContent);
+  if (!found) return NO_HANDLER;
+  const { call, reqIdent } = found;
+
+  const src = _requestSource(fileContent, reqIdent, finding.line);
+  if (!src) {
+    return { ok: false, reason: `the handler does not read query/body/params off '${reqIdent}', so the injection point is unknown` };
+  }
+
+  const { base, importLine, invoke, handlerLabel } = _binding(finding, call);
+  // Filter metacharacters plus the sentinel. An escaping handler keeps the
+  // sentinel and neutralises the parens/star, which is exactly the difference
+  // the decision below reads.
+  const payload = `*)(uid=*))(|(uid=*${LDAP_SENTINEL}`;
+  // The distinctive raw tail of that payload. Present verbatim only if no
+  // escaping happened between the request and the client.
+  const RAW_TAIL = `)(|(uid=*${LDAP_SENTINEL}`;
+
+  const code = [
+    `// Auto-generated proof for ${finding.file}.`,
+    `// Stubs the '${driver}' client with a recorder and calls the handler with a`,
+    '// payload carrying LDAP filter metacharacters. The marker is written only if',
+    '// those metacharacters reached the filter UNESCAPED — an escaped value still',
+    '// carries the sentinel, so the sentinel alone proves nothing.',
+    importLine,
+    "import fs from 'node:fs';",
+    'await new Promise((resolve) => {',
+    '  let timer = null;',
+    '  const done = () => { clearTimeout(timer); resolve(); };',
+    '  const res = {',
+    '    send: done, json: done, end: done,',
+    '    status: () => ({ send: done, json: done, end: done }),',
+    '  };',
+    `  const req = { ${src.prop}: ${JSON.stringify({ [src.key]: payload })} };`,
+    '  timer = setTimeout(resolve, 3000);',
+    `  try { ${invoke}(req, res); } catch { done(); }`,
+    '});',
+    '',
+    '// The whole decision, stated once: did the PAYLOAD\'s OWN metacharacters',
+    '// survive verbatim? Looking for any raw paren near the sentinel does not',
+    '// work — the application\'s filter template (\'(uid=\' + v + \')\') always',
+    '// contributes raw parens of its own, so that test called an ESCAPING',
+    '// handler vulnerable. Escaping rewrites the payload tail to \\2a\\29\\28…,',
+    '// so its verbatim presence is the bug and its absence is the fix working.',
+    'let proven = false;',
+    'try {',
+    `  for (const line of fs.readFileSync(${JSON.stringify(LDAP_LOG)}, 'utf8').split('\\n')) {`,
+    '    if (!line.trim()) continue;',
+    '    const rec = JSON.parse(line);',
+    `    for (const f of rec.filters) if (f.includes(${JSON.stringify(RAW_TAIL)})) proven = true;`,
+    '  }',
+    '} catch {}',
+    `if (proven) fs.writeFileSync('${MARKER}', 'x');`,
+  ].join('\n');
+
+  return {
+    ok: true,
+    poc: {
+      lang: 'js', kind: 'in-process', family: finding.family, cwe: finding.cwe || null,
+      marker: MARKER, paramKey: src.key, paramSource: src.prop, handler: handlerLabel,
+      driver,
+      observes: 'the request payload reached the LDAP client with its filter metacharacters unescaped',
+      requires: [base],
+      extraFiles: { [`node_modules/${driver}/index.js`]: LDAP_STUB },
+      code,
+    },
+  };
+}
+
+
+// ── XXE (CWE-611) ──────────────────────────────────────────────────────────
+//
+// The third-largest unclassified family in the published proof-coverage
+// breakdown. It is provable in-process for a reason the SSRF class is NOT: the
+// external entity can point at a LOCAL file the harness plants inside the
+// sandbox, so the proof needs no network and a failed fetch can never be
+// confinement talking.
+//
+// The decision is whether the parser RESOLVED the entity. The sentinel content
+// lives only in a file the XML never contains, so its presence in the parsed
+// output means the parser went and read it — which is the vulnerability. A
+// parser with entity expansion off returns the entity unexpanded (or throws),
+// and neither writes the marker.
+const XXE_SENTINEL = 'PROVEN_XXE_ENTITY_RESOLVED';
+const XXE_SENTINEL_FILE = 'xxe-sentinel.txt';
+const XXE_PARSERS = ['libxmljs', 'libxmljs2', '@xmldom/xmldom', 'xmldom', 'node-expat'];
+const XXE_PARSER_RES = XXE_PARSERS.map((d) => [
+  d, new RegExp(`require\\(\\s*['"\`]${d.replace('/', '\\/')}['"\`]|from\\s*['"\`]${d.replace('/', '\\/')}['"\`]`),
+]);
+
+function _xxePoc(finding, fileContent) {
+  const parser = (XXE_PARSER_RES.find(([, re]) => re.test(fileContent)) || [])[0];
+  if (!parser) {
+    return {
+      ok: false,
+      reason: `no recognised XML parser is required by this file, so there is nothing to observe entity resolution at (looked for: ${XXE_PARSERS.join(', ')})`,
+    };
+  }
+  const found = _findHandler(fileContent);
+  if (!found) return NO_HANDLER;
+  const { call, reqIdent } = found;
+
+  const src = _requestSource(fileContent, reqIdent, finding.line);
+  if (!src) {
+    return { ok: false, reason: `the handler does not read query/body/params off '${reqIdent}', so the XML entry point is unknown` };
+  }
+
+  const { base, importLine, invoke, handlerLabel } = _binding(finding, call);
+  const xml = `<?xml version="1.0"?><!DOCTYPE r [<!ENTITY x SYSTEM "file://./${XXE_SENTINEL_FILE}">]><r>&x;</r>`;
+
+  const code = [
+    `// Auto-generated proof for ${finding.file}.`,
+    '// Plants a sentinel file, hands the handler XML whose external entity points',
+    '// at it, and writes the marker only if the SENTINEL CONTENT comes back —',
+    '// which can only happen if the parser resolved the entity and read the file.',
+    '// A parser with entity expansion disabled returns it unexpanded or throws.',
+    importLine,
+    "import fs from 'node:fs';",
+    `fs.writeFileSync(${JSON.stringify(XXE_SENTINEL_FILE)}, ${JSON.stringify(XXE_SENTINEL)});`,
+    'let seen = "";',
+    'await new Promise((resolve) => {',
+    '  let timer = null;',
+    '  const capture = (v) => { try { seen += typeof v === "string" ? v : JSON.stringify(v); } catch {} clearTimeout(timer); resolve(); };',
+    '  const res = {',
+    '    send: capture, json: capture, end: capture,',
+    '    status: () => ({ send: capture, json: capture, end: capture }),',
+    '  };',
+    `  const req = { ${src.prop}: ${JSON.stringify({ [src.key]: xml })} };`,
+    '  timer = setTimeout(resolve, 3000);',
+    `  try { const r = ${invoke}(req, res); if (r && typeof r.then === "function") r.then(capture, () => resolve()); } catch { resolve(); }`,
+    '});',
+    '',
+    '// The whole decision, stated once: the sentinel STRING is only reachable by',
+    '// reading the planted file. Matching the entity name or the XML itself would',
+    '// be satisfied by a parser that never expanded anything.',
+    `if (seen.includes(${JSON.stringify(XXE_SENTINEL)})) fs.writeFileSync('${MARKER}', 'x');`,
+  ].join('\n');
+
+  return {
+    ok: true,
+    poc: {
+      lang: 'js', kind: 'in-process', family: finding.family, cwe: finding.cwe || null,
+      marker: MARKER, paramKey: src.key, paramSource: src.prop, handler: handlerLabel,
+      driver: parser,
+      observes: 'the XML parser resolved an external entity and returned the contents of a local file',
+      requires: [base],
+      code,
+    },
+  };
+}
+
 function _pathTraversalPoc(finding, fileContent) {
   const found = _findHandler(fileContent);
   if (!found) return NO_HANDLER;

package/src/posture/proof-coverage.js

@@ -0,0 +1,162 @@
+// PRD F7.2 — publish what CANNOT be proven, and how much of the finding set that is.
+//
+// The PoC generator declines whole vulnerability classes it cannot honestly
+// prove. Those reasons were documented in poc-inprocess.js's header and nowhere
+// else, so the only number a reader ever saw was the proof RATE — computed over
+// the findings that happened to be provable. A high rate on a small provable
+// subset reads as strength and is nearly meaningless.
+//
+// Publishing which classes are structurally unprovable, and what share of real
+// findings they represent, is more credible than a high proof rate. It is also
+// the harder number to publish, which is rather the point.
+//
+// THE THREE BUCKETS, and why "unclassified" is separate from "indeterminate":
+//
+//   provable       — a proof class exists and a PoC can be attempted.
+//   indeterminate  — the class is DECLINED ON PURPOSE, with a stated reason.
+//                    Not a gap in effort; a limit of what a single-shot harness
+//                    can honestly assert.
+//   unclassified   — no proof class covers it and no decision has been recorded.
+//                    This is the genuine backlog, and it is kept apart so it can
+//                    never hide inside the principled exclusions.
+//   out-of-scope   — the in-process harness is JAVASCRIPT-ONLY. A Python, Java,
+//                    C#, PHP, Kotlin, Go or Ruby finding cannot be proven by it
+//                    at any effort, so it is not backlog — it is the CEILING.
+//
+// That fourth bucket is the "stated ceiling" Feature 7's exit gate asks for, and
+// omitting it made the headline number mean two different things at once.
+// Measured on the CVE corpus: 280 findings, of which only 76 are JS/TS. Proof
+// coverage is 26% of ALL findings and 96% of the ones the harness can reach.
+// Reporting the first alone understates the harness; reporting the second alone
+// overstates the product. Both are published, with the denominator on each.
+//
+// Folding `unclassified` into `indeterminate` would let "we haven't looked at
+// this" borrow the credibility of "we looked and it can't be done".
+import { SUPPORTED } from './poc-inprocess.js';
+
+// Declined on purpose. Reasons are the ones recorded in poc-inprocess.js — kept
+// as DATA here so a report can print them, rather than living only in a comment
+// nobody downstream can read.
+export const INDETERMINATE_BY_CLASS = Object.freeze({
+  'idor': 'proving it means showing user A read user B\'s record, which needs two authenticated identities and a populated data store. A single-shot harness would invent both, and a PoC built on invented state proves something about the invention.',
+  'broken-access-control': 'same as idor — requires two identities and real state.',
+  'broken-authz': 'same as idor — requires two identities and real state.',
+  'ssrf': 'the proof is that the server fetched an attacker-named host. The sandbox denies egress by design, so a failed fetch is confinement talking, not the finding.',
+  'xss': 'needs a browser to say whether the payload executed; a marker file cannot observe a DOM.',
+  'mutation-xss': 'needs a DOM and a parser round-trip — same limit as xss.',
+  'open-redirect': 'the effect is a Location header a browser would follow; nothing in a marker-file harness observes the follow.',
+});
+
+// The in-process harness only ever loads JavaScript (see poc-inprocess.js's
+// JS_EXT and its "ES-module source" refusal). Anything else is unreachable by
+// construction.
+const HARNESS_LANGS = /\.(?:js|cjs|mjs|jsx|ts|tsx)$/i;
+
+// Internal: `bucketOf` is the public surface for this question. Not exported —
+// the dead-export guard is right that a second entry point with no caller is
+// just surface area.
+function outOfHarnessScope(finding) {
+  const file = finding && typeof finding.file === 'string' ? finding.file : '';
+  if (!file) return false;              // unknown file — do not claim a ceiling
+  return !HARNESS_LANGS.test(file);
+}
+
+/** Bucket a finding: 'provable' | 'indeterminate' | 'unclassified' | 'out-of-scope'. */
+export function bucketOf(finding) {
+  // Language first: a Python SQL-injection finding is not "provable", however
+  // good the SQL proof class is. Ordering this after the class check would
+  // report a ceiling case as a capability.
+  if (outOfHarnessScope(finding)) return 'out-of-scope';
+  const fam = finding && typeof finding.family === 'string' ? finding.family : '';
+  if (!fam) return 'unclassified';
+  // Families are emitted as `<base>-<rule-slug>` in places, so match the base
+  // too — the same resolution problem the compliance evaluator hit.
+  const base = fam.split('-').slice(0, 2).join('-');
+  for (const key of SUPPORTED) {
+    if (fam === key || fam.startsWith(`${key}-`)) return 'provable';
+  }
+  for (const key of Object.keys(INDETERMINATE_BY_CLASS)) {
+    if (fam === key || fam.startsWith(`${key}-`) || base === key) return 'indeterminate';
+  }
+  return 'unclassified';
+}
+
+/**
+ * Proof coverage over a finding set.
+ *
+ * Every share carries {n, d} — a percentage without its denominator is exactly
+ * the shape of claim this module exists to replace.
+ */
+export function proofCoverage(findings) {
+  const list = Array.isArray(findings) ? findings.filter(Boolean) : [];
+  const d = list.length;
+  const buckets = { provable: [], indeterminate: [], unclassified: [], 'out-of-scope': [] };
+  for (const f of list) buckets[bucketOf(f)].push(f);
+
+  const byClass = {};
+  for (const f of buckets.indeterminate) {
+    const fam = f.family || '(none)';
+    const key = Object.keys(INDETERMINATE_BY_CLASS)
+      .find(k => fam === k || fam.startsWith(`${k}-`) || fam.split('-').slice(0, 2).join('-') === k) || fam;
+    if (!byClass[key]) byClass[key] = { n: 0, reason: INDETERMINATE_BY_CLASS[key] || 'declined' };
+    byClass[key].n += 1;
+  }
+
+  const unclassifiedFamilies = {};
+  for (const f of buckets.unclassified) {
+    const fam = f.family || '(no family)';
+    unclassifiedFamilies[fam] = (unclassifiedFamilies[fam] || 0) + 1;
+  }
+
+  const reachable = d - buckets['out-of-scope'].length;
+  const outLangs = {};
+  for (const f of buckets['out-of-scope']) {
+    const ext = (String(f.file || '').match(/\.[a-z0-9]+$/i) || ['(none)'])[0].toLowerCase();
+    outLangs[ext] = (outLangs[ext] || 0) + 1;
+  }
+
+  return {
+    total: d,
+    // Reported BOTH ways on purpose. `provable.d` is every finding; `ofReachable`
+    // is the share of what the harness can actually load. Publishing only one of
+    // them is how a number ends up meaning whatever the reader assumes.
+    provable: { n: buckets.provable.length, d, ofReachable: { n: buckets.provable.length, d: reachable } },
+    ceiling: {
+      reachable: { n: reachable, d },
+      outOfScope: { n: buckets['out-of-scope'].length, d, byExtension: outLangs },
+      reason: 'the in-process proof harness only loads JavaScript; findings in other languages cannot be execution-proven by it at any effort',
+    },
+    indeterminate: { n: buckets.indeterminate.length, d, byClass },
+    unclassified: { n: buckets.unclassified.length, d, families: unclassifiedFamilies },
+    provableClasses: [...SUPPORTED],
+    meaning: 'provable = a proof class exists; indeterminate = declined on purpose with a stated reason; unclassified = no proof class and no decision yet (the real backlog); out-of-scope = a language the JS-only harness cannot load at all (the ceiling, not backlog).',
+  };
+}
+
+/** Markdown for the scorecard. Every rate keeps its denominator. */
+export function renderProofCoverage(cov) {
+  if (!cov || !cov.total) return '_No findings to report proof coverage over._\n';
+  const pct = (n) => `${n}/${cov.total} (${Math.round((n / cov.total) * 100)}%)`;
+  const lines = [
+    '| Bucket | Share | Meaning |',
+    '|---|---|---|',
+    `| Provable | ${pct(cov.provable.n)} | a proof class exists and a PoC can be attempted |`,
+    `| Indeterminate by class | ${pct(cov.indeterminate.n)} | declined on purpose — see reasons below |`,
+    `| Unclassified | ${pct(cov.unclassified.n)} | no proof class yet; the real backlog |`,
+    `| Out of harness scope | ${pct(cov.ceiling.outOfScope.n)} | not JavaScript — the harness cannot load it at all |`,
+    '',
+    // Stated every time, because the two readings of "provable" differ by a lot
+    // and a reader who sees only the first will draw the wrong conclusion.
+    `**Ceiling.** ${cov.ceiling.reason}. Of ${cov.total} findings, ${cov.ceiling.reachable.n} are reachable by the harness; `
+    + `proof coverage is ${cov.provable.n}/${cov.total} of ALL findings and `
+    + `${cov.provable.ofReachable.n}/${cov.provable.ofReachable.d} of the reachable ones.`,
+    '',
+  ];
+  const entries = Object.entries(cov.indeterminate.byClass).sort((a, b) => b[1].n - a[1].n);
+  if (entries.length) {
+    lines.push('**Why each class is declined**', '');
+    for (const [cls, { n, reason }] of entries) lines.push(`- \`${cls}\` (${n}): ${reason}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}