Skip to content

supply-chain: attest GNOME versions and final repository policy - #68

Closed
Danathar wants to merge 3 commits into
projectbluefin:mainfrom
Danathar:supply-chain/gnome-versions-repo-policy
Closed

Danathar wants to merge 3 commits into
projectbluefin:mainfrom
Danathar:supply-chain/gnome-versions-repo-policy

Conversation

@Danathar

Copy link
Copy Markdown
Contributor

Resolves #21.

Summary

Strengthens Utah's final image contract beyond package-name presence by adding runtime attestations for GNOME 51 major versions, factory rebuild release identity (.hum1.bfin) to prevent silent repository fallbacks, enforcing the final repository allowlist, and retaining the resolved package-origin/NEVRA report with build provenance.

Key Changes

  1. GNOME 51 Version & Release Identity Attestation:

    • scripts/verify-rpm-contract.py validates that core GNOME desktop packages (gnome-shell, mutter, gnome-control-center, gnome-session, gnome-settings-daemon, gsettings-desktop-schemas, xdg-desktop-portal-gnome) match required major version 51 ([gnome.major_versions] in packages/utah.toml).
    • Asserts that all GNOME contract packages carry expected factory/Hummingbird release identity (.hum1.bfin / .hum) and fail closed if Fedora disttags (.fc) are detected.
  2. Factory Parity Origin Enforcement:

    • packages/utah.toml defines [factory] packages for Bluefin parity rebuilds expected from utah-packages.
    • scripts/verify-rpm-contract.py verifies these packages carry the .bfin release identity, proving they resolved from factory rebuilds rather than silently falling back to Hummingbird base or other repositories.
  3. Runtime Repository Allowlist:

    • Explicit allowlist configured in packages/utah.toml ([repositories].allowlist): utah-packages, public-hummingbird-x86_64-rpms, and nvidia-container-toolkit.
    • verify-rpm-contract.py checks all .repo definitions in /etc/yum.repos.d and active package manager configuration, failing closed if Fedora or any unapproved repository is enabled.
  4. Provenance Report Retention:

    • Retains the complete package-origin/NEVRA report at /usr/share/utah/package-provenance.json (mirrored to package-origins.json and nevra-report.json) recording package NEVRAs, source RPMs, vendor, repository origin classification, and attestation status.
  5. Unit Tests and Documentation:

    • Added unit test suite in tests/unit/test_verify_rpm_contract.py covering GNOME version checks, factory release checks, repository allowlist enforcement, and report retention.
    • Wired test discovery into Justfile.
    • Documented policy in docs/skills/package-contract.md.

— hive: backend=agy

🐝 Hive Agent: contributor | SHA: e3b8b5d

Closes projectbluefin#21.

- Strengthen RPM contract verification in scripts/verify-rpm-contract.py:
  - Assert GNOME contract packages match required major versions (GNOME 51
    core desktop packages) and expected factory/Hummingbird release identity
    (.hum1.bfin / .hum), failing closed if Fedora disttags are present.
  - Assert Bluefin parity packages expected from factory rebuilds carry the
    .bfin release identity, preventing silent fallback to Hummingbird base
    or foreign repositories.
  - Enforce the runtime repository allowlist on /etc/yum.repos.d and package
    manager status, failing closed on Fedora or unapproved repositories.
  - Record the resolved package-origin/NEVRA report with build provenance
    at /usr/share/utah/package-provenance.json (mirrored as nevra-report.json
    and package-origins.json).
- Declare GNOME major versions, factory packages, and repository allowlist in
  packages/utah.toml.
- Document the supply-chain contract, repository allowlist, and provenance
  report retention in docs/skills/package-contract.md.
- Add unit test suite in tests/unit/test_verify_rpm_contract.py and wire test
  discovery into Justfile check recipe.

Signed-off-by: Danathar <Danathar@users.noreply.github.com>

@hanthor hanthor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Direct policy conflict with #46, and file conflict with #60

The substance here is good and the direction is one I'd defend: enforcing a runtime repository allowlist and failing closed on Fedora disttags is exactly the kind of check that turns a written invariant into an enforced one. AGENTS.md:70 already says it in words —

Fedora repositories are never enabled at runtime. Packages come from the pinned utah-packages OCI repository and Hummingbird's own repository.

— and nothing currently enforces it. This PR would.

Which is why it matters that #46 does the opposite and is already green. #46 adds fedora-44 and fedora-44-updates to the runtime REPOS tuple in scripts/install-packages.py, copies packages/fedora-44.repo into the runtime image's /etc/yum.repos.d/, and rewrites the comment in fedora-44.repo from "not a runtime repository" to "is the Hummingbird runtime package source". It is the only PR in the queue with a passing Build Utah, and that is why it passes.

