test fixes and new product advisories work
This commit is contained in:
master
271
docs/releases/RELEASE_EVIDENCE_PACK.md
Normal file
271
docs/releases/RELEASE_EVIDENCE_PACK.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user