mikronova/modgunn

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 instead. What "provenance" means at all is in 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

1. 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.
• Why it's built this way (the logbook, the regression signal) — provenance-policy-and-diff.md.