docs/security/slsa-provenance.md
Last updated: 2026-06-27
Related: PR #8277, RFC #8177
Scope: Release pipeline (release-stable-manual.yml — publish job)
When the best-effort attestation step succeeds, each release artifact gets a signed SLSA provenance attestation generated by actions/attest-build-provenance. The attestation proves:
"This file was produced by workflow run <ID> at commit <SHA> on <date> in repository zeroclaw-labs/zeroclaw."
Attestations are stored in GitHub's artifact attestation API and release assets include offline verification material:
<artifact>.attestation.jsonl — downloaded attestation bundle for that artifacttrusted_root.jsonl — Sigstore/GitHub trusted root material for offline verificationATTESTATION-BUNDLES.md — artifact-to-bundle index with SHA256 digests| Threat | Covered? | Explanation |
|---|---|---|
| Attacker creates a fake release with tampered binaries | ✅ | If attestation succeeded for the real release, it proves the artifact came from a real GH Actions run at a specific commit |
| Attacker gains write access to Releases page, swaps artifact files | ✅ | If attestation succeeded for the original artifact, swapped files won't match the attested hash |
| Developer machine compromised, attacker pushes a tag | ✅ | If the release workflow attests the artifact, provenance traces back to the CI workflow run, not a local build |
| Threat | Covered? | Why |
|---|---|---|
| Compromised GitHub Actions runner | ❌ | Attestation runs on the same runner. An attacker controlling the runner can tamper with files before or after the attestation step. |
| Malicious dependency injected during build | ❌ | Attestation proves origin, not content correctness. A backdoored dependency compiles into the binary; provenance won't catch it. SBOM generation is tracked separately in PR #8158. |
| GitHub internal OIDC key compromise | ❌ | Trust is rooted in GitHub's OIDC infrastructure. If GitHub's signing keys are compromised, attestations can be forged. |
| Binaries contain malware or vulnerabilities | ❌ | Attestation says "who built this", not "this is safe to run". Code review, SAST, and SBOM analysis cover that separately. |
| Tampering after the attestation step but before upload | ⚠️ Partial | The attestation step runs on the same runner as the release steps. A runner-level attacker can tamper, but the attestation hash would mismatch when verified. |
User verifies artifact
│
├── gh CLI contacts GitHub's attestation API
│ (or reads a local attestation bundle + trusted root)
│
├── Signature verified against GitHub's OIDC public key
│
└── Result: "artifact matches workflow run X at commit Y"
Root of trust: GitHub's OIDC signing key (managed by GitHub)
Phase A — best-effort. Attestation is generated in GitHub's artifact attestation API and exported as release-asset bundles for offline verification. A failure does not block the release (continue-on-error: true). Purpose: learn failure modes, verify the pipeline works end-to-end.
Planned: Phase B (not yet scheduled). Promote attestation to a hard gate
(continue-on-error: false) once Phase A has stabilized.
See the Verify SLSA Provenance section in every release's notes.
Online:
gh attestation verify <artifact> \
--repo zeroclaw-labs/zeroclaw \
--signer-workflow zeroclaw-labs/zeroclaw/.github/workflows/release-stable-manual.yml \
--source-digest <commit-sha>
Offline:
gh attestation verify <artifact> \
--repo zeroclaw-labs/zeroclaw \
--signer-workflow zeroclaw-labs/zeroclaw/.github/workflows/release-stable-manual.yml \
--source-digest <commit-sha> \
--bundle <artifact>.attestation.jsonl \
--custom-trusted-root trusted_root.jsonl