70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# Repro Bundle Profile (SLSA v1 + in-toto + DSSE)
|
|
|
|
## Status
|
|
- Planned contract (gap-closure track).
|
|
- Implementation sprint: `docs/implplan/SPRINT_20260209_001_DOCS_repro_bundle_gap_closure.md`.
|
|
|
|
## Purpose
|
|
- Define the minimum reproducibility evidence required for release promotion.
|
|
- Standardize canonicalization rules so rebuild and verification outcomes are deterministic.
|
|
- Preserve online and offline parity for transparency verification workflows.
|
|
|
|
## Required bundle contents (per artifact)
|
|
1. `build_provenance.json` with SLSA v1 predicate fields:
|
|
- `builder.id` and `builder.version`
|
|
- source binding (`invocation` and commit)
|
|
- `materials[]` with pinned digests
|
|
- canonicalized build command representation
|
|
- pinned toolchain digest (`@sha256:...`)
|
|
2. `in_toto.link` mapping materials to products with deterministic digests.
|
|
3. DSSE signatures/envelopes for provenance and link payloads.
|
|
4. Transparency evidence:
|
|
- Online mode: Rekor entry metadata.
|
|
- Offline mode: local checkpoint/tile bundle and verification metadata, including Rekor leaf hash (`leafHash`), path hashes, and checkpoint root.
|
|
|
|
## Canonicalization policy (fail-closed)
|
|
- Paths and filenames must be Unicode NFC.
|
|
- JSON payloads must be canonicalized with sorted keys and deterministic encoding.
|
|
- PURLs/material references must be pinned, digest-backed, and deterministically ordered.
|
|
- Archive outputs must use deterministic metadata/order:
|
|
- fixed timestamps (policy default: zero epoch)
|
|
- stable uid/gid and owner names
|
|
- fixed mode policy
|
|
- Line endings must be normalized (policy default: LF).
|
|
- Build environments must pin deterministic settings:
|
|
- `LC_ALL=C`
|
|
- `TZ=UTC`
|
|
- stable source date epoch
|
|
- Toolchains must be digest-pinned; mutable tags are non-compliant in strict mode.
|
|
|
|
## Verification modes
|
|
### Online mode
|
|
- Verify DSSE signatures.
|
|
- Verify SLSA/in-toto policy compliance.
|
|
- Verify Rekor inclusion against trusted log/checkpoint state.
|
|
|
|
### Offline mode
|
|
- Verify DSSE signatures with bundled trust roots/keys.
|
|
- Verify bundled inclusion proof data cryptographically (leaf hash + Merkle path + checkpoint root) without network.
|
|
- Missing/invalid proof material is fail-closed by default.
|
|
- If break-glass verification is allowed, it must be explicitly configured and recorded in evidence with machine-readable marker(s).
|
|
|
|
## Promotion gate contract
|
|
- Promotion must block when any required repro evidence is missing or invalid.
|
|
- Promotion must block when canonicalization policy fails.
|
|
- Promotion must block when toolchain digest pinning is absent.
|
|
- Gate output must include stable rejection codes and references to failed evidence files for replay.
|
|
|
|
## Component ownership map
|
|
- `Attestor`: strict predicate validation, DSSE handling, Rekor verification (online/offline).
|
|
- `ReleaseOrchestrator`: fail-closed promotion gate enforcement and policy simulation.
|
|
- `EvidenceLocker`: storage/export contracts for repro-bundle artifacts and offline verification packs.
|
|
- `Provenance`: provenance model extensions and deterministic serialization support.
|
|
- `devops`: deterministic build/container/pipeline defaults and toolchain pinning.
|
|
|
|
## Test expectations
|
|
- Deterministic fixtures for valid and invalid bundles.
|
|
- Unit + integration coverage for canonicalization policy and strict validation.
|
|
- End-to-end coverage for online and offline promotion checks.
|
|
- Negative tests for each fail-closed rule.
|