# 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)