@portll/cobolwork 0.2.76 → 0.2.140

package/README.md

@@ -36,7 +36,8 @@ follows. To run from a checkout instead:
 
 Node 18 or later. No dependencies, runtime or development. `npm link` puts `cobolwork` on your PATH;
 adding `bin/` to PATH does the same thing. GnuCOBOL is needed only to regrade the parser or validate
-benchmark cases.
+benchmark cases. In a GitHub workflow, `uses: Portll/cobolwork@main` runs the build gate on a pull
+request and writes SARIF for code scanning: [docs/github-action.md](docs/github-action.md).
 
 ## What it does
 
@@ -44,7 +45,7 @@ benchmark cases.
 |---|---|
 | `cobolwork scan <path>` | every rule set below, as JSON or SARIF |
 | `cobolwork inventory <path>` | inventory (and what couldn't be read) |
-| `cobolwork flow <path>` | where untrusted data reaches a sensitive operation, with the path it took |
+| `cobolwork flow <path>` | where untrusted data reaches a sensitive operation, with the path it took and whether an attacker can use it |
 | `cobolwork diff <repo> --base <ref>` | what a change reaches: layouts it moves in programs nobody edited, new call targets, findings it adds or removes |
 | `cobolwork build <repo> [--base <ref>] [-- <compiler> …]` | the build gate: every finding ranked LOW to KNOWN-EXPLOITABLE, the build stopped on the ones the policy blocks and on compiler options that let a bad index corrupt storage, and the compiler run only on a pass |
 | `cobolwork parse <file>` | one file's structure, for debugging |
@@ -128,12 +129,63 @@ decides who acts on it. Every rule declares one of eight finding types:
 `coverage` and `context` are exactly the `info` rules (not defects). A consumer that counts these
 findings should leave them out of its counts.
 
-None of the kinds says *exploitable*, on purpose. Whether a route can be used also depends on who may
-start the transaction or job that reaches it, and on what the running system enforces, and no
-repository holds those facts. A finding names the entry points that reach it (`startedBy`). `path`
-is the strongest claim the tool makes: a route found by reading the code, not by running it. Its
-precision has been measured on benchmark cases this project wrote, not yet on an independently
-labelled corpus.
+`path` is a route found by reading the code, not by running it. Its precision has been measured on
+benchmark cases this project wrote, not yet on an independently labelled corpus.
+
+### Can an attacker use it?
+
+Every `path` finding carries a verdict, the facts it rests on, and the one fact that would change it:
+
+| `exploitability` | What it means | What to do |
+|---|---|---|
+| `confirmed` | the estate's own test reproduced it, and brought the result as a witness feed | patch now |
+| `exploitable` | input an attacker supplies reaches the operation with no check on every route, and the estate declares a transaction or job that carries it open to any user | patch first |
+| `attacker-driven` | the same route, but nobody has declared who may start its entries | patch, or declare the entries |
+| `restricted` | the same route, behind a control the estate named on every entry | patch; the control is not a check |
+| `mitigated` | a check runs first but is not shown to stop the value, or SSRANGE turns an overrun into an abend | confirm the check |
+| `upstream` | the value is a file record or database row, so whoever can write it drives it | review who writes the data |
+| `refuted` | a check leaves only safe values, or no route reaches the operation | nothing |
+
+For the terminal route to dynamic SQL in `test/fixtures/entry`, scanned with a site file that
+declares its transaction open:
+
+```json
+"exploitability": {
+  "verdict": "exploitable",
+  "drivenBy": "A terminal user",
+  "because": [
+    "A terminal user supplies it: EXEC CICS RECEIVE at INQUIRY.cbl:10",
+    "no check is shown to run on every route before the operation at INQUIRY.cbl:13",
+    "started by transaction INQ1: open to any user, per cobolwork.site.json"
+  ],
+  "unknown": "whether it reproduces: a test on a system the estate owns, under its own authorisation, is the only confirmation",
+  "fixAt": {
+    "program": "INQUIRY", "path": "INQUIRY.cbl", "line": 13, "item": "WS-STMT",
+    "test": "before the operation at INQUIRY.cbl:13, on every route to it, test WS-STMT against a list of the values allowed (...), and let only a value that passes reach it; a static statement with host variables needs no test"
+  }
+}
+```
+
+`fixAt` is where one patch covers every route, with a test the analysis credits: patch it there, scan
+again, and the finding moves to `refuted`. Where no test makes the operation safe, `why` says so and
+the rule's remedy is the fix.
+
+Who may start a transaction lives in RACF, not in a repository, so without it the strongest verdict is
+`attacker-driven`, and `summary.reachNote` says how many that is. Name the entries in
+`cobolwork.site.json` (`openTransactions`, `restrictedTransactions`, `openJobs`, `restrictedJobs`), or
+bring a reduced RACF unload as `COBOLWORK_REACH`, which is refused from inside the scanned tree.
+`node diag/propose-site.mjs <path>` lists the transactions and jobs to ask about, most findings
+first, with the program each runs and any listener or URI map that puts it on the network; it
+proposes none of them as open or restricted.
+
+The tool never confirms a finding from reading: that needs a test on the running system. The estate
+brings its own results as `COBOLWORK_WITNESS`, keyed by fingerprint with the outcome, who ran the
+test, when and on which system, and refused from inside the tree like `COBOLWORK_REACH`. A reproduced
+finding becomes `confirmed`; one the estate's test did not reproduce keeps its verdict and says so,
+since a test that missed the route does not show it safe.
+`summary.byExploitability` counts the verdicts, and a report holding an `exploitable` finding carries
+`summary.handling`, because it is then a list of what to attack first. Upload it only where the RACF
+facts behind it may go. [docs/spec/reach.md](docs/spec/reach.md) §9 is the full specification.
 
 ### What each finding lets someone do, and the fix
 
@@ -191,7 +243,7 @@ A scan says what each rule set read, not only what it found:
       "why": "no cobolwork.site.json: the production-name and production-dataset rules did not run, because nothing declares what production means in this estate" }
   ],
   "flowModel": "byte-range",
