# keryn ledger build

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> keryn ledger build: one merged, deduplicated, reproducible findings ledger from ci/stage directories; compare two ledgers

Source: https://keryn.dev/docs/reference/cli/ledger-build/

> **Caution: Next release: keryn ledger build**
> On main; not in Keryn 0.5.2, the latest release.

One merged, deduplicated, reproducible findings ledger from ci/stage directories; compare two ledgers.

```text
keryn ledger build <run-or-stage-dir>... --out <new-file.json> [--json]
```

## Options

```text
Usage: keryn ledger build <run-or-stage-dir>... --out <new-file.json> [--json]
       keryn ledger diff <old-ledger.json> <new-ledger.json> [--json]
  build merges every stage of one or more keryn ci run directories, or single sca/dast/scan/artifact stage directories, into one
  keryn.dev/ledger/v1 document: one entry per distinct finding with normalised and original severities, stage/tool provenance,
  every location, and evidence citing each per-stage artifact by relative path (its sha256 is in the run's evidence.json, so two
  runs with identical results give identical ledger bytes). Keys: source keryn-fp/v1; secrets path +
  line across tools; dependencies ecosystem + package + version + manifest + canonical advisory with aliases folded; web rule +
  normalised URL path + parameter with the affected URLs; binary artifact sha256 + member + rule. Nothing is dropped: merged
  observations stay as evidence with the merge reason. Paths are target-relative; no timestamps; same inputs give the same bytes.
  Each stage records what makes a re-run differ (OSV-Scanner version and advisory database or "unknown", ZAP and add-on versions,
  a digest of the target's reported answers). keryn ci writes ledger.json at the end of every run.
  diff compares entry ids: new, fixed, unchanged, changed severity, and stages whose recorded inputs changed.
  With runtime observations (keryn import runtime, IAST on) it also lists entries that moved between INFERRED and OBSERVED with the
  tests behind them, and observed flows the newer run lacks: fixed only when the tests that produced them ran again, otherwise
  "not re-observed". Neither changes the exit code.
  Exit (build) 0 written | 2 usage/unreadable input. Exit (diff) 0 nothing new and no severity raised | 1 new or raised, or an
  observed-flow entry (one per function) seen at more places than before | 2 usage.
```

## Examples

```sh
# Same inputs give the same bytes.
keryn ledger build out/ci --out ledger.json
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | written |
| 2 | usage error or unreadable input |