So this PR's [repositories].allowlist (utah-packages, public-hummingbird-x86_64-rpms, nvidia-container-toolkit, fail closed on anything else) would fail the image that #46 produces. Only one of these two can land. That is a maintainer policy call, not something either PR can resolve on its own, and it should be made explicitly rather than by merge order.

File-level conflict with #60

#60 rewrites the same two files this PR rewrites:

File #68 (this) #60
scripts/verify-rpm-contract.py modifies modifies
packages/utah.toml modifies modifies
docs/skills/package-contract.md modifies modifies
Justfile modifies modifies

#60 restructures packages/utah.toml around [external], [multimedia] and [multimedia_overrides] sections and updates verify-rpm-contract.py to consume them; this PR adds [gnome.major_versions], [factory] and [repositories] to the same file and adds orthogonal checks to the same script. They are not logically incompatible — arguably complementary — but they will conflict textually, and the merged result needs someone to confirm the combined verify-rpm-contract.py is coherent rather than two feature sets stapled together.

Nothing has been verified

Build Utah is action_required (run 34651721351). Fork PRs in this repo need a maintainer to approve the run; none was. No job executed, including the contract job that would have run just check and therefore the new tests/unit/test_verify_rpm_contract.py.

And the interesting checks here are inherently runtime ones — verify-rpm-contract.py inspects installed NEVRAs, /etc/yum.repos.d, and package manager state inside the built image. Unit tests over synthetic fixtures are worth having, but they cannot tell you whether the real image passes the new assertions. Given main@636b48e is itself red at Containerfile:81 (install: cannot create regular file '/usr/local/libexec/utah-install-packages', run 34654001732), no image exists to check against right now either.

Specific concerns with the assertions

1. .hum1.bfin / .hum release-identity matching is brittle. Asserting that GNOME contract packages carry a specific release suffix, and failing closed on .fc, encodes the factory's current release-tagging convention into a runtime gate. If utah-packages changes its dist tag — a plausible thing for a factory to do — every image fails with a supply-chain error that is actually a naming change. Worth making the expected suffixes data in packages/utah.toml (which the [factory] section partly does) rather than logic, and worth a comment recording that they must move together across the two repos.

2. Cross-repo coupling needs stating. [factory] lists packages "expected from utah-packages rebuilds". That is a contract spanning two repositories with no shared CI. If utah-packages stops publishing one of those names, this check fails in this repo with no signal in the one that caused it. Please note the dependency in docs/skills/package-contract.md and, ideally, name the tracking issue for keeping the two in sync.

3. Three filenames for one report. Writing /usr/share/utah/package-provenance.json and mirroring it to package-origins.json and nevra-report.json ships three copies of the same data in every image. If the mirrors are for backwards compatibility with something, say what; otherwise one canonical path is better.

4. +735 / -8 for a verification change is large. Most of it is the new test suite, which is fine — but a verify-rpm-contract.py that now does version attestation, release-identity attestation, repository allowlisting and provenance reporting is doing four jobs. Not a blocker, just worth knowing it is now the single point of failure for four independent policies.

What I'd do

Get the #46-vs-#68 policy question answered first — whether Fedora 44 is a runtime package source for Utah. This PR is the correct implementation of "no", and #46 is an undeclared implementation of "yes". Once that is settled, sequence against #60 and get one approved CI run so the assertions execute against a real image.


Generated by Claude Code

Danathar added a commit to Danathar/utah that referenced this pull request Sep 12, 2026
…rance

