Files

master 644887997c test fixes and new product advisories work

2026-01-28 02:30:48 +02:00

8.2 KiB

Raw Blame History

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:

Release artifacts - Binaries, container images, and archives
Checksums - SHA-256 and SHA-512 hashes for all artifacts
Signatures - Cosign signatures for cryptographic verification
SBOMs - Software Bill of Materials in CycloneDX format
Provenance - SLSA v1.0 provenance statements
Rekor proofs - Transparency log inclusion proofs (optional)
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:

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

# Run the verification script
./verify.sh

On Windows (PowerShell 7+):

./verify.ps1

Verify (Manual Method)

If you prefer to verify manually without running scripts:

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

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:

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:

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

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:

{
  "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:

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

Re-download the artifact
Verify the download completed (check file size)
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:

cosign verify-blob \
  --certificate-identity "https://ci.stella-ops.org" \
  --certificate-oidc-issuer "https://oauth2.sigstore.dev/auth" \
  --signature artifact.sig \
  artifact

Security Considerations

Verify the evidence pack itself - Download from official sources only
Check the signing key - Compare cosign.pub fingerprint against published key
Verify provenance - Ensure builder ID matches expected CI system
Use transparency logs - When possible, verify Rekor inclusion

8.2 KiB Raw Blame History