<!-- nornir:class: idiot -->
# provenance-diff — for idiots
> **Class:** `idiot`. Every step, nothing assumed. Goal: answer one question — **"did
> any build's provenance get worse since yesterday?"** — and know what to do when the
> answer is yes. If you already know the tool, read
> [`provenance-diff-guide.md`](provenance-diff-guide.md) instead. What "provenance"
> means at all is in [`for-idiots.md`](for-idiots.md).
## What this even is
Every time modgunn checks a build's signature, it writes down the result — "this build
is **VERIFIED** (good)" or "**REJECTED** (bad)" — in a little logbook that never gets
erased. `provenance-diff` reads two pages of that logbook, yesterday's and today's, and
tells you what changed.
The one thing you care about: a build that was **VERIFIED** yesterday and is
**REJECTED** today. modgunn calls that a **REGRESSION**. It means a build that used to
be trustworthy no longer is — someone changed the code, swapped the signer, or tampered
with it. That is the red row.
## Run this
Type this and press **Enter** (swap `/srv/wh` for wherever your warehouse lives):
```
modgunn warehouse provenance-diff --warehouse /srv/wh --fail-on-regression
```
That's it. It reads the logbook and prints what changed.
## Reading the answer
You get one line per build that changed, then a summary. The first character tells you
what happened:
- **`+`** a build that is now being checked for the first time. New, not scary.
- **`-`** a build that stopped being checked. Worth a glance.
- **`~`** a build whose result *changed*. Look at the tag in `[square brackets]`.
The tags on a `~` line:
- **`[recovered]`** — was bad, now good. 🎉 Nothing to do.
- **`[signer-changed]`** — same result, but a *different person/robot* signed it. Ask
"did we mean to change who signs our builds?"
- **`[REGRESSION]`** — **this is the red row.** Was good, now bad.
Example:
```
~ holger app@1.4.2 VERIFIED → REJECTED [REGRESSION] tampered
1 added, 0 removed, 1 changed (1 regression(s))
```
That says: the build `app@1.4.2` in the `holger` project used to pass and now fails, and
the reason recorded is "tampered".
## What a red row means, and what to do
A **`[REGRESSION]`** row means: **do not ship this build.** Something about how it was
built or signed no longer matches what you trust. In order, do this:
1. **Stop.** Don't promote or release that build.
2. **Read the reason** at the end of the line ("tampered", "untrusted signer", "commit
mismatch", …). It's the short version of *why* it failed.
3. **Get the details.** Run this to see the full history for that one build:
```
modgunn warehouse provenance-log --warehouse /srv/wh --id app@1.4.2
```
4. **Tell a human** who owns that project. Paste them the red line and the reason.
## The exit code (for scripts / robots)
If you put that command in a script or CI job, it tells the machine what happened
without anyone reading the text:
- exits **`0`** — no regressions. Safe to carry on.
- exits **`3`** — at least one regression. **Stop the pipeline.**
So a release gate is just:
```
modgunn warehouse provenance-diff --warehouse /srv/wh --fail-on-regression \
|| { echo "provenance got worse — refusing to release"; exit 1; }
```
If you *only* want to look and never block, drop `--fail-on-regression` — it will still
print the red rows but always exit 0.
## "It printed nothing but a summary"
If you see:
```
0 added, 0 removed, 0 changed (0 regression(s)) — provenance unchanged
```
that's the happy answer: **nothing got worse.** Every build's provenance is exactly
where it was. Go get coffee.
## Where to go next
- The full flag list (comparing specific days, one project at a time, enforcing rules
like "must be SLSA 3") — [`provenance-diff-guide.md`](provenance-diff-guide.md).
- Why it's built this way (the logbook, the regression signal) —
[`provenance-policy-and-diff.md`](provenance-policy-and-diff.md).
</content>