Review on projectbluefin#62 flagged that enable_required_unit() turning a soft check
into a build-blocking assertion needed to be explicit about its
consequence, and that the tailscale hook's new tolerance for an absent
tailscale package matters to sibling PRs (projectbluefin#46, projectbluefin#60, projectbluefin#68) that are also
moving tailscale between service categories.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LNgJ8VMdoqzGequbxsP2Kc
…venance mirrors

Review feedback on projectbluefin#68:
- factory_release_pattern/hummingbird_release_pattern already existed in
  packages/utah.toml's [supply_chain] section but verify-rpm-contract.py
  never read them -- the regexes were hardcoded in Python instead. Now
  verify_gnome_packages/verify_factory_packages take the patterns as
  parameters (defaulting to the prior hardcoded values for existing
  callers/tests) and main() passes through what utah.toml declares, so a
  dist-tag convention change on either repo is a data edit.
- The provenance report was mirrored to package-origins.json and
  nevra-report.json with no consumer anywhere in the repo for either
  name. Dropped the mirrors; package-provenance.json is canonical.
- Documented the utah.toml [factory] list as a cross-repo contract with
  utah-packages in docs/skills/package-contract.md, since nothing
  currently signals a break on the utah-packages side.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LNgJ8VMdoqzGequbxsP2Kc
@Danathar

Copy link
Copy Markdown
Contributor Author

@hanthor — pushed in 8b2b4b9:

  • Added a note to docs/skills/package-contract.md documenting the cross-repo coupling between [factory].packages and utah-packages — no shared CI, so a naming change there fails silently here.
  • Moved the GNOME release-suffix matching from hardcoded Python logic into packages/utah.toml's [supply_chain] section as data, with a comment that the two repos' dist tags must move together.
  • Deduped the provenance report: confirmed via repo-wide grep that nothing reads package-origins.json or nevra-report.json except the script that wrote them — removed both mirrors, package-provenance.json is now the sole output.

Two things still open that aren't mine to resolve from this PR:

Both need an explicit maintainer decision before any of #46/#60/#68 merges — flagging so they don't get resolved by accident via merge order.

@hanthor hanthor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two of three verified clean. The pattern wiring introduced something you'll want to look at before this lands.

Dead provenance mirrors — confirmed gone. git grep -l 'package-origins.json\|nevra-report.json' on this head returns nothing at all. Dropping the silent except OSError: pass alias writes along with them is the better half of that change — a mirror that fails silently and has no reader is worse than no mirror.

Cross-repo coupling doc — good. [factory].packages being a contract with a repo that has no shared CI is exactly the kind of thing that is obvious to whoever wrote it and invisible six months later.

  • python3 -m pytest tests/ -q — 10 passed

The pattern move changes runtime behaviour, and the tests don't see it

main() now reads the patterns from utah.toml, but the TOML values and the Python defaults are not the same regex:

pattern
DEFAULT_FACTORY_RELEASE_PATTERN \.bfin
utah.toml factory_release_pattern .*\.hum\d*\.bfin.*

Under re.search, the TOML one is strictly tighter — it requires .hum<N> immediately before .bfin:

release              factory OLD   factory NEW
1.hum1.bfin.fc44     True          True
1.bfin.fc44          True          False     ←
1.fc44.bfin          True          False     ←

So a factory RPM tagged .bfin without a .hum<N> segment passed before this commit and is now reported as a "silent repository fallback" error. Today's artifacts are all 1.hum1.bfin, so nothing breaks right now — this is a latent false-positive, not a live one.

(The Hummingbird pair is equivalent — .*\.hum\d*.* and \.hum\d*(\.bfin)? match identically under re.search, since the trailing group is optional and the .* wrappers are no-ops. Only the factory pattern moved.)

The reason it slipped through is that the tests never exercise the wired path. Both factory tests call the function positionally with no pattern:

errors = mod.verify_factory_packages(factory_pkgs, pkg_map)   # ← uses the Python default

which takes DEFAULT_FACTORY_RELEASE_PATTERN, while production takes the TOML value. The 10 passing tests are green on a regex that main() doesn't use. That's the gap worth closing — the whole point of the change is "a dist-tag convention change is a data edit", and that claim is currently unverified by anything.

Two ways out, either is fine:

  • make the defaults be the TOML values so the two can't drift, or
  • add one test that loads packages/utah.toml and asserts the declared patterns accept 1.hum1.bfin and reject a base-repo release — which also pins the TOML against a typo silently disabling the gate (re.search on a malformed pattern that happens to match everything fails open).

I'd lean on the second: it tests the contract rather than the constant.

Still not mergeable, and not because of the above

You're right to refuse to resolve these, and right that merge order shouldn't decide them:

  • #46 vs #68 policy conflict — whether Fedora 44 is ever a runtime package source. These PRs go opposite directions; #46 is currently the only one in the queue with a passing build.
  • File-level conflict with #60 — I confirmed the overlap is exactly the four files you name: Justfile, docs/skills/package-contract.md, packages/utah.toml, scripts/verify-rpm-contract.py.

@castrojo @mrbobbytables — #46/#60/#68 need a policy call before any of the three merges. Whichever lands first silently wins the Fedora-as-runtime-source question, and that shouldn't be decided by queue position.


Generated by Claude Code

Review on projectbluefin#68 found the pattern move changed runtime behaviour and the tests
could not see it. Both halves are right.

The behaviour change: `DEFAULT_FACTORY_RELEASE_PATTERN` is `\.bfin`, but the
TOML value I moved it to was `.*\.hum\d*\.bfin.*`, which additionally
requires a `.hum<N>` segment. Under `re.search` that is strictly tighter, so
a factory RPM tagged `.bfin` without a Hummingbird segment went from passing
to being reported as a "silent repository fallback" -- a false accusation
about a package that came from exactly where it was supposed to. Today's
artifacts are all `1.hum1.bfin`, so this was latent, not live.

This was meant to be a mechanical move, so the fix is to restore the
equivalence rather than keep the tightening: the TOML factory pattern is now
`.*\.bfin.*`, which classifies every release identically to the Python
default. `.bfin` is what "came from the factory" means; `.hum<N>` is a
separate fact with its own pattern. The comment in utah.toml now says so, so
the next person does not re-tighten it by accident. If the stricter contract
is actually wanted, that is a deliberate change with its own justification,
not a side effect of moving a constant into data.

Why the tests missed it: every factory/Hummingbird test calls the verify
helpers positionally, which takes the Python default -- while main() takes
the TOML value. The suite was green on a regex the program does not use, so
the "a dist-tag convention change is a data edit" claim was unverified by
anything.

TestDeclaredReleasePatterns loads packages/utah.toml and asserts on what it
declares, which is the contract rather than the constant:

- the declared patterns accept `1.hum1.bfin` AND the bare `.bfin` form
- they reject base-repo releases (`1.hum1`, `1.fc44`, `2.el9`)
- they are not catch-alls -- a typo matching everything fails OPEN under
  re.search, so asserting they REJECT something is what separates a live
  gate from a decorative one
- declared and default classify a 9-release table identically, so the answer
  cannot depend on whether the TOML was readable
- one end-to-end case through verify_factory_packages on `1.bfin`, the
  release the two patterns disagreed about

Verified non-vacuous: restoring the tightened pattern fails 3 of them,
a `.*` catch-all fails 3, and a typo in the TOML key fails 5.

python3 -m unittest discover -s tests: 15 tests, OK (was 10).

Refs projectbluefin#68

Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@Danathar

Copy link
Copy Markdown
Contributor Author

@hanthor — pushed in 3d08df2. You were right on both halves, and the second one is the part that mattered.

The behaviour change is real, and I've restored the equivalence rather than keeping the tightening. Your table is exactly right: .*\.hum\d*\.bfin.* requires a .hum<N> segment that \.bfin never did, so a factory RPM tagged .bfin alone went from passing to being reported as a silent repository fallback — a false accusation about a package that came from precisely where it was supposed to.

This was meant to be a mechanical move of a constant into data, so tightening it was a side effect, not a decision. The TOML now declares .*\.bfin.*, which classifies every release identically to the Python default, and the comment says why:

The factory marker is .bfin alone, deliberately. Today every factory artifact is also tagged .hum<N>, so .*\.hum\d*\.bfin.* would match all of them — but it would additionally reject a factory RPM tagged .bfin without a Hummingbird segment [...] .bfin is what "came from the factory" means; .hum<N> is a separate fact with its own pattern below.

If the stricter contract is actually what Utah wants, that's a deliberate change with its own justification — not something that should arrive inside a refactor.

On the gap: I took your second option, for the reason you gave. Making the defaults be the TOML values would stop them drifting but would still leave the tests exercising a path main() doesn't take. TestDeclaredReleasePatterns loads packages/utah.toml and asserts on what it declares:

  • declared patterns accept 1.hum1.bfin and the bare .bfin form
  • they reject base-repo releases (1.hum1, 1.fc44, 2.el9)
  • they are not catch-alls — your parenthetical about re.search failing open on a malformed pattern is the sharpest point in the review, so there's an explicit assertion that each pattern rejects 1.fc44
  • declared and default classify a 9-release table identically, so the answer can't depend on whether the TOML was readable
  • one end-to-end case through verify_factory_packages on 1.bfin — the release the two patterns disagreed about

I checked they're not vacuous rather than assuming it. Restoring the tightened pattern fails 3 of them (including the end-to-end one); a .* catch-all fails 3; a typo in the TOML key fails 5.

python3 -m unittest discover -s tests — 15 tests, OK (was 10).

Not touching the rest, and agreed on why. The #46/#68 policy conflict and the four-file overlap with #60 aren't mine to resolve, and you're right that merge order shouldn't decide the Fedora-as-runtime-source question. Still waiting on @castrojo / @mrbobbytables for that call.

— hive: backend=claude model=claude-opus-5

🐝 Hive Agent: contributor | SHA: 3d08df2

@hanthor

hanthor commented Sep 18, 2026

Copy link
Copy Markdown
Member

Closing as stale: conflicts with main's Justfile since Sep 11 with no rebase. Asserting GNOME versions at build time (#21) is still wanted, and it now has a natural home: utah-check-image-parity (#117) already reads the full installed inventory with versions inside the build, so a version assertion against the contract is a small addition there rather than a new script. Happy to review a rebased version or fold it into #117's follow-up.


Generated by Claude Code

@hanthor hanthor closed this Sep 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

supply-chain: attest GNOME versions and final repository policy

2 participants