Hypermedia Security: Build Provenance Requirements
v1.0Hypermedia Au
Security requirements for establishing verifiable provenance of container image builds, ensuring traceability from source code to deployed artifact.
PROV-001 Trusted Build Environment MUST
All production container images MUST be built in a trusted, auditable build environment. GitHub Actions with OIDC token authentication is the approved build environment. Builds must be initiated only from the main branch and executed in ephemeral runners to prevent tampering.
A trusted build environment ensures that container images are built from verified source code in a controlled, auditable pipeline. GitHub Actions provides cryptographic identity binding through OIDC tokens, creating non-repudiatable build provenance.
- build-platform
- GitHub Actions
- authentication-method
- OIDC
- runner-type
- ephemeral
- branch-restriction
- main
PROV-002 Verified Source Code Provenance MUST
All container images MUST be built from source code in a verified Git repository with commit SHA recorded in the build provenance. The git commit SHA must be cryptographically linked to the resulting container image digest through signed attestations.
Source code provenance establishes the exact source code version used to build an artifact. Recording the git SHA creates bidirectional traceability between source and artifact, enabling security audits and vulnerability analysis.
- vcs-type
- git
- commit-sha-required
- true
- signature-required
- true
PROV-003 Build Reproducibility SHOULD
Container image builds SHOULD be reproducible, meaning that building from the same source code commit with the same build parameters produces bit-identical results. Build metadata including environment variables, tool versions, and timestamps must be recorded.
Reproducible builds allow independent verification that a binary artifact matches its claimed source code. While not always achievable, recording detailed build metadata enables forensic analysis and supply chain verification.
- reproducibility-level
- best-effort
- metadata-recording
- required
- tool-versions
- recorded
PROV-004 Cryptographic Attestation Signing MUST
Build provenance attestations MUST be cryptographically signed using Sigstore/Cosign with keyless signing via GitHub Actions OIDC. Signatures must be verifiable by consumers without requiring access to private keys. All signatures must be recorded in the Sigstore transparency log (Rekor).
Cryptographic signing with keyless infrastructure eliminates key management burden while providing non-repudiatable proof of build identity. The transparency log provides public auditability of all signing events.
- signing-method
- sigstore-cosign
- key-type
- keyless-oidc
- transparency-log
- rekor
- verification-public
- true
PROV-005 Complete Build Audit Trail MUST
All builds MUST record a complete audit trail including build trigger event, workflow definition, runner environment, build duration, and build URL. This audit trail must be included in the build provenance attestation and remain accessible for the lifetime of the artifact.
A complete audit trail enables post-incident forensics and supply chain security analysis. Recording the build URL provides a hypermedia link to the full build logs and execution context.
- audit-fields
- triggerworkflowrunnerdurationurl
- retention
- artifact-lifetime
- accessibility
- organization-wide