Proposal: build provenance chain with per-wheel attestations

[LalatenduMohanty]

Problem

Organizations that build Python wheels from source with fromager need to answer: was every package in this tree built from the claimed source, by a known builder, with known tools? Fromager does not record or verify that today.

Existing standards address a narrower scope:

Mechanism	What it verifies
PyPI publish attestations (PEP 740)	One published wheel ↔ one source repo
SLSA / Sigstore	One artifact at a time
Fromager SBOM (sbom.py)	Package identity in the built wheel, not build-dependency chain

None of these cover build dependencies — the packages installed into the build environment before a wheel is compiled. A compromised build-time dependency can affect every downstream wheel without any cross-package check.

Fromager already builds the full dependency tree in topological order (bootstrap roots first, then layers that depend on them). Each layer's build deps exist in wheels-repo/ before the next layer builds. That ordering is the right foundation for a provenance chain, but fromager does not use it yet:

• No SHA-256 hashes recorded for built wheels or downloaded sdists
• Sdist download URLs often include #sha256= fragments; fromager does not verify them (sources.py)
• No structured build-environment snapshot per wheel
• No attestation documents linking a wheel to its build-dep attestations

Related open work: #1200 (CI metadata in SBOM annotations) records which pipeline built a wheel but not what build deps were used.

Proposal

Add an opt-in provenance feature that, for each built wheel:

1. Records SHA-256 digests of the sdist input and output wheel
2. Captures build environment metadata (Python version, platform, compiler, fromager version, allowlisted env vars)
3. Generates an attestation document (in-toto Statement v1 / SLSA Provenance v1 predicate) referencing each build dependency's attestation by digest
4. Optionally signs attestations
5. Provides fromager verify to walk the dependency tree and check chain integrity

The key field is attestationDigest in resolvedDependencies — each build dep points to its own attestation, forming a tree verifiable from any top-level wheel down to bootstrap roots (flit_core, setuptools, etc.).

Trust model

Fromager acts as builder and attester for packages it builds from source:

1. Source integrity: hash sdists at download; verify PyPI URL #sha256= fragments; fail on mismatch
2. Bootstrap roots: simplest attestations (source in, wheel out, environment recorded)
3. Chain construction: before installing a build dep, verify its wheel bytes match the hash in the attestation from the current run; repeat layer by layer
4. Output integrity: after each build, hash the wheel and write an attestation referencing build-dep attestation digests

This establishes build integrity (known bytes, known builder, no tampering between layers). It does not establish source trustworthiness (whether upstream code is safe).

Pre-built wheels (not built by fromager) break the chain. Recommended handling: mark as unattested-prebuilt in the attestation; verify warns unless --allow-prebuilt.

Attestation example (abbreviated)

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [{ "name": "scipy-....whl", "digest": { "sha256": "..." } }],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://fromager.readthedocs.io/provenance/v1",
      "externalParameters": {
        "source": { "uri": "...", "digest": { "sha256": "..." } }
      },
      "resolvedDependencies": [{
        "name": "numpy-....whl",
        "digest": { "sha256": "..." },
        "attestationDigest": { "sha256": "..." }
      }]
    },
    "runDetails": {
      "builder": { "id": "..." },
      "environment": { "python": "3.12.3", "compiler": "gcc-14.1", "fromager": "0.88.0" }
    }
  }
}

Storage (no graph.json changes)

Keep graph.json unchanged. Store provenance separately:

work-dir/provenance-index.json          # package key → digests + sidecar paths
wheels-repo/downloads/{wheel}.attestation.json
wheels-repo/downloads/{wheel}.attestation.json.sig          # when GPG signing enabled
wheels-repo/downloads/{wheel}.attestation.json.sigstore.json  # when Sigstore signing enabled

Lightweight integrity/env JSON may be embedded in .dist-info/ (same pattern as SBOM). Full attestations and signatures stay as sidecars to avoid repack-on-sign.

Integration points

Step	Module	Hook
Source download	sources.py	hash + verify URL fragment
Before build-dep install	bootstrapper.py	verify build-dep wheel hash + attestation
After wheel build	wheels.py	embed integrity/env; write attestation sidecar
Post-build	new commands/verify.py	fromager verify walks topology

New module: provenance.py (hashing, environment capture, attestation generation, chain verification). Settings gate via provenance.enabled in package settings (mirrors SBOM opt-in pattern).

Suggested phases

Phase	Scope
1	SHA-256 sdists/wheels; URL fragment verify; provenance-index.json
2	Build environment capture
3	Attestation generation + fromager verify
4	Optional signing + verify --signatures

Phases 1–3 deliver unsigned attestations and chain verification. Phase 4 adds signature sidecars via a provenance.signing setting:

