272 lines
8.2 KiB
Markdown
272 lines
8.2 KiB
Markdown
# Release Evidence Pack
|
|
|
|
This document describes the **Release Evidence Pack** - a self-contained bundle that allows customers to independently verify the authenticity and integrity of Stella Ops releases, even in air-gapped environments.
|
|
|
|
## Overview
|
|
|
|
Every Stella Ops release includes a Release Evidence Pack that contains:
|
|
|
|
1. **Release artifacts** - Binaries, container images, and archives
|
|
2. **Checksums** - SHA-256 and SHA-512 hashes for all artifacts
|
|
3. **Signatures** - Cosign signatures for cryptographic verification
|
|
4. **SBOMs** - Software Bill of Materials in CycloneDX format
|
|
5. **Provenance** - SLSA v1.0 provenance statements
|
|
6. **Rekor proofs** - Transparency log inclusion proofs (optional)
|
|
7. **Verification tools** - Scripts to verify everything offline
|
|
|
|
## Bundle Structure
|
|
|
|
```
|
|
stella-release-{version}-evidence-pack/
|
|
├── VERIFY.md # Human-readable verification guide
|
|
├── verify.sh # POSIX-compliant verification script
|
|
├── verify.ps1 # PowerShell verification script (Windows)
|
|
├── cosign.pub # Stella Ops release signing public key
|
|
├── rekor-public-key.pub # Rekor transparency log public key
|
|
├── manifest.json # Bundle manifest with all file hashes
|
|
├── artifacts/
|
|
│ ├── stella-{version}-linux-x64.tar.gz
|
|
│ ├── stella-{version}-linux-x64.tar.gz.sig
|
|
│ ├── stella-{version}-linux-arm64.tar.gz
|
|
│ ├── stella-{version}-linux-arm64.tar.gz.sig
|
|
│ ├── stella-{version}-macos-universal.tar.gz
|
|
│ ├── stella-{version}-macos-universal.tar.gz.sig
|
|
│ ├── stella-{version}-windows-x64.zip
|
|
│ └── stella-{version}-windows-x64.zip.sig
|
|
├── checksums/
|
|
│ ├── SHA256SUMS # Checksum file
|
|
│ ├── SHA256SUMS.sig # Signed checksums
|
|
│ └── SHA512SUMS # SHA-512 checksums
|
|
├── sbom/
|
|
│ ├── stella-cli.cdx.json # CycloneDX SBOM
|
|
│ ├── stella-cli.cdx.json.sig # Signed SBOM
|
|
│ └── ...
|
|
├── provenance/
|
|
│ ├── stella-cli.slsa.intoto.jsonl # SLSA v1.0 provenance
|
|
│ ├── stella-cli.slsa.intoto.jsonl.sig
|
|
│ └── ...
|
|
├── attestations/
|
|
│ └── combined-attestation-bundle.json
|
|
└── rekor-proofs/
|
|
├── checkpoint.json
|
|
└── log-entries/
|
|
└── {uuid}.json
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Download the Evidence Pack
|
|
|
|
Evidence packs are attached to every GitHub release:
|
|
|
|
```bash
|
|
# Download the evidence pack
|
|
curl -LO https://github.com/stella-ops/stella-ops/releases/download/v1.2.3/stella-release-1.2.3-evidence-pack.tgz
|
|
|
|
# Extract
|
|
tar -xzf stella-release-1.2.3-evidence-pack.tgz
|
|
cd stella-release-1.2.3-evidence-pack
|
|
```
|
|
|
|
### Verify (Quick Method)
|
|
|
|
```bash
|
|
# Run the verification script
|
|
./verify.sh
|
|
```
|
|
|
|
On Windows (PowerShell 7+):
|
|
|
|
```powershell
|
|
./verify.ps1
|
|
```
|
|
|
|
### Verify (Manual Method)
|
|
|
|
If you prefer to verify manually without running scripts:
|
|
|
|
```bash
|
|
# 1. Verify checksums
|
|
cd artifacts/
|
|
sha256sum -c ../checksums/SHA256SUMS
|
|
|
|
# 2. Verify checksums signature (requires cosign)
|
|
cosign verify-blob \
|
|
--key ../cosign.pub \
|
|
--signature ../checksums/SHA256SUMS.sig \
|
|
../checksums/SHA256SUMS
|
|
|
|
# 3. Verify artifact signatures
|
|
cosign verify-blob \
|
|
--key ../cosign.pub \
|
|
--signature stella-1.2.3-linux-x64.tar.gz.sig \
|
|
stella-1.2.3-linux-x64.tar.gz
|
|
```
|
|
|
|
## Verification Levels
|
|
|
|
The evidence pack supports multiple verification levels depending on your security requirements:
|
|
|
|
### Level 1: Checksum Verification (No External Tools)
|
|
|
|
Verify artifact integrity using standard Unix tools:
|
|
|
|
```bash
|
|
cd artifacts/
|
|
sha256sum -c ../checksums/SHA256SUMS
|
|
```
|
|
|
|
**What this proves:** The artifacts have not been modified since the checksums were generated.
|
|
|
|
### Level 2: Signature Verification (Requires cosign)
|
|
|
|
Verify that artifacts were signed by Stella Ops:
|
|
|
|
```bash
|
|
cosign verify-blob \
|
|
--key cosign.pub \
|
|
--signature artifacts/stella-1.2.3-linux-x64.tar.gz.sig \
|
|
artifacts/stella-1.2.3-linux-x64.tar.gz
|
|
```
|
|
|
|
**What this proves:** The artifacts were signed by the holder of the Stella Ops signing key.
|
|
|
|
### Level 3: Provenance Verification (SLSA)
|
|
|
|
Verify the build provenance matches expected parameters:
|
|
|
|
```bash
|
|
# Verify provenance signature
|
|
cosign verify-blob \
|
|
--key cosign.pub \
|
|
--signature provenance/stella-cli.slsa.intoto.jsonl.sig \
|
|
provenance/stella-cli.slsa.intoto.jsonl
|
|
|
|
# Inspect provenance
|
|
cat provenance/stella-cli.slsa.intoto.jsonl | jq .predicate
|
|
```
|
|
|
|
**What this proves:** The artifacts were built from a specific source commit using a specific builder.
|
|
|
|
### Level 4: Transparency Log Verification (Requires Network)
|
|
|
|
Verify the signatures were recorded in the Rekor transparency log:
|
|
|
|
```bash
|
|
rekor-cli verify \
|
|
--artifact artifacts/stella-1.2.3-linux-x64.tar.gz \
|
|
--signature artifacts/stella-1.2.3-linux-x64.tar.gz.sig \
|
|
--public-key cosign.pub
|
|
```
|
|
|
|
**What this proves:** The signature was publicly recorded at a specific time and cannot be repudiated.
|
|
|
|
## Offline Verification
|
|
|
|
The evidence pack is designed for air-gapped environments. All verification can be done offline except for Rekor transparency log verification.
|
|
|
|
For fully offline verification including Rekor proofs, the bundle includes pre-fetched inclusion proofs in `rekor-proofs/`.
|
|
|
|
## SLSA Compliance
|
|
|
|
Stella Ops releases target **SLSA Level 2** compliance:
|
|
|
|
| SLSA Requirement | Implementation |
|
|
|-----------------|----------------|
|
|
| Source - Version controlled | Git repository with signed commits |
|
|
| Build - Scripted build | Automated CI/CD pipeline |
|
|
| Build - Build service | GitHub Actions / Gitea Actions |
|
|
| Provenance - Available | SLSA v1.0 provenance statements |
|
|
| Provenance - Authenticated | Cosign signatures on provenance |
|
|
|
|
The SLSA provenance includes:
|
|
- **Builder ID**: The CI system that built the artifact
|
|
- **Source commit**: Git SHA of the source code
|
|
- **Build type**: The build recipe used
|
|
- **Resolved dependencies**: All build inputs with digests
|
|
- **Timestamps**: Build start and finish times
|
|
|
|
## Manifest Schema
|
|
|
|
The `manifest.json` file contains structured metadata:
|
|
|
|
```json
|
|
{
|
|
"bundleFormatVersion": "1.0.0",
|
|
"releaseVersion": "1.2.3",
|
|
"createdAt": "2025-01-15T10:30:00Z",
|
|
"sourceCommit": "abc123...",
|
|
"sourceDateEpoch": 1705315800,
|
|
"artifacts": [...],
|
|
"checksums": {...},
|
|
"sboms": [...],
|
|
"provenanceStatements": [...],
|
|
"attestations": [...],
|
|
"rekorProofs": [...],
|
|
"signingKeyFingerprint": "...",
|
|
"rekorLogId": "..."
|
|
}
|
|
```
|
|
|
|
## Build Reproducibility
|
|
|
|
Stella Ops releases are reproducible. Given the same source code and `SOURCE_DATE_EPOCH`, anyone can produce byte-identical artifacts.
|
|
|
|
To reproduce a build:
|
|
|
|
```bash
|
|
git clone https://git.stella-ops.org/stella-ops.org/git.stella-ops.org.git
|
|
cd git.stella-ops.org
|
|
git checkout <source-commit>
|
|
|
|
export SOURCE_DATE_EPOCH=<from-manifest>
|
|
make release
|
|
|
|
# Compare checksums
|
|
sha256sum dist/* | diff - path/to/evidence-pack/checksums/SHA256SUMS
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "cosign: command not found"
|
|
|
|
Install cosign from https://docs.sigstore.dev/cosign/installation/
|
|
|
|
### Checksum mismatch
|
|
|
|
1. Re-download the artifact
|
|
2. Verify the download completed (check file size)
|
|
3. Try a different mirror if available
|
|
|
|
### Signature verification failed
|
|
|
|
Ensure you're using the `cosign.pub` from the evidence pack, not a different key.
|
|
|
|
### Certificate identity mismatch
|
|
|
|
For keyless-signed artifacts:
|
|
|
|
```bash
|
|
cosign verify-blob \
|
|
--certificate-identity "https://ci.stella-ops.org" \
|
|
--certificate-oidc-issuer "https://oauth2.sigstore.dev/auth" \
|
|
--signature artifact.sig \
|
|
artifact
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
1. **Verify the evidence pack itself** - Download from official sources only
|
|
2. **Check the signing key** - Compare `cosign.pub` fingerprint against published key
|
|
3. **Verify provenance** - Ensure builder ID matches expected CI system
|
|
4. **Use transparency logs** - When possible, verify Rekor inclusion
|
|
|
|
## Related Documentation
|
|
|
|
- [SLSA Compliance](./SLSA_COMPLIANCE.md)
|
|
- [Reproducible Builds](./REPRODUCIBLE_BUILDS.md)
|
|
- [Offline Verification Guide](./offline-verification.md)
|
|
- [Release Process](./RELEASE_PROCESS.md)
|
|
- [Release Engineering Playbook](./RELEASE_ENGINEERING_PLAYBOOK.md)
|
|
- [Evidence Pack Schema](./evidence-pack-schema.json)
|