@portll/cobolwork 0.2.75 → 0.2.117

package/lib/evidence/store.mjs

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The evidence directory on disk: where it may be, how its files are opened (never through a
+// symbolic link, owner-only), the ledger lock, and reading a chain file back line by line.
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, statSync, unlinkSync, writeSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+
+const { O_WRONLY, O_CREAT, O_EXCL, O_APPEND, O_NOFOLLOW } = constants;
+
+export class EvidenceRefusal extends Error {
+  constructor(message) { super(message); this.code = 'EEVIDENCE'; }
+}
+
+const isLink = (p) => { try { return lstatSync(p).isSymbolicLink(); } catch { return false; } };
+
+// The directory named by --evidence or COBOLWORK_EVIDENCE, or null when neither is set.
+export function evidenceDirFrom(opts, env = process.env) {
+  const named = opts.evidence || env.COBOLWORK_EVIDENCE || null;
+  return named ? resolve(named) : null;
+}
+
+// Creates the directory (0700) and its runs/ and seals/, and refuses a link anywhere on that
+// path or a directory inside a tree this run reads.
+export function prepareDir(dir, roots = []) {
+  // Checked before anything is created: a refused run leaves nothing inside the tree.
+  let existing = resolve(dir);
+  const rest = [];
+  while (!existsSync(existing)) {
+    rest.unshift(basename(existing));
+    const up = dirname(existing);
+    if (up === existing) break;
+    existing = up;
+  }
+  const intended = join(realpathSync(existing), ...rest);
+  for (const root of roots) {
+    let r;
+    try { r = realpathSync(root); } catch { continue; }
+    if (intended === r || intended.startsWith(r.endsWith(sep) ? r : r + sep)) {
+      throw new EvidenceRefusal(`the evidence directory ${dir} is inside ${root}, which this run reads; a tree under review must not supply its own evidence`);
+    }
+  }
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  for (const p of [dir, join(dir, 'runs'), join(dir, 'seals')]) {
+    if (isLink(p)) throw new EvidenceRefusal(`${p} is a symbolic link, which evidence is not written through`);
+    if (!existsSync(p)) mkdirSync(p, { mode: 0o700 });
+    else if (!statSync(p).isDirectory()) throw new EvidenceRefusal(`${p} is not a directory`);
+  }
+  return realpathSync(dir);
+}
+
+// O_NOFOLLOW guards the last component only, so the two directories above an evidence file
+// (runs/ or seals/, and the evidence directory) are checked immediately before each open. Where
+// the platform has no O_NOFOLLOW (Windows), the file itself is checked the same way.
+function parentsNotLinked(path) {
+  const dir = dirname(path);
+  const inside = [dir, ...(/^(runs|seals)$/.test(basename(dir)) ? [dirname(dir)] : []), ...(O_NOFOLLOW ? [] : [path])];
+  for (const p of inside) {
+    if (isLink(p)) throw new EvidenceRefusal(`${p} is a symbolic link, which evidence is not written or read through`);
+  }
+}
+
+const refuseLink = (path, e) => {
+  if (e.code === 'ELOOP' || (e.code === 'EEXIST' && isLink(path))) throw new EvidenceRefusal(`${path} is a symbolic link, which evidence is not written or read through`);
+  throw e;
+};
+
+export function createExclusive(path) {
+  parentsNotLinked(path);
+  try { return openSync(path, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW, 0o600); } catch (e) { return refuseLink(path, e); }
+}
+
+export function openAppend(path) {
+  parentsNotLinked(path);
+  try { return openSync(path, O_WRONLY | O_APPEND | O_CREAT | O_NOFOLLOW, 0o600); } catch (e) { return refuseLink(path, e); }
+}
+
+function openRead(path) {
+  parentsNotLinked(path);
+  try { return openSync(path, constants.O_RDONLY | O_NOFOLLOW); } catch (e) { return refuseLink(path, e); }
+}
+
+// Everything the descriptor holds, sized from the descriptor, so the path is resolved once.
+function readAll(fd) {
+  const size = fstatSync(fd).size;
+  const buf = Buffer.alloc(size);
+  let off = 0;
+  while (off < size) {
+    const n = readSync(fd, buf, off, size - off, off);
+    if (n === 0) break;
+    off += n;
+  }
+  return buf.subarray(0, off);
+}
+
+export function writeAll(fd, text) {
+  const buf = Buffer.from(text, 'utf8');
+  let off = 0;
+  while (off < buf.length) off += writeSync(fd, buf, off, buf.length - off);
+}
+
+export function syncClose(fd) {
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+// Lines of a chain file, each without its newline, and whether the last one was cut short.
+export function readLines(path) {
+  const fd = openRead(path);
+  let text;
+  try { text = readAll(fd).toString('utf8'); } finally { closeSync(fd); }
+  if (!text) return { lines: [], torn: false };
+  const torn = !text.endsWith('\n');
+  const lines = text.split('\n');
+  if (!torn) lines.pop();
+  return { lines, torn };
+}
+
+// The last complete line of a chain file, read from its tail, or null for an empty file.
+export function lastLine(path) {
+  if (!existsSync(path)) return { line: null, torn: false };
+  const fd = openRead(path);
+  try {
+    const size = fstatSync(fd).size;
+    if (!size) return { line: null, torn: false };
+    let window = Math.min(size, 65536);
+    for (;;) {
+      const buf = Buffer.alloc(window);
+      const n = readSync(fd, buf, 0, window, size - window);
+      if (n !== window) throw new EvidenceRefusal(`${path} changed while it was read`);
+      const text = buf.toString('utf8');
+      const torn = !text.endsWith('\n');
+      const body = torn ? text : text.slice(0, -1);
+      const nl = body.lastIndexOf('\n');
+      if (nl >= 0 || window === size) return { line: nl >= 0 ? body.slice(nl + 1) : body, torn };
+      window = Math.min(size, window * 4);
+    }
+  } finally { closeSync(fd); }
+}
+
+const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } };
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+// Takes ledger.lock, breaking one that is older than staleMs and whose holder is gone. Returns
+// { release, broken } or null when the lock could not be had within waitMs.
+export function takeLock(path, { waitMs = 5000, staleMs = 60000, now = Date.now } = {}) {
+  const deadline = now() + waitMs;
+  let broken = null;
+  for (;;) {
+    try {
+      const fd = createExclusive(path);
+      writeAll(fd, `${process.pid} ${now()}\n`);
+      closeSync(fd);
+      return { release: () => { try { unlinkSync(path); } catch { /* already gone */ } }, broken };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+    }
+    let pid = null;
+    let since = null;
+    try {
+      const [p, t] = readFileSync(path, 'utf8').trim().split(/\s+/).map(Number);
+      pid = Number.isSafeInteger(p) ? p : null;
+      since = Number.isSafeInteger(t) ? t : null;
+    } catch { /* removed between the open and the read */ }
+    const age = since === null ? null : now() - since;
+    if (pid !== null && age !== null && age > staleMs && !pidAlive(pid)) {
+      try { unlinkSync(path); broken = { holderPid: pid, ageMs: Math.max(0, Math.trunc(age)) }; } catch { /* a peer broke it first */ }
+      continue;
+    }
+    if (now() >= deadline) return null;
+    sleep(25);
+  }
+}

package/lib/evidence/verify.mjs

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Verifies an evidence directory and reports verified, broken, unrecorded, open, anchored, sealed,
+// unsealedTail and signatures as separate facts. docs/spec/evidence.md §9.
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { JOURNAL_KINDS, LEDGER_KINDS, checkLine } from './record.mjs';
+import { readLines } from './store.mjs';
+import { LEDGER } from './journal.mjs';
+import { NAMESPACE, PAYLOAD_TYPE, SEAL_PREDICATE, STATEMENT_TYPE, listWitnessed, pae, readWitnessed, resolveRef, sealFiles } from './seal.mjs';
+import { verifySshsig } from './sshsig.mjs';
+
+const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+
+// Every line of one chain file checked against the one before it. After a break the walk goes on
+// from the record as read, so one edit is reported once and later breaks are still found.
+export function verifyChain(path, label, kinds = LEDGER_KINDS) {
+  const out = { records: [], broken: [], torn: false };
+  if (!existsSync(path)) return out;
+  const { lines, torn } = readLines(path);
+  out.torn = torn;
+  let prev = null;
+  let chain = null;
+  lines.forEach((line, i) => {
+    if (i === 0) {
+      try { chain = JSON.parse(line).chain; } catch { chain = null; }
+    }
+    const { record, fail } = checkLine(line, prev, { chain, kinds });
+    if (fail) out.broken.push({ file: label, line: i + 1, check: fail });
+    if (record) { out.records.push(record); prev = record; }
+  });
+  if (torn) out.broken.push({ file: label, line: lines.length, check: 'torn' });
+  return out;
+}
+
+function decodeSeal(text) {
+  const env = JSON.parse(text);
+  if (env.payloadType !== PAYLOAD_TYPE || typeof env.payload !== 'string' || !Array.isArray(env.signatures)) throw new Error('not a DSSE envelope of an in-toto statement');
+  const payload = Buffer.from(env.payload, 'base64');
+  const st = JSON.parse(payload.toString('utf8'));
+  if (st._type !== STATEMENT_TYPE || st.predicateType !== SEAL_PREDICATE) throw new Error('not a cobolwork seal statement');
+  const subject = st.subject && st.subject[0];
+  const m = subject && /^ledger:([0-9a-f]{32})$/.exec(subject.name || '');
+  if (!m || !subject.digest || !/^[0-9a-f]{64}$/.test(subject.digest.sha256 || '')) throw new Error('the seal names no ledger tip');
+  const length = st.predicate && st.predicate.ledgerLength;
+  if (!Number.isSafeInteger(length) || length < 1) throw new Error('the seal names no ledger length');
+  return { envelope: env, payload, chain: m[1], tip: subject.digest.sha256, length, previous: st.predicate.previousSeal ? st.predicate.previousSeal.sha256 : null };
+}
+
+// Whether the ledger holds the state a seal names: same chain, and the record at that length has
+// that hash.
+function agrees(seal, ledger) {
+  const rec = ledger[seal.length - 1];
+  if (!ledger.length || ledger[0].chain !== seal.chain) return { ok: false, why: `the seal names ledger ${seal.chain}, and this ledger is ${ledger.length ? ledger[0].chain : 'empty'}` };
+  if (!rec) return { ok: false, why: `the seal names ${seal.length} records and the ledger holds ${ledger.length}` };
+  if (rec.hash !== seal.tip) return { ok: false, why: `record ${seal.length} of the ledger is not the one sealed` };
+  return { ok: true };
+}
+
+function signaturesOf(seal, allowed) {
+  const message = pae(PAYLOAD_TYPE, seal.payload);
+  if (!seal.envelope.signatures.length) return [{ keyid: null, valid: null, reason: 'unsigned' }];
+  return seal.envelope.signatures.map((s) => {
+    if (!allowed) return { keyid: s.keyid || null, valid: null, reason: 'no allowed signers were given' };
+    let blob;
+    try { blob = Buffer.from(String(s.sig), 'base64'); } catch { return { keyid: s.keyid || null, valid: false, reason: 'the signature is not base64' }; }
+    return verifySshsig({ blob, message, namespace: NAMESPACE, allowed });
+  });
+}
+
+export function verifyEvidence(dir, { allowed = null, anchorGit = null, anchorRef = null, maxUnsealed = 0, env = process.env } = {}) {
+  const verdict = { verified: true, broken: [], unrecorded: [], open: [], anchored: null, sealed: null, sealedReason: null, unsealedTail: null, signatures: [], seals: [] };
+  const ledger = verifyChain(join(dir, LEDGER), LEDGER);
+  verdict.broken.push(...ledger.broken);
+  const recs = ledger.records;
+  if (recs.length && recs[0].kind !== 'genesis') verdict.broken.push({ file: LEDGER, line: 1, check: 'genesis' });
+
+  const named = new Set();
+  recs.forEach((rec, i) => {
+    if (rec.kind !== 'run') return;
+    named.add(rec.run);
+    const file = `runs/${rec.run}.jsonl`;
+    if (!/^[0-9TZ]+-[0-9a-f]{16}$/.test(rec.run) || !existsSync(join(dir, file))) { verdict.broken.push({ file: LEDGER, line: i + 1, check: 'run-missing' }); return; }
+    const run = verifyChain(join(dir, file), file, JOURNAL_KINDS);
+    verdict.broken.push(...run.broken);
+    const last = run.records[run.records.length - 1];
+    if (!run.records.length || run.records[0].kind !== 'open' || run.records[0].chain !== rec.runChain) verdict.broken.push({ file, line: 1, check: 'run-chain' });
+    else if (run.records.length !== rec.runLength || last.hash !== rec.runTip) verdict.broken.push({ file, line: run.records.length, check: 'run-tip' });
+  });
+
+  const runsDir = join(dir, 'runs');
+  for (const n of existsSync(runsDir) ? readdirSync(runsDir).sort() : []) {
+    const m = /^(.+)\.jsonl$/.exec(n);
+    if (!m) continue;
+    let records = [];
+    try { ({ records } = verifyChain(join(runsDir, n), `runs/${n}`, JOURNAL_KINDS)); } catch { /* reported below as unreadable only if named */ }
+    if (!named.has(m[1])) verdict.unrecorded.push(m[1]);
+    if (!records.some((r) => r.kind === 'close')) verdict.open.push(m[1]);
+  }
+
+  // The local seal chain: each seal names the digest of the one before it.
+  const local = [];
+  let prevDigest = null;
+  for (const f of sealFiles(dir)) {
+    const text = readFileSync(f.path, 'utf8');
+    let s;
+    try { s = decodeSeal(text); } catch (e) { verdict.broken.push({ file: `seals/${f.name}`, line: 1, check: 'seal', reason: e.message }); prevDigest = sha256(text); continue; }
+    if (s.previous !== prevDigest) verdict.broken.push({ file: `seals/${f.name}`, line: 1, check: 'seal-chain' });
+    prevDigest = sha256(text);
+    local.push({ ...s, seq: f.seq, name: f.name, text });
+  }
+  if (local.length) {
+    const newest = local[local.length - 1];
+    const a = agrees(newest, recs);
+    verdict.anchored = a.ok;
+    if (!a.ok) verdict.anchoredReason = a.why;
+  }
+  for (const s of local) {
+    const sigs = signaturesOf(s, allowed);
+    verdict.signatures.push({ seal: s.name, results: sigs });
+  }
+
+  if (anchorGit) {
+    const ref = anchorRef || '@{upstream}';
+    if (!resolveRef(anchorGit, ref, env)) {
+      verdict.sealedReason = `${ref} does not resolve in ${anchorGit}`;
+    } else {
+      // The witness is the authority: every seal it holds for this ledger is checked, whether or
+      // not the directory still has its copy, so deleting local seals cannot hide a cut tail.
+      const held = listWitnessed(anchorGit, ref, env);
+      const chain = recs.length ? recs[0].chain : null;
+      const seqs = chain ? held.get(chain) || [] : [];
+      const localSeqs = new Set(local.filter((s) => s.chain === chain).map((s) => s.seq));
+      let newestOk = null;
+      if (!seqs.length && held.size) {
+        verdict.sealed = false;
+        verdict.sealedReason = `the witness holds seals for ledger ${[...held.keys()].join(', ')}, and this directory holds ledger ${chain || 'none'}`;
+      } else if (!seqs.length) verdict.sealedReason = `not on ${ref}: the witness holds no seal for ledger ${chain || 'none'}`;
+      for (const seq of verdict.sealed === false ? [] : seqs) {
+        const name = `${seq}.dsse.json`;
+        const w = readWitnessed(anchorGit, ref, `${chain}/${name}`, env);
+        let ws;
+        try { ws = decodeSeal(w.text); } catch (e) { verdict.sealed = false; verdict.sealedReason = `the witnessed ${name} is not a seal: ${e.message}`; break; }
+        const a = agrees(ws, recs);
+        if (!a.ok) { verdict.sealed = false; verdict.sealedReason = `witnessed ${name}: ${a.why}`; break; }
+        const sigs = signaturesOf(ws, allowed);
+        const good = sigs.some((x) => x.valid === true);
+        const bad = sigs.every((x) => x.valid === false);
+        verdict.seals.push({ seal: name, witnessed: true, local: localSeqs.has(seq), length: ws.length, signed: good });
+        if (bad) { verdict.sealed = false; verdict.sealedReason = `witnessed ${name} carries no signature from an allowed signer`; break; }
+        if (good) newestOk = ws;
+      }
+      for (const s of local) if (s.chain === chain && !seqs.includes(s.seq)) verdict.seals.push({ seal: s.name, witnessed: false, reason: `not on ${ref}` });
+      if (verdict.sealed !== false) {
+        if (newestOk) {
+          verdict.sealed = true;
+          verdict.unsealedTail = recs.length - newestOk.length;
+        } else if (!verdict.sealedReason) verdict.sealedReason = allowed ? 'no witnessed seal carries a valid signature' : 'no allowed signers were given';
+      }
+    }
+  } else verdict.sealedReason = 'no witness was named';
+
+  verdict.verified = verdict.broken.length === 0;
+  verdict.exit = !verdict.verified || verdict.sealed === false ? 1
+    : verdict.sealed === true && verdict.unsealedTail <= maxUnsealed ? 0 : 3;
+  return verdict;
+}

package/lib/explain.mjs

@@ -6,6 +6,7 @@ import { parseFile, buildFileIndex, detectFormat } from './parser.mjs';
 import { EVIDENCE } from './kernel/findings.mjs';
 import { REGISTRY } from './kernel/registry.mjs';
 import { WHO_ACTS } from './tui/model.mjs';
+import { verificationPlan } from './verify.mjs';
 
 const HIDDEN_RULES = new Set(Object.keys(REGISTRY.find((s) => s.name === 'hidden').rules));
 
@@ -18,7 +19,8 @@ function codeArea(line, kind, format) {
 }
 
 const NOTE = 'This packet contains source text from the files it names. A cobolwork report never does: '
-  + 'treat the packet as you would the source, and do not store or send it where the source may not go.';
+  + 'treat the packet as you would the source, and do not store or send it where the source may not go. '
+  + 'Its verification plan is for a test region the estate owns and authorises the test in.';
 
 function contained(root, rel) {
   const base = resolve(root);
@@ -140,6 +142,7 @@ export function explainFinding(report, fingerprint, { root }) {
     guard: f.guard ? { ...f.guard, ...quote(f.guard.file, f.guard.line) } : null,
     related: (f.related || []).map((r) => ({ ...r, ...quote(r.path, r.line) })),
     declarations,
+    verify: verificationPlan(f),
     unread,
   };
 }

package/lib/exploitability.mjs

@@ -0,0 +1,263 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Whether an attacker can use a path finding, as a verdict that lists the facts it rests on and names
+// the fact it still lacks. It joins the route (what the check model credits), who supplies the input
+// (the source), who may start the entries that carry it (reach) and what those run as (effect).
+// Reading the source and the estate's records can show a route exploitable; only a test on the
+// running system confirms one, so a verdict says confirmed only where the estate brings the result
+// of its own test as a witness feed. See docs/spec/reach.md §9.
+import { readFileSync, realpathSync } from 'node:fs';
+import { basename, sep, delimiter } from 'node:path';
+import { ALL_RULES } from './kernel/registry.mjs';
+import { EXPLOITABILITY } from './kernel/findings.mjs';
+import { kindsOf } from './consequence.mjs';
+import { WHO } from './sets/flow.mjs';
+import { entryName, accessOfEntry, accessFromEntry, privilegedFromEntry } from './reach.mjs';
+
+export const HANDLING = 'This report joins routes an attacker can drive with the estate\'s own access facts. It holds no source '
+  + 'text, but it is a list of what to attack first: keep it where the access records it was built from may go, and do not '
+  + 'upload it anywhere more people can read it than can read those records.';
+
+// A system response is not input, but the caller who provokes the failure is the one who reads it back.
+const DRIVER = { ...WHO, 'system-response': 'A web caller, who can provoke the failure and reads the code sent back' };
+const AT_REST = { 'file-record': 'the file record', database: 'the database row' };
+
+const at = (x) => `${x.file}:${x.line}`;
+
+// The test on the value at the sink that the check model credits as clearing the route
+// (stops() in lib/control.mjs), so a patch written to it moves the finding to refuted on the next
+// scan. A sink no test on the value can make safe has none: the fix is the rule's remedy.
+const ALLOW_LIST = (i) => `${i} against a list of the values allowed (an EVALUATE with a WHEN for each literal and WHEN OTHER turning the rest away, or a condition name)`;
+const BOUND = (i) => `that ${i} is at least 1 and not above the number of entries in the table`;
+const TESTS = {
+  arithmetic: (i) => `${i} IS NUMERIC`,
+  subscript: BOUND,
+  'reference-modification': (i) => `that ${i} is at least 1 and not above the length of the field`,
+  'occurs-depending-count': (i) => `that ${i} is within the OCCURS range it sets`,
+  'loop-bound': BOUND,
+  'storage-length': (i) => `that ${i} is not above the most storage the program means to acquire`,
+  'dynamic-sql': (i) => `${ALLOW_LIST(i)}, or ${i} IS NUMERIC where it is a number`,
+  'internal-reader': (i) => `${ALLOW_LIST(i)}, or ${i} IS NUMERIC where it is a number`,
+  'web-response': (i) => `${ALLOW_LIST(i)}, or ${i} IS NUMERIC or IS ALPHABETIC, which leave no markup`,
+  'http-header': (i) => `${ALLOW_LIST(i)}, or ${i} IS NUMERIC or IS ALPHABETIC, which leave no line break`,
+  log: (i) => `${ALLOW_LIST(i)}, or ${i} IS NUMERIC or IS ALPHABETIC, which leave no line break`,
+  'os-command': ALLOW_LIST,
+  'dynamic-program-load': ALLOW_LIST,
+  'cics-dynamic-transfer': ALLOW_LIST,
+  'dynamic-file-path': ALLOW_LIST,
+  'queue-name': ALLOW_LIST,
+  'connection-target': ALLOW_LIST,
+  'cics-sysid': ALLOW_LIST,
+  'cics-system-resource': ALLOW_LIST,
+  'outbound-host': ALLOW_LIST,
+};
+
+// Where the rule's remedy takes input out of the operation altogether, which no test does.
+const WITHOUT_A_TEST = {
+  'dynamic-sql': 'a static statement with host variables',
+  'internal-reader': 'a job built from a fixed skeleton',
+  'os-command': 'a command built only from literals',
+};
+
+// Where one patch covers every route: immediately before the operation, on the value it uses. A
+// response code is not input, so no test on it clears a route; the fix is not to send it.
+function fixAt(f, kinds) {
+  const last = f.trace?.length ? f.trace[f.trace.length - 1] : null;
+  const item = last?.item || 'the value';
+  const test = kinds.source === 'system-response' ? null : TESTS[kinds.sink]?.(item) || null;
+  const instead = WITHOUT_A_TEST[kinds.sink];
+  return {
+    program: f.program || null, path: f.path, line: f.line, item,
+    ...(test ? { test: `before the operation at ${f.path}:${f.line}, on every route to it, test ${test}, and let only a value that passes reach it${instead ? `; ${instead} needs no test` : ''}` }
+      : { test: null, why: `no test of ${item} makes the operation at ${f.path}:${f.line} safe: apply the rule's remedy there` }),
+  };
+}
+
+// Entries grouped by what the estate declared about them, each group citing the record that said so.
+function entryFacts(f, resolver) {
+  const groups = new Map();
+  for (const e of f.startedBy) {
+    const access = resolver ? accessOfEntry(e, resolver) : null;
+    const state = access ? `${access === 'open' ? 'open to any user' : 'restricted'}, per ${accessFromEntry(e, resolver)}` : '';
+    if (!groups.has(state)) groups.set(state, []);
+    groups.get(state).push(entryName(e));
+  }
+  const more = f.startedByMore ? `; and ${f.startedByMore} more not listed` : '';
+  const said = (state, names) => state || `who may start ${names.length > 1 ? 'them' : 'it'} is not declared`;
+  const lines = [`started by ${[...groups].map(([state, names]) => `${names.join(', ')}: ${said(state, names)}`).join('; ')}${more}`];
+  const privileged = new Map();
+  for (const e of f.startedBy) {
+    const from = resolver && f.effect === 'privileged' ? privilegedFromEntry(e, resolver) : null;
+    if (!from) continue;
+    if (!privileged.has(from)) privileged.set(from, []);
+    privileged.get(from).push(entryName(e));
+  }
+  for (const [from, names] of privileged) lines.push(`${names.join(', ')} ${names.length > 1 ? 'run' : 'runs'} with elevated authority, per ${from}`);
+  return lines;
+}
+
+// The verdict on one finding, or null for a finding that is not a path: a construct or a piece of
+// context has no route for an attacker to drive. `checked` marks a route the check model stops.
+export function judge(f, resolver = null, { checked = false } = {}) {
+  const kinds = ALL_RULES[f.rule]?.evidence === 'path' ? kindsOf(f.rule) : null;
+  if (!kinds) return null;
+  const drivenBy = DRIVER[kinds.source];
+  const sink = `${f.path}:${f.line}`;
+  const because = [];
+  const src = f.related?.[0];
+  if (src) because.push(`${drivenBy} supplies it: ${src.detail} at ${src.path}:${src.line}${f.screen ? `, field ${f.screen.field} of map ${f.screen.map}` : ''}${f.sources > 1 ? `, one of ${f.sources} such sources` : ''}`);
+  const verdict = (v, unknown) => ({ verdict: v, drivenBy, because, ...(unknown ? { unknown } : {}), ...(v === 'refuted' ? {} : { fixAt: fixAt(f, kinds) }) });
+
+  if (checked) {
+    because.push(`${f.guard ? `the check on ${f.guard.item} at ${at(f.guard)}` : 'a check'} runs first on every route and leaves only values the operation at ${sink} can take`);
+    return verdict('refuted');
+  }
+  if (f.unreached) {
+    because.push(`no route from the program's entries reaches ${sink}, so as the program stands it does not run`);
+    return verdict('refuted');
+  }
+
+  let mitigation = null;
+  if (f.guardedFrom && f.guard) {
+    because.push(`the check on ${f.guard.item} at ${at(f.guard)} runs first on every route, but what it leaves is not shown safe for the operation at ${sink}`);
+    mitigation = `whether the check on ${f.guard.item} turns away every value the operation at ${sink} cannot take`;
+  } else if (f.ssrange) {
+    because.push('the program is compiled with SSRANGE, so an index out of range abends it instead of reaching the storage beside the table');
+    mitigation = 'whether an abend is an outage the estate can bear: SSRANGE stops the overrun, not whoever drives it';
+  } else if (f.checkElsewhere) {
+    because.push(`the check on ${f.checkElsewhere.item} at ${at(f.checkElsewhere)} does not run on every route: another reaches ${sink} without it`);
+  } else {
+    because.push(`no check is shown to run on every route before the operation at ${sink}`);
+  }
+
+  const entries = f.startedBy || [];
+  if (entries.length) because.push(...entryFacts(f, resolver));
+  else because.push(`nothing in this tree starts ${f.program || 'the program'}, so who can run it is not shown here`);
+
+  if (AT_REST[kinds.source]) return verdict('upstream', `who can write ${AT_REST[kinds.source]}: the tree does not show it`);
+  if (mitigation) return verdict('mitigated', mitigation);
+  if (ALL_RULES[f.rule].whenPrivileged && f.effect !== 'privileged') {
+    because.push('it acts with the authority of whoever runs it, and no entry that starts it is declared privileged');
+    return verdict('attacker-driven', 'whether an entry that starts it runs with more authority than its user: name it in privilegedTransactions or privilegedJobs, or in a COBOLWORK_REACH extract');
+  }
+  if (f.reach === 'open') return verdict('exploitable', 'whether it reproduces: a test on a system the estate owns, under its own authorisation, is the only confirmation');
+  if (f.reach === 'restricted') return verdict('restricted', 'whether everyone the control admits is trusted: the route is unchecked all the same');
+  return verdict('attacker-driven', entries.length
+    ? 'who may start the entries above: declare them in openTransactions, restrictedTransactions, openJobs or restrictedJobs in cobolwork.site.json, or bring a COBOLWORK_REACH extract'
+    : `what starts ${f.program || 'the program'}: no transaction or job in this tree does`);
+}
+
+// The feeds a scan was given: the caller's list, or COBOLWORK_WITNESS read when the scan runs.
+export function witnessFeedPaths(opts = {}) {
+  if (opts.witnessFeeds) return opts.witnessFeeds;
+  return (process.env.COBOLWORK_WITNESS || '').split(delimiter).filter(Boolean);
+}
+
+const OUTCOMES = new Set(['reproduced', 'not-reproduced']);
+const str = (v) => typeof v === 'string' && v.length > 0;
+const isoDate = (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v);
+
+// The results of the estate's own tests, keyed by the fingerprint of the finding each tried, loaded
+// for one scan and refused from inside the scanned tree the way a reach feed is: a list of what was
+// reproduced is a list of what to attack. Shape:
+//   { witness, recorded, results: { FINGERPRINT: { outcome: "reproduced"|"not-reproduced", by, on, system, reference? } } }
+// Only those fields are read. What was sent to the system is not one of them.
+export function loadWitnessFeed(path, { root = null } = {}) {
+  const feed = { file: basename(path), witness: null, recorded: null, results: new Map(), refused: [], problem: null };
+  let real;
+  try { real = realpathSync(path); } catch (e) { feed.problem = `could not be read (${e.code || e.name})`; return feed; }
+  if (root) {
+    const top = realpathSync(root);
+    if (real === top || real.startsWith(top + sep)) { feed.problem = 'is inside the tree being scanned, where anyone who can read the repository can read it, so it was not loaded'; return feed; }
+  }
+  let doc;
+  try { doc = JSON.parse(readFileSync(real, 'utf8')); } catch (e) { feed.problem = `is not JSON (${e.message})`; return feed; }
+  if (!str(doc.witness)) { feed.problem = 'does not say whose tests it holds'; return feed; }
+  if (!isoDate(doc.recorded)) { feed.problem = 'does not say when it was recorded'; return feed; }
+  if (!doc.results || typeof doc.results !== 'object' || Array.isArray(doc.results)) { feed.problem = 'holds no results'; return feed; }
+  feed.witness = doc.witness;
+  feed.recorded = doc.recorded;
+  for (const [fingerprint, r] of Object.entries(doc.results)) {
+    const why = !r || typeof r !== 'object' ? 'is not an object'
+      : !OUTCOMES.has(r.outcome) ? `says outcome ${JSON.stringify(r.outcome)}, not "reproduced" or "not-reproduced"`
+        : !str(r.by) ? 'does not say who ran the test'
+          : !isoDate(r.on) ? 'does not say when the test ran'
+            : !str(r.system) ? 'does not say which system it ran on' : null;
+    if (why) { feed.refused.push({ fingerprint, why: `the result for ${fingerprint} ${why}` }); continue; }
+    feed.results.set(fingerprint, { outcome: r.outcome, by: r.by, on: r.on, system: r.system, ...(str(r.reference) ? { reference: r.reference } : {}) });
+  }
+  return feed;
+}
+
+// The newest result for a fingerprint across the feeds; on the same day a reproduction outweighs a
+// test that did not reproduce it.
+function newest(feeds, fingerprint) {
+  let best = null;
+  for (const f of feeds) {
+    const r = f.results.get(fingerprint);
+    if (!r) continue;
+    if (!best || r.on > best.r.on || (r.on === best.r.on && r.outcome === 'reproduced')) best = { r, feed: f };
+  }
+  return best;
+}
+
+// Apply the estate's test results. A reproduced finding is confirmed, and takes back any severity a
+// check or the reading took off it, since the test shows neither held. A route the check model
+// cleared that the estate reproduced leaves `checked` and is reported as a finding again. A test
+// that did not reproduce a finding is stated beside its verdict and changes nothing: a test that
+// missed the route does not show it safe.
+export function applyWitness(findings, checked, feeds) {
+  const good = feeds.filter((f) => !f.problem);
+  const byWitness = { reproduced: 0, 'not-reproduced': 0 };
+  const matched = new Set();
+  const overruled = [];
+  const apply = (f) => {
+    const x = f.exploitability;
+    const hit = x && f.fingerprint ? newest(good, f.fingerprint) : null;
+    if (!hit) return false;
+    matched.add(f.fingerprint);
+    const { r, feed } = hit;
+    const cite = `${feed.file} (${feed.witness}, recorded ${feed.recorded})`;
+    x.witness = { ...r, from: cite };
+    byWitness[r.outcome]++;
+    if (r.outcome === 'not-reproduced') {
+      x.because.push(`not reproduced on ${r.system} by ${r.by} on ${r.on}${r.reference ? ` (${r.reference})` : ''}, per ${cite}`);
+      x.unknown = 'why the test did not reproduce it: a test that misses a route does not show the route safe';
+      return false;
+    }
+    const was = x.verdict;
+    x.verdict = 'confirmed';
+    x.because.push(`reproduced on ${r.system} by ${r.by} on ${r.on}${r.reference ? ` (${r.reference})` : ''}, per ${cite}`);
+    delete x.unknown;
+    if (!x.fixAt) x.fixAt = fixAt(f, kindsOf(f.rule));
+    if (f.guardedFrom) f.sev = f.guardedFrom;
+    if (f.unreached) { f.sev = ALL_RULES[f.rule].sev; delete f.unreached; }
+    return was === 'refuted';
+  };
+  for (const f of findings) if (apply(f)) overruled.push(f);
+  for (let i = checked.length - 1; i >= 0; i--) {
+    if (!apply(checked[i])) continue;
+    const [f] = checked.splice(i, 1);
+    overruled.push(f);
+    findings.push(f);
+  }
+  const unmatched = good.flatMap((feed) => [...feed.results.keys()]).filter((fp, i, all) => !matched.has(fp) && all.indexOf(fp) === i);
+  return {
+    byWitness,
+    overruled: overruled.map((f) => ({ fingerprint: f.fingerprint, rule: f.rule, path: f.path, line: f.line })),
+    unmatched,
+  };
+}
+
+export function byVerdict(findings) {
+  const by = Object.fromEntries(Object.keys(EXPLOITABILITY).map((v) => [v, 0]));
+  let judged = 0;
+  for (const f of findings) if (f.exploitability) { by[f.exploitability.verdict]++; judged++; }
+  return judged ? by : null;
+}
+
+// Stamp a verdict on every path finding and every route a check stopped, and count the findings.
+export function stampExploitability(findings, resolver, checked = []) {
+  for (const f of findings) { const x = judge(f, resolver); if (x) f.exploitability = x; }
+  for (const f of checked) { const x = judge(f, resolver, { checked: true }); if (x) f.exploitability = x; }
+  return byVerdict(findings);
+}