• GPG — detached .sig files; works offline; suited to private indexes and air-gapped builders.
• Sigstore — keyless signing via OIDC in CI; produces a .sigstore.json bundle. The default public Sigstore flow also writes to Rekor, which publishes the signing identity and artifact digest — worth considering when choosing a backend for non-public artifacts.

Each phase is independently mergeable; later phases no-op when provenance.enabled: false.

Optional follow-up (lower priority): verify PyPI PEP 740 sdist attestations on download when available (verify_if_present mode).

Non-goals

• Key management infrastructure (HSM, KMS, rotation policies)
• Replacing PyPI publish attestations (complementary, not competing)
• Reproducible builds verification (provenance ≠ reproducibility)
• Modifying graph.json schema

Happy to contribute a docs/proposals/ write-up and phased PRs if there is interest.

References

• SLSA Provenance v1
• in-toto Statement v1
• Sigstore overview
• Rekor transparency log
• PyPI publish attestations

[LalatenduMohanty]

Open question: where should provenance data live — inside the wheel or beside it?

Each built wheel could carry provenance in two places:

1. Inside the wheel (under .dist-info/, like the existing SBOM)
2. Beside the wheel as separate files in wheels-repo/downloads/ (sidecars)

What	Inside wheel?	Sidecar?	Why
Source + wheel SHA-256 hashes	Yes (small)	Also in index	Check integrity without extra files
Build environment (Python, compiler, OS)	Yes (small)	Also in index	Useful if the wheel travels alone
Full attestation JSON (build-dep chain)	Maybe	Yes	Large; changes if you sign later
Signature (GPG .sig or Sigstore bundle)	Maybe	Yes	Signing happens after build; embedding forces repacking the wheel

Tradeoff:

• Embed everything → wheel is self-contained, but bigger, and signing means rebuilding/repacking the wheel.
• Sidecar only → simpler build flow, but consumers need the wheel and the .attestation.json (and signature file) together.
• Hybrid (current leaning) → embed only the small, stable pieces (hashes + env); keep the full attestation and signatures as sidecars.

Example with the hybrid approach:

wheels-repo/downloads/
  numpy-1.26.4-....whl
  numpy-1.26.4-....whl.attestation.json         # full chain (sidecar)
  numpy-1.26.4-....whl.attestation.json.sig     # signature (sidecar)

# Inside the wheel (.dist-info/):
  fromager-integrity.json    # hashes only
  fromager-build-env.json    # env snapshot

Is that split right, or do downstream users need the full attestation embedded in the wheel?

[LalatenduMohanty]

Open question: use standard SLSA as-is, or add a fromager-specific field?

Attestations would use the standard in-toto Statement envelope with the SLSA Provenance v1 predicate — the same formats PyPI attestations and Sigstore use.

SLSA's resolvedDependencies lists build inputs by name and digest:

"resolvedDependencies": [{
  "uri": "pkg:pypi/numpy@1.26.4",
  "digest": { "sha256": "abc..." }
}]

That tells you which wheels were installed during the build, but not how to find their attestations to continue verifying up the tree.

Fromager needs one extra link per build dependency — a pointer to that dependency's attestation document, so fromager verify can walk the chain recursively:

"resolvedDependencies": [{
  "name": "numpy-1.26.4-....whl",
  "digest": { "sha256": "abc..." },
  "attestationDigest": { "sha256": "def..." }
}]

The choice:

Approach	Pros	Cons
Pure SLSA v1	Maximum interoperability; no custom fields	No standard way to chain attestations; verify logic can't walk the tree
SLSA v1 + attestationDigest	Chain verification works; still uses standard envelope and predicate type	Custom field not in the SLSA spec; needs documenting as a fromager extension
Entirely custom predicate	Full freedom	Loses interoperability with SLSA/Sigstore/PyPI tooling

Current leaning: keep the standard SLSA Provenance v1 predicate and document attestationDigest as a fromager extension in resolvedDependencies. Verifiers that don't understand the extension can still read name + digest; fromager's verify uses the extra field for chain walking.

Is a documented extension field acceptable, or should we pursue getting something like attestationDigest into a future SLSA revision?

[LalatenduMohanty]

fromager verify — what it is

A read-only command that checks wheel digests and attestation links across a
fromager output directory (-O ./output) or release tarball. --signatures
adds GPG/Sigstore checks. Local files only — not an index or pip install
checker.

Strongest use case: release promotion

Build-time checks already catch bad sdists and build-dep wheels during the
build. verify matters most before promoting a release — QE confirms the
tarball's wheels and attestations are still consistent after bundling and
transfer, without re-bootstrapping.

[rd4398]

I like this idea as it highlights some gaps we have in fromager and how we can improve it. I especially like phase 1 which has the highest ROI. We can make it a standalone PR as it is the most concrete security win with the least architectural risk

I would like to contribute to this feature as well.