-  "toolVersion": "0.2.0"
+  "toolVersion": "0.2.90"
 }
 ```
 
@@ -236,7 +288,7 @@ gate. An incomplete scan is undecided, never a pass.
 
 The compiler options are held to the policy too. A program compiled without `SSRANGE`, or with
 `SSRANGE(MSG)`, which reports a bad subscript and carries on, fails; for `cobc` the missing `-fec`
-checks are added to the command. `cobolwork.policy.json` changes any of this, and `--policy <file>`
+checks are added to the command, and for GCC's `gcobol` the missing `-fcobol-exceptions`. `cobolwork.policy.json` changes any of this, and `--policy <file>`
 names an organisation's floor, which a repository can tighten and never loosen.
 [docs/spec/build-gate.md](docs/spec/build-gate.md) is the full specification.
 
@@ -261,7 +313,7 @@ stand-in in `diag/precompiler.mjs`, which rewrites what the parser would otherwi
 tests compare the parser with the compiler's answers kept in `test/fixtures/parser/*.golden.json`,
 so they run without GnuCOBOL.
 
-`bench/cases/` holds 93 CWE-labelled cases, each paired with a near-miss negative: the same shape
+`bench/cases/` holds 102 CWE-labelled cases, each paired with a near-miss negative: the same shape
 with the flaw removed. `node bench/run.mjs` scores any scanner's findings against them, by rule and
 file, never by line, and `npm test` fails if any case scores differently from its declaration.
 `--validate` compiles every COBOL case with GnuCOBOL and checks every JCL case against the
@@ -291,9 +343,9 @@ Every rule is mapped to the clause of each framework that makes it an obligation
 
 | File | Instrument | Rules mapped |
 |---|---|---|
-| `rules/compliance-dora.json` | Regulation (EU) 2022/2554 (DORA) | 156 |
-| `rules/compliance-ffiec.json` | FFIEC IT Examination Handbook | 154, and 2 recorded as unmapped |
-| `rules/compliance-nist80053.json` | NIST SP 800-53 Rev. 5.2.0 | 154, and 2 recorded as unmapped |
+| `rules/compliance-dora.json` | Regulation (EU) 2022/2554 (DORA) | 203 |
+| `rules/compliance-ffiec.json` | FFIEC IT Examination Handbook | 201, and 2 recorded as unmapped |
+| `rules/compliance-nist80053.json` | NIST SP 800-53 Rev. 5.2.0 | 201, and 2 recorded as unmapped |
 
 `node diag/map-compliance.mjs` refuses to write a quote the cached instrument does not contain, and
 every scan carries the mapping as `ruleCompliance`. The clause choice is a judgement that no

package/bin/cobolwork.mjs

@@ -4,9 +4,10 @@ import { writeFileSync, readFileSync, lstatSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { scanAll, RULE_SETS } from '../lib/scan.mjs';
+import { scanAll, applyEstateFacts, RULE_SETS } from '../lib/scan.mjs';
 import { scan as scanFlow } from '../lib/sets/flow.mjs';
 import { inventory } from '../lib/inventory.mjs';
+import { sbom } from '../lib/sbom.mjs';
 import { parseFile } from '../lib/parser.mjs';
 import { toSarif } from '../lib/sarif.mjs';
 import { diffRefs } from '../lib/diff.mjs';
@@ -15,12 +16,19 @@ import { build, buildSarif, buildSummaryLine } from '../lib/build.mjs';
 import { capabilities } from '../lib/capabilities.mjs';
 import { commitAt, revisionOf, toolRevision } from '../lib/revision.mjs';
 import { stampFingerprints } from '../lib/kernel/identity.mjs';
+import { tally } from '../lib/kernel/findings.mjs';
 import { loadBaseline, applyBaseline, baselineEntries, BASELINE_FILE, SUPPRESSING } from '../lib/baseline.mjs';
 import { readReport } from '../lib/tui/model.mjs';
 import { nodeTerminal } from '../lib/tui/terminal.mjs';
 import { runTui } from '../lib/tui/run.mjs';
 import { explainFinding } from '../lib/explain.mjs';
 import { printable } from '../lib/kernel/printable.mjs';
+import { startEvidence, recordInputs, recordHashed, recordFindings, recordOutput, recordVerdict, recordBaselineWrite, finishEvidence } from '../lib/evidence/run.mjs';
+import { evidenceCommand } from '../lib/evidence/cli.mjs';
+import { slsaStatement } from '../lib/evidence/slsa.mjs';
+import { parseAllowedSigners } from '../lib/evidence/sshsig.mjs';
+
+const STARTED = new Date().toISOString();
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
@@ -28,6 +36,9 @@ const USAGE = `cobolwork ${VERSION} — COBOL, JCL and CICS security analysis, n
 
   cobolwork scan <path>        every rule set: data flow, CICS, JCL, hidden content, copybooks, build pins
   cobolwork inventory <path>   what is there and what could not be read (copybooks, dialects)
+  cobolwork sbom <path> [--name <estate>]
+                               a CycloneDX 1.6 bill of materials: every source by SHA-256, what each
+                               program copies and calls, what each job runs, and the platforms used
   cobolwork flow <path>        data-flow findings with the path the data took, as JSON
   cobolwork parse <file>       parse one source file and print a summary
   cobolwork diff <repo> --base <ref> [--head <ref>]
@@ -47,11 +58,17 @@ const USAGE = `cobolwork ${VERSION} — COBOL, JCL and CICS security analysis, n
                                what this cobolwork can do: commands and options, the version of every
                                document it writes, its fingerprint version, the file kinds it reads, and
                                the commit it runs from
-  cobolwork build <repo> [--base <ref>] [--policy <file>] [--provenance <file>] [-- <compiler> <arg>...]
+  cobolwork build <repo> [--base <ref>] [--policy <file>] [--provenance <file>] [--ironwork <path> | -- <compiler> <arg>...]
                                the build gate: every finding ranked LOW to KNOWN-EXPLOITABLE, the
                                policy's blocking findings and compiler options checked, and the
                                compiler run only on a pass. Exits 0 pass, 1 fail, 3 undecided, 4 the
                                compiler failed after a pass, 2 could not run
+  cobolwork evidence verify|seal|anchor --evidence <dir>
+                               the evidence a run records: verify its chains, seals and witnesses;
+                               seal the ledger (--ssh-key <file> or --signer <program>); anchor a seal
+                               in a git witness (--anchor-git <repo> [--push]) or write an RFC 3161
+                               request (--tsq <file>). verify exits 0 sealed, 1 broken or contradicted,
+                               3 undetermined
 
 Options
   --format json|sarif   output format (default json)
@@ -81,6 +98,22 @@ Options
   --policy <file>       build: an organisation's floor policy, from outside the repository; the
                         repository's cobolwork.policy.json can tighten it and never loosen it
   --provenance <file>   build: write what was scanned, under which policy, and what was compiled
+  --provenance-format cobolwork|slsa  build: the record as written today, or an in-toto statement with
+                        the SLSA Provenance v1 predicate (unsigned; the pipeline signs it)
+  --artifact <path>[,<path>]  build: what the compiler produced, named as subjects of the SLSA statement
+  --equivalence <file>[,<file>]  build --base: ironwork equivalence statements for the programs the
+                        change edits; with --allowed-signers each must be signed by one. The policy's
+                        requireEquivalence (never, machineAuthored, always) says when one is required
+  --ironwork <path>     build: after a pass, run ironwork check on every program, for an estate that
+                        compiles with IBM Enterprise COBOL; a program ironwork rejects exits 4, one it
+                        does not model yet leaves the build undecided
+  --evidence <dir>      scan, flow, diff, gate, build, baseline, inventory: record this run in a
+                        hash-chained journal and ledger there (or COBOLWORK_EVIDENCE); never inside
+                        the tree being read
+  --allowed-signers <file>  evidence verify: OpenSSH allowed_signers for namespace cobolwork-evidence
+  --anchor-git <repo>, --ref <ref>, --push, --max-unsealed <n>
+                        evidence: the git witness, the ref that counts (default @{upstream}), whether
+                        anchor pushes, and how many ledger records may follow the newest seal
 
 Exit codes: 0 the command ran, 2 it could not run. A run that examined nothing says so in
 summary.filesScanned and summary.nosrc rather than reporting a clean zero.
@@ -127,6 +160,21 @@ function parseArgs(argv) {
     else if (a === '--json') opts.json = true;
     else if (a === '--policy') opts.policy = value();
     else if (a === '--provenance') opts.provenance = value();
+    else if (a === '--provenance-format') opts.provenanceFormat = value();
+    else if (a === '--equivalence') opts.equivalence = [...(opts.equivalence || []), ...list().map((x) => resolve(x))];
+    else if (a === '--artifact') opts.artifact = [...(opts.artifact || []), ...list().map((x) => resolve(x))];
+    else if (a === '--ironwork') opts.ironwork = value();
+    else if (a === '--evidence') opts.evidence = value();
+    else if (a === '--name') opts.name = value();
+    else if (a === '--ssh-key') opts.sshKey = value();
+    else if (a === '--signer') opts.signer = value();
+    else if (a === '--allowed-signers') opts.allowedSigners = value();
+    else if (a === '--anchor-git') opts.anchorGit = value();
+    else if (a === '--ref') opts.ref = value();
+    else if (a === '--push') opts.push = true;
+    else if (a === '--max-unsealed') opts.maxUnsealed = value();
+    else if (a === '--tsq') opts.tsq = value();
+    else if (a === '--expect-key') opts.expectKey = value();
     else if (a === '--help' || a === '-h') opts.help = true;
     else if (a === '--version' || a === '-v') opts.version = true;
     else if (a.startsWith('-')) { opts.unknown = a; }
@@ -151,8 +199,11 @@ function warnCoverage(report) {
 
 const isLink = (p) => { try { return lstatSync(p).isSymbolicLink(); } catch { return false; } };
 
+let journal = null;
+
 function emit(obj, opts) {
   const text = JSON.stringify(obj, null, opts.quiet ? 0 : 1);
+  recordOutput(journal, 'report', text + '\n', opts.out || null);
   if (opts.out) { writeFileSync(opts.out, text + '\n'); return; }
   // A pipe drains asynchronously and process.exit discards what has not drained: past 64 KB the
   // reader got a truncated document and exit 0. The process ends on its own once stdout is flushed.
@@ -202,7 +253,7 @@ if (gateFlag && opts._.length && opts._[0] !== 'gate') {
   process.stderr.write(`cobolwork: --${gateFlag.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)} is for gate only\n`);
   process.exit(2);
 }
-const COPYLIB_COMMANDS = ['scan', 'flow', 'inventory', 'diff', 'build', 'baseline', 'tui', 'explain'];
+const COPYLIB_COMMANDS = ['scan', 'flow', 'inventory', 'diff', 'build', 'baseline', 'tui', 'explain', 'sbom'];
 if (opts.copylib && opts._.length && !COPYLIB_COMMANDS.includes(opts._[0])) {
   process.stderr.write(`cobolwork: ${opts._[0]} reads no copybooks; ${COPYLIB_COMMANDS.join(', ')} do\n`);
   process.exit(2);
@@ -215,7 +266,9 @@ if (opts.json && opts._.length && opts._[0] !== 'capabilities') {
   process.stderr.write(`cobolwork: --json is for capabilities; every other command writes JSON unless --format says otherwise\n`);
   process.exit(2);
 }
-const buildFlag = ['policy', 'provenance'].find((k) => opts[k] !== undefined) || (compilerArgv ? '' : null);
+const buildFlag = ['policy', 'provenance', 'provenanceFormat', 'artifact', 'equivalence', 'ironwork'].find((k) => opts[k] !== undefined) || (compilerArgv ? '' : null);
+if (opts.provenanceFormat !== undefined && !['cobolwork', 'slsa'].includes(opts.provenanceFormat)) { process.stderr.write(`cobolwork: --provenance-format takes cobolwork or slsa; got ${opts.provenanceFormat}\n`); process.exit(2); }
+if ((opts.provenanceFormat !== undefined || opts.artifact) && !opts.provenance) { process.stderr.write('cobolwork: --provenance-format and --artifact describe the --provenance file; name it\n'); process.exit(2); }
 if (buildFlag !== null && opts._.length && opts._[0] !== 'build') {
   process.stderr.write(`cobolwork: ${buildFlag ? `--${buildFlag}` : '--'} is for build only\n`);
   process.exit(2);
@@ -223,11 +276,32 @@ if (buildFlag !== null && opts._.length && opts._[0] !== 'build') {
 // A misspelled set would run nothing and report a clean zero.
 const badSets = (opts.only || []).filter(s => !RULE_SETS.includes(s));
 if (badSets.length || (opts.only && !opts.only.length)) { process.stderr.write(`cobolwork: --only takes ${RULE_SETS.join(',')}; got ${badSets.join(',') || 'nothing'}\n`); process.exit(2); }
+const JOURNALED = ['scan', 'flow', 'diff', 'gate', 'build', 'baseline', 'inventory', 'sbom'];
+if (opts.name !== undefined && opts._.length && opts._[0] !== 'sbom') { process.stderr.write('cobolwork: --name is for sbom only\n'); process.exit(2); }
+if (opts.evidence !== undefined && opts._.length && ![...JOURNALED, 'evidence'].includes(opts._[0])) {
+  process.stderr.write(`cobolwork: ${opts._[0]} records no evidence; ${JOURNALED.join(', ')} and evidence do\n`);
+  process.exit(2);
+}
+const evidenceFlag = ['sshKey', 'signer', 'allowedSigners', 'anchorGit', 'ref', 'push', 'maxUnsealed', 'tsq', 'expectKey'].find((k) => opts[k] !== undefined);
+if (opts.equivalence && !opts.base) { process.stderr.write('cobolwork: --equivalence judges a change; it needs --base\n'); process.exit(2); }
+if (evidenceFlag && opts._.length && opts._[0] !== 'evidence' && !(evidenceFlag === 'allowedSigners' && opts._[0] === 'build')) {
+  process.stderr.write(`cobolwork: --${evidenceFlag.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)} is for evidence only\n`);
+  process.exit(2);
+}
 
 const [command, target] = opts._;
 const root = resolve(target || '.');
 const repos = opts.repos ? readdirSync(root, { withFileTypes: true }).filter(d => d.isDirectory() && !d.name.startsWith('.')).map(d => d.name) : [''];
 
+if (JOURNALED.includes(command)) {
+  try {
+    journal = startEvidence(opts, { command, argv, roots: [root], toolVersion: VERSION });
+  } catch (e) {
+    process.stderr.write(`cobolwork: ${printable(e && e.message ? e.message : e)}\n`);
+    process.exit(2);
+  }
+}
+
 function storedReport(file) {
   const path = resolve(file);
   let doc;
@@ -254,12 +328,22 @@ function baselinedScan() {
 try {
   if (command === 'capabilities') {
     emit(capabilities(), opts);
+  } else if (command === 'evidence') {
+    process.exitCode = evidenceCommand(target, opts, { toolVersion: VERSION, write: (s) => process.stdout.write(s) });
   } else if (command === 'scan' || command === 'flow') {
     const flowOpts = { repos, fullTrace: opts.fullTrace === true, systemDirs };
     const report = command === 'flow' ? scanFlow(root, flowOpts) : scanAll(root, { ...flowOpts, only: opts.only, advisoryFeeds: opts.advisoryFeeds });
-    if (command === 'flow') report.summary.identity = stampFingerprints(report.findings, { root });
+    if (command === 'flow') {
+      report.summary.identity = stampFingerprints(report.findings, { root });
+      stampFingerprints(report.checked, { root });
+      Object.assign(report.summary, applyEstateFacts(report.findings, report.checked, root));
+      // A route the estate reproduced moves from checked back to findings.
+      Object.assign(report.summary, { findings: report.findings.length, byRule: tally(report.findings), checked: report.checked.length });
+    }
     applyBaseline(report, loadBaseline(root, { explicit: opts.baseline ? resolve(opts.baseline) : null, use: !opts.noBaseline }));
     stampRevisions(report.summary);
+    recordInputs(journal, 0, root);
+    recordFindings(journal, report);
     if (command === 'flow') emit(report, opts);
     else if (opts.format === 'sarif') emit(toSarif(report, { toolVersion: VERSION }), opts);
     else emit(opts.quiet ? { tool: report.tool, schemaVersion: report.schemaVersion, summary: report.summary } : report, opts);
@@ -268,6 +352,7 @@ try {
     if (!opts.base) { process.stderr.write(`cobolwork: diff needs --base <ref>\n`); process.exit(2); }
     const report = diffRefs(root, opts.base, opts.head || null, { only: opts.only, fullTrace: opts.fullTrace === true, systemDirs });
     stampRevisions(report.summary, opts.head || null);
+    recordFindings(journal, { findings: [...report.findings, ...(report.introduced || [])] });
     if (opts.format === 'sarif') emit(toSarif({ ...report, findings: [...report.findings, ...report.introduced] }, { toolVersion: VERSION }), opts);
     else emit(opts.quiet ? { tool: report.tool, schemaVersion: report.schemaVersion, summary: report.summary } : report, opts);
   } else if (command === 'gate') {
@@ -280,13 +365,14 @@ try {
     stampRevisions(doc.summary, opts.head || null);
     emit(doc, opts);
     if (opts.exitCode) process.exitCode = VERDICT_EXIT[doc.verdict];
+    recordVerdict(journal, doc, process.exitCode ?? 0);
   } else if (command === 'build') {
     // A rule set left out is findings not seen, and a waiver file from elsewhere is not the one the
     // change was reviewed against.
     if (opts.only || opts.repos) { process.stderr.write('cobolwork: build judges one repository with every rule set; --only and --repos do not apply\n'); process.exit(2); }
     if (opts.baseline) { process.stderr.write('cobolwork: build reads the baseline the change was written against; --baseline does not apply, --no-baseline does\n'); process.exit(2); }
     if (opts.head && !opts.base) { process.stderr.write('cobolwork: build --head needs --base\n'); process.exit(2); }
-    const result = build(root, { base: opts.base || null, head: opts.head || null, policy: opts.policy || null, noBaseline: opts.noBaseline === true, compiler: compilerArgv, advisoryFeeds: opts.advisoryFeeds || null, copylibs: systemDirs });
+    const result = build(root, { base: opts.base || null, head: opts.head || null, policy: opts.policy || null, noBaseline: opts.noBaseline === true, compiler: compilerArgv, ironwork: opts.ironwork || null, advisoryFeeds: opts.advisoryFeeds || null, copylibs: systemDirs, equivalence: opts.equivalence || [], allowed: opts.allowedSigners ? parseAllowedSigners(readFileSync(resolve(opts.allowedSigners), 'utf8')) : null });
     stampRevisions(result.doc.summary, opts.head || null);
     Object.assign(result.report.summary, { toolRevision: result.doc.summary.toolRevision, revision: result.doc.summary.revision });
     Object.assign(result.provenance, { toolRevision: result.doc.summary.toolRevision, revision: result.doc.summary.revision });
@@ -294,9 +380,25 @@ try {
       const report = result.report;
       emit(buildSarif(toSarif({ ...report, findings: report.findings }, { toolVersion: VERSION }), result.doc), opts);
     } else emit(result.doc, opts);
-    if (opts.provenance) writeFileSync(resolve(opts.provenance), JSON.stringify(result.provenance, null, 1) + '\n');
+    recordHashed(journal, 0, result.provenance.sources);
+    recordFindings(journal, result.report);
+    if (opts.provenance) {
+      const record = opts.provenanceFormat === 'slsa'
+        ? slsaStatement({
+          provenance: result.provenance, root, artifacts: opts.artifact || [],
+          docBytes: Buffer.from(JSON.stringify(result.doc, null, opts.quiet ? 0 : 1) + '\n'),
+          runId: journal ? journal.id : null, runTip: journal && journal.tip ? journal.tip.hash : null,
+          builderId: process.env.COBOLWORK_BUILDER_ID || null,
+          ...(process.env.SOURCE_DATE_EPOCH ? {} : { startedOn: STARTED, finishedOn: new Date().toISOString() }),
+        })
+        : result.provenance;
+      const text = JSON.stringify(record, null, 1) + '\n';
+      writeFileSync(resolve(opts.provenance), text);
+      recordOutput(journal, 'provenance', text, resolve(opts.provenance));
+    }
     process.stderr.write(`${buildSummaryLine(result.doc)}\n`);
     process.exitCode = result.exit;
+    recordVerdict(journal, result.doc, result.exit);
   } else if (command === 'baseline') {
     // A suppression nobody dated is never looked at again, so every part of the judgement is asked for.
     const missing = ['reason', 'who', 'expires'].filter((k) => !opts[k]);
@@ -313,8 +415,14 @@ try {
     if (held.problems.length) { process.stderr.write(`cobolwork: ${path} holds entries that do not validate, so it is left as it is:\n  ${held.problems.join('\n  ')}\n`); process.exit(2); }
     const report = scanAll(root, { repos, only: opts.only, advisoryFeeds: opts.advisoryFeeds, systemDirs });
     const { entries, added } = baselineEntries(report.findings, held.entries, { action, reason: opts.reason, who: opts.who, expires: expires.toISOString(), at, rules: opts.rule || null });
-    writeFileSync(path, JSON.stringify({ _comment: 'Judgements over cobolwork findings, matched by fingerprint. A suppression lapses at its expires date and the finding comes back.', entries }, null, 1) + '\n');
-    process.stdout.write(`${JSON.stringify({ tool: 'cobolwork-baseline', path, added, entries: entries.length })}\n`);
+    const written = JSON.stringify({ _comment: 'Judgements over cobolwork findings, matched by fingerprint. A suppression lapses at its expires date and the finding comes back.', entries }, null, 1) + '\n';
+    writeFileSync(path, written);
+    recordInputs(journal, 0, root);
+    recordFindings(journal, report);
+    recordBaselineWrite(journal, { before: held.entries, after: entries, who: opts.who, expires: expires.toISOString(), reason: opts.reason, path, text: written });
+    const line = `${JSON.stringify({ tool: 'cobolwork-baseline', path, added, entries: entries.length })}\n`;
+    recordOutput(journal, 'baseline', line);
+    process.stdout.write(line);
   } else if (command === 'tui') {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
       process.stderr.write('cobolwork: tui needs a terminal on standard input and output; cobolwork scan writes the same report without one\n');
@@ -332,8 +440,15 @@ try {
     const packet = explainFinding({ ...report, findings: [...report.findings, ...(report.suppressed || [])] }, fingerprint, { root });
     if (!packet) { process.stderr.write(`cobolwork: no finding with fingerprint ${fingerprint} in this report\n`); process.exit(2); }
     emit(packet, opts);
+  } else if (command === 'sbom') {
+    const bom = sbom(root, { systemDirs, name: opts.name });
+    recordInputs(journal, 0, root);
+    const text = JSON.stringify(bom, null, opts.quiet ? 0 : 1) + '\n';
+    recordOutput(journal, 'sbom', text, opts.out || null);
+    if (opts.out) writeFileSync(opts.out, text); else process.stdout.write(text);
   } else if (command === 'inventory') {
     const inv = inventory(root, { systemDirs });
+    recordInputs(journal, 0, root);
     emit(inv, opts);
     warnCoverage(inv);
   } else if (command === 'parse') {
@@ -348,7 +463,9 @@ try {
     process.stderr.write(`cobolwork: unknown command ${command}\n${USAGE}`);
     process.exit(2);
   }
+  finishEvidence(journal, process.exitCode ?? 0);
 } catch (e) {
   process.stderr.write(`cobolwork: ${printable(e && e.message ? e.message : e)}\n`);
+  finishEvidence(journal, 2);
   process.exit(2);
 }

package/lib/arith.mjs

@@ -0,0 +1,235 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Interval arithmetic for the check model: what an arithmetic statement can leave in an integer
+// field, given what its operands can hold. Endpoints are exact rationals, so a quotient's lower end
+// is not lost to rounding, and every interval is closed.
+//
+// An expression is parsed once into a tree whose leaves name fields; `candidates` then reads it
+// against the facts the caller can offer for each field. Each candidate is an interval together with
+// the facts it needs to hold, so the caller can tie the result to the same facts.
+
+const gcd = (a, b) => { a = a < 0n ? -a : a; b = b < 0n ? -b : b; while (b) [a, b] = [b, a % b]; return a; };
+export const q = (n, d = 1n) => {
+  if (d < 0n) { n = -n; d = -d; }
+  const g = gcd(n, d) || 1n;
+  return { n: n / g, d: d / g };
+};
+const cmp = (a, b) => { const x = a.n * b.d - b.n * a.d; return x < 0n ? -1 : x > 0n ? 1 : 0; };
+const qAdd = (a, b) => q(a.n * b.d + b.n * a.d, a.d * b.d);
+const qSub = (a, b) => q(a.n * b.d - b.n * a.d, a.d * b.d);
+const qMul = (a, b) => q(a.n * b.n, a.d * b.d);
+const qDiv = (a, b) => q(a.n * b.d, a.d * b.n);
+const qMin = (list) => list.reduce((m, x) => (cmp(x, m) < 0 ? x : m));
+const qMax = (list) => list.reduce((m, x) => (cmp(x, m) > 0 ? x : m));
+export const floorQ = (a) => { const t = a.n / a.d; return a.n % a.d !== 0n && a.n < 0n ? t - 1n : t; };
+export const ceilQ = (a) => { const t = a.n / a.d; return a.n % a.d !== 0n && a.n > 0n ? t + 1n : t; };
+const truncQ = (a) => a.n / a.d;
+
+// A division is exact when its divisor is a whole number with no prime factor but 2 and 5, which the
+// decimal arithmetic of every compiler carries to the end; any other quotient is cut short of its
+// last digit, in either direction, and the interval says so.
+const terminating = (b) => {
+  if (b.d !== 1n) return false;
+  let n = b.n < 0n ? -b.n : b.n;
+  for (const p of [2n, 5n]) while (n % p === 0n) n /= p;
+  return n === 1n;
+};
+const EPSILON = q(1n, 10n ** 30n);
+
+const iv = (lo, hi, inexact = false) => ({ lo, hi, inexact });
+const ivAdd = (a, b) => iv(qAdd(a.lo, b.lo), qAdd(a.hi, b.hi), a.inexact || b.inexact);
+const ivSub = (a, b) => iv(qSub(a.lo, b.hi), qSub(a.hi, b.lo), a.inexact || b.inexact);
+function ivMul(a, b) {
+  if (a.inexact || b.inexact) return null;
+  const p = [qMul(a.lo, b.lo), qMul(a.lo, b.hi), qMul(a.hi, b.lo), qMul(a.hi, b.hi)];
+  return iv(qMin(p), qMax(p));
+}
+function ivDiv(a, b) {
+  if (a.inexact || b.inexact) return null;
+  if (!(cmp(b.lo, q(0n)) > 0 || cmp(b.hi, q(0n)) < 0)) return null;
+  const p = [qDiv(a.lo, b.lo), qDiv(a.lo, b.hi), qDiv(a.hi, b.lo), qDiv(a.hi, b.hi)];
+  const point = cmp(b.lo, b.hi) === 0;
+  return iv(qMin(p), qMax(p), !(point && terminating(b.lo)));
+}
+const ivNeg = (a) => iv(qSub(q(0n), a.hi), qSub(q(0n), a.lo), a.inexact);
+// FUNCTION MOD takes the sign of its divisor, so a positive divisor leaves 0 up to one below it.
+function ivMod(a, b) {
+  if (a.inexact || b.inexact || b.lo.d !== 1n || b.hi.d !== 1n || cmp(b.lo, q(1n)) < 0) return null;
+  return iv(q(0n), qSub(b.hi, q(1n)));
+}
+
+// What lands in an integer field: a truncated value moves toward zero, a rounded one to either
+// neighbour, whatever the rounding mode.
+export function storedRange(r, rounded) {
+  let { lo, hi } = r;
+  if (r.inexact) { lo = qSub(lo, EPSILON); hi = qAdd(hi, EPSILON); }
+  return rounded ? { lo: floorQ(lo), hi: ceilQ(hi) } : { lo: truncQ(lo), hi: truncQ(hi) };
+}
+
+// ---- parsing ----------------------------------------------------------------------------------
+
+const isWord = (t, u) => t && t.t === 'word' && t.u === u;
+const isSep = (t, v) => t && t.t === 'sep' && t.v === v;
+const isOp = (t, v) => t && t.t === 'op' && t.v === v;
+const decimal = (s) => {
+  const m = /^(\d*)(?:\.(\d+))?$/.exec(s);
+  if (!m || (!m[1] && !m[2])) return null;
+  const frac = m[2] || '';
+  return q(BigInt((m[1] || '0') + frac), 10n ** BigInt(frac.length));
+};
+const TRIMS = new Set(['TRIM', 'UPPER-CASE', 'LOWER-CASE', 'REVERSE']);
+
+// The token after a balanced pair of parentheses that opens at `i`, or -1.
+function closeOf(toks, i) {
+  let depth = 0;
+  for (let j = i; j < toks.length; j++) {
+    if (isSep(toks[j], '(')) depth++;
+    else if (isSep(toks[j], ')') && --depth === 0) return j;
+  }
+  return -1;
+}
+
+// `env.field(tok, subscripted)` gives a leaf for an integer field or null; `env.sizeOf(tokens)` the
+// most bytes an item, subscripted or not, can be, or null.
+export function parser(toks, env) {
+  let i = 0;
+  const fail = () => { throw parser; };
+  function lengthArg(inner) {
+    if (inner.length === 1 && inner[0].t === 'lit') return { k: 'range', lo: q(BigInt(String(inner[0].v).length)), hi: q(BigInt(String(inner[0].v).length)) };
+    let span = inner;
+    if (isWord(span[0], 'FUNCTION') && span[1] && TRIMS.has(span[1].u) && isSep(span[2], '(') && closeOf(span, 2) === span.length - 1) {
+      span = span.slice(3, -1).filter((t) => !isWord(t, 'LEADING') && !isWord(t, 'TRAILING'));
+    }
+    const size = span.length && span[0].t === 'word' ? env.sizeOf(span) : null;
+    return size == null ? fail() : { k: 'range', lo: q(0n), hi: q(BigInt(size)) };
+  }
+  function primary() {
+    const t = toks[i];
+    if (!t) fail();
+    if (isOp(t, '-') || isOp(t, '+')) { i++; const a = primary(); return t.v === '-' ? { k: 'neg', a } : a; }
+    if (isSep(t, '(')) {
+      i++;
+      const a = expr();
+      if (!isSep(toks[i], ')')) fail();
+      i++;
+      return a;
+    }
+    if (t.t === 'num') { const v = decimal(t.v); if (!v) fail(); i++; return { k: 'const', v }; }
+    if (t.t !== 'word') fail();
+    if (/^\d+$/.test(t.v)) { i++; return { k: 'const', v: q(BigInt(t.v)) }; }
+    if (t.u === 'LENGTH' && isWord(toks[i + 1], 'OF') && toks[i + 2] && toks[i + 2].t === 'word') {
+      const size = env.sizeOf([toks[i + 2]]);
+      if (size == null) fail();
+      i += 3;
+      return { k: 'range', lo: q(BigInt(size)), hi: q(BigInt(size)) };
+    }
+    if (t.u === 'FUNCTION') {
+      const name = toks[i + 1] && toks[i + 1].u;
+      if (!name || !isSep(toks[i + 2], '(')) fail();
+      const close = closeOf(toks, i + 2);
+      if (close < 0) fail();
+      const inner = toks.slice(i + 3, close);
+      let node;
+      if (name === 'LENGTH') node = lengthArg(inner);
+      else if (name === 'ORD') node = { k: 'range', lo: q(1n), hi: q(256n) };
+      else if (name === 'MOD') {
+        const sub = parser(inner, env);
+        const a = sub.expr();
+        const b = sub.expr();
+        if (!sub.done()) fail();
+        node = { k: 'mod', a, b };
+      } else fail();
+      i = close + 1;
+      return node;
+    }
+    // An identifier, with the subscripts of a table element; a qualified name or a reference
+    // modification is not read.
+    if (isWord(toks[i + 1], 'OF') || isWord(toks[i + 1], 'IN')) fail();
+    let subscripted = false;
+    let end = i + 1;
+    if (isSep(toks[end], '(')) {
+      const close = closeOf(toks, end);
+      if (close < 0 || toks.slice(end, close).some((x) => isOp(x, ':'))) fail();
+      subscripted = true;
+      end = close + 1;
+    }
+    const leaf = env.field(t, subscripted);
+    if (!leaf) fail();
+    i = end;
+    return leaf;
+  }
+  function term() {
+    let a = primary();
+    while (isOp(toks[i], '*') || isOp(toks[i], '/')) { const op = toks[i++].v; a = { k: 'bin', op, a, b: primary() }; }
+    return a;
+  }
+  function expr() {
+    let a = term();
+    while (isOp(toks[i], '+') || isOp(toks[i], '-')) { const op = toks[i++].v; a = { k: 'bin', op, a, b: term() }; }
+    return a;
+  }
+  return { expr, primary, done: () => i >= toks.length, at: () => i };
+}
+
+// Runs a parse, giving null where the tokens are not something the model reads.
+export function attempt(fn) {
+  try { return fn(); } catch (e) { if (e === parser) return null; throw e; }
+}
+
+// ---- reading a tree against facts ---------------------------------------------------------------
+
+const union = (a, b) => [...new Set([...a, ...b])].sort((x, y) => x - y);
+const within = (a, b) => cmp(b.lo, a.lo) <= 0 && cmp(a.hi, b.hi) <= 0;
+
+// Drops what another candidate does at least as well: fewer facts needed and an interval inside.
+function prune(list, cap) {
+  const kept = [];
+  for (const c of list) {
+    if (kept.some((k) => k.needs.every((x) => c.needs.includes(x)) && within(k.iv, c.iv) && (!k.iv.inexact || c.iv.inexact))) continue;
+    for (let j = kept.length - 1; j >= 0; j--) {
+      const k = kept[j];
+      if (c.needs.every((x) => k.needs.includes(x)) && within(c.iv, k.iv) && (!c.iv.inexact || k.iv.inexact)) kept.splice(j, 1);
+    }
+    kept.push(c);
+  }
+  if (kept.length <= cap) return kept;
+  const plain = kept.filter((c) => !c.needs.length);
+  const rest = kept.filter((c) => c.needs.length).sort((a, b) => cmp(qSub(a.iv.hi, a.iv.lo), qSub(b.iv.hi, b.iv.lo)) || a.needs.length - b.needs.length);
+  return [...plain, ...rest].slice(0, cap);
+}
+
+// Every interval the tree can take, with the facts each needs. `field(leaf)` gives a leaf's own
+// candidates as { needs, lo, hi } with BigInt ends, the widest of them needing nothing.
+export function candidates(tree, field, cap = 64) {
+  const both = (a, b, fn) => {
+    const out = [];
+    for (const x of a) {
+      for (const y of b) {
+        const r = fn(x.iv, y.iv);
+        if (r) out.push({ needs: union(x.needs, y.needs), iv: r });
+      }
+    }
+    return prune(out, cap);
+  };
+  const walk = (t) => {
+    switch (t.k) {
+      case 'const': return [{ needs: [], iv: iv(t.v, t.v) }];
+      case 'range': return [{ needs: [], iv: iv(t.lo, t.hi) }];
+      case 'field': return prune((field(t) || []).map((c) => ({ needs: c.needs, iv: iv(q(c.lo), q(c.hi)) })), cap);
+      case 'neg': return walk(t.a).map((c) => ({ needs: c.needs, iv: ivNeg(c.iv) }));
+      case 'mod': return both(walk(t.a), walk(t.b), (a, b) => ivMod(a, b));
+      case 'bin': {
+        const fn = t.op === '+' ? ivAdd : t.op === '-' ? ivSub : t.op === '*' ? ivMul : ivDiv;
+        return both(walk(t.a), walk(t.b), fn);
+      }
+      default: return [];
+    }
+  };
+  return walk(tree);
+}
+
+// The fields a tree reads.
+export function leaves(tree, out = []) {
+  if (tree.k === 'field') out.push(tree);
+  else if (tree.a) { leaves(tree.a, out); if (tree.b) leaves(tree.b, out); }
+  return out;
+}