test fixes and new product advisories work
This commit is contained in:
master
@@ -149,7 +149,25 @@ CI job fails if token expiry < 29 days (guard against stale caches).
|
||||
6. Verify SBOM attachment with `stella sbom verify stella/backend:X.Y.Z`.
|
||||
7. Run the release verifier locally if CI isn’t available (mirrors the workflow step):
|
||||
`python ops/devops/release/test_verify_release.py`
|
||||
8. Mirror the release debug store into the Offline Kit staging tree and re-check the manifest:
|
||||
8. **Verify reproducibility** – rebuild and compare checksums:
|
||||
```bash
|
||||
export SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD)
|
||||
make release
|
||||
sha256sum dist/* | diff - out/release/SHA256SUMS
|
||||
```
|
||||
9. **Generate Release Evidence Pack** – trigger evidence pack workflow:
|
||||
```bash
|
||||
gh workflow run release-evidence-pack.yml \
|
||||
-f version=X.Y.Z \
|
||||
-f release_tag=vX.Y.Z
|
||||
```
|
||||
10. **Self-verify evidence pack** – extract and run verify.sh:
|
||||
```bash
|
||||
tar -xzf stella-release-X.Y.Z-evidence-pack.tgz
|
||||
cd stella-release-X.Y.Z-evidence-pack
|
||||
./verify.sh --verbose
|
||||
```
|
||||
11. Mirror the release debug store into the Offline Kit staging tree and re-check the manifest:
|
||||
```bash
|
||||
./ops/offline-kit/mirror_debug_store.py \
|
||||
--release-dir out/release \
|
||||
@@ -157,9 +175,9 @@ CI job fails if token expiry < 29 days (guard against stale caches).
|
||||
jq '.artifacts | length' out/offline-kit/debug/debug-manifest.json
|
||||
readelf -n /app/... | grep -i 'Build ID'
|
||||
```
|
||||
Validate that the hash from `readelf` matches the `.build-id/<aa>/<rest>.debug` path created by the script.
|
||||
9. Smoke-test OUK tarball in offline lab.
|
||||
10. Announce in `#stella-release` Mattermost channel.
|
||||
Validate that the hash from `readelf` matches the `.build-id/<aa>/<rest>.debug` path created by the script.
|
||||
12. Smoke-test OUK tarball in offline lab.
|
||||
13. Announce in `#stella-release` Mattermost channel.
|
||||
|
||||
---
|
||||
|
||||
@@ -189,11 +207,11 @@ CI job fails if token expiry < 29 days (guard against stale caches).
|
||||
## 9 📌 Non‑Commercial Usage Rules (English canonical)
|
||||
|
||||
1. **Free for internal security assessments** (company or personal).
|
||||
2. **SaaS resale / re-hosting prohibited** without prior written consent (policy requirement; not a license restriction).
|
||||
3. If you distribute a fork with UI or backend modifications **you must**:
|
||||
* Include the LICENSE and NOTICE files.
|
||||
* Mark modified files with prominent change notices.
|
||||
* Retain the original Stella Ops attribution in UI footer and CLI `--version`.
|
||||
2. **SaaS resale / re-hosting prohibited** without prior written consent (policy requirement; not a license restriction).
|
||||
3. If you distribute a fork with UI or backend modifications **you must**:
|
||||
* Include the LICENSE and NOTICE files.
|
||||
* Mark modified files with prominent change notices.
|
||||
* Retain the original Stella Ops attribution in UI footer and CLI `--version`.
|
||||
4. All third‑party dependencies remain under their respective licences (MIT, Apache‑2.0, ISC, BSD).
|
||||
5. Deployments in state‑regulated or classified environments must obey**applicable local regulations** governing cryptography and software distribution.
|
||||
|
||||
|
||||
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)
|
||||
@@ -213,9 +213,81 @@ For critical security fixes:
|
||||
|
||||
---
|
||||
|
||||
## Release Evidence Pack
|
||||
|
||||
Every release includes a **Release Evidence Pack** for customer verification and compliance.
|
||||
|
||||
### Evidence Pack Contents
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| Artifacts | Release binaries and container references |
|
||||
| Checksums | SHA-256 and SHA-512 checksum files |
|
||||
| Signatures | Cosign signatures for all artifacts |
|
||||
| SBOMs | CycloneDX Software Bill of Materials |
|
||||
| Provenance | SLSA v1.0 provenance statements |
|
||||
| Rekor Proofs | Transparency log inclusion proofs |
|
||||
| Verification Scripts | `verify.sh` and `verify.ps1` |
|
||||
|
||||
### Generation Workflow
|
||||
|
||||
The evidence pack is generated by `.gitea/workflows/release-evidence-pack.yml`:
|
||||
|
||||
1. **Verify Test Gates** - Ensures all test workflows passed
|
||||
2. **Generate Checksums** - Create SHA256SUMS and SHA512SUMS
|
||||
3. **Sign Artifacts** - Sign with cosign (keyless or key-based)
|
||||
4. **Generate SBOMs** - Create CycloneDX SBOMs per artifact
|
||||
5. **Generate Provenance** - Create SLSA v1.0 statements
|
||||
6. **Collect Rekor Proofs** - Fetch inclusion proofs from Rekor
|
||||
7. **Build Pack** - Assemble final evidence pack bundle
|
||||
8. **Self-Verify** - Run verify.sh to validate the pack
|
||||
|
||||
### Manual Trigger
|
||||
|
||||
```bash
|
||||
# Trigger evidence pack generation for a release
|
||||
gh workflow run release-evidence-pack.yml \
|
||||
-f version=2.5.0 \
|
||||
-f release_tag=v2.5.0
|
||||
```
|
||||
|
||||
### Verification
|
||||
|
||||
Customers can verify releases offline:
|
||||
|
||||
```bash
|
||||
tar -xzf stella-release-2.5.0-evidence-pack.tgz
|
||||
cd stella-release-2.5.0-evidence-pack
|
||||
./verify.sh --verbose
|
||||
```
|
||||
|
||||
See [Release Evidence Pack](./RELEASE_EVIDENCE_PACK.md) for detailed documentation.
|
||||
|
||||
---
|
||||
|
||||
## Reproducible Builds
|
||||
|
||||
All release builds are reproducible using `SOURCE_DATE_EPOCH`:
|
||||
|
||||
```bash
|
||||
# Set from git commit timestamp
|
||||
export SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD)
|
||||
|
||||
# Build with deterministic settings
|
||||
dotnet build -c Release /p:Deterministic=true /p:ContinuousIntegrationBuild=true
|
||||
```
|
||||
|
||||
The CI verifies reproducibility by building twice and comparing checksums.
|
||||
|
||||
See [Reproducible Builds](./REPRODUCIBLE_BUILDS.md) for details.
|
||||
|
||||
---
|
||||
|
||||
## Post-Release Tasks
|
||||
|
||||
- [ ] Verify artifacts in registry
|
||||
- [ ] Generate and publish Release Evidence Pack
|
||||
- [ ] Verify evidence pack passes self-verification
|
||||
- [ ] Update documentation site
|
||||
- [ ] Send release announcement
|
||||
- [ ] Update compatibility matrix
|
||||
|
||||
195
docs/releases/REPRODUCIBLE_BUILDS.md
Normal file
195
docs/releases/REPRODUCIBLE_BUILDS.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# Reproducible Builds
|
||||
|
||||
Stella Ops releases are **reproducible**: given the same source code and build environment, anyone can produce byte-identical artifacts.
|
||||
|
||||
## Overview
|
||||
|
||||
Reproducible builds provide:
|
||||
|
||||
1. **Verifiability** - Anyone can verify that released binaries match source code
|
||||
2. **Trust** - No need to trust the build infrastructure
|
||||
3. **Auditability** - Build process can be independently audited
|
||||
4. **Security** - Compromised builds can be detected
|
||||
|
||||
## How It Works
|
||||
|
||||
### SOURCE_DATE_EPOCH
|
||||
|
||||
All timestamps in build outputs use the `SOURCE_DATE_EPOCH` environment variable instead of the current time. This is set to the git commit timestamp:
|
||||
|
||||
```bash
|
||||
export SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD)
|
||||
```
|
||||
|
||||
### Deterministic Build Settings
|
||||
|
||||
The following MSBuild properties ensure deterministic .NET builds:
|
||||
|
||||
```xml
|
||||
<!-- src/Directory.Build.props -->
|
||||
<PropertyGroup>
|
||||
<Deterministic>true</Deterministic>
|
||||
<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
|
||||
<PathMap>$(MSBuildProjectDirectory)=/src/</PathMap>
|
||||
<EmbedUntrackedSources>true</EmbedUntrackedSources>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
### Pinned Dependencies
|
||||
|
||||
All dependencies are pinned to exact versions in `Directory.Packages.props`:
|
||||
|
||||
```xml
|
||||
<PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
|
||||
```
|
||||
|
||||
### Containerized Builds
|
||||
|
||||
Release builds run in containerized environments with:
|
||||
|
||||
- Fixed base images
|
||||
- Pinned tool versions
|
||||
- Isolated network (no external fetches during build)
|
||||
|
||||
## Reproducing a Build
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- .NET SDK (version in `global.json`)
|
||||
- Git
|
||||
- Docker (optional, for containerized builds)
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Clone the repository**
|
||||
|
||||
```bash
|
||||
git clone https://git.stella-ops.org/stella-ops.org/git.stella-ops.org.git
|
||||
cd git.stella-ops.org
|
||||
```
|
||||
|
||||
2. **Checkout the release tag**
|
||||
|
||||
```bash
|
||||
git checkout v1.2.3
|
||||
```
|
||||
|
||||
3. **Set SOURCE_DATE_EPOCH**
|
||||
|
||||
Get the value from the release evidence pack `manifest.json`:
|
||||
|
||||
```bash
|
||||
export SOURCE_DATE_EPOCH=1705315800
|
||||
```
|
||||
|
||||
Or compute from git:
|
||||
|
||||
```bash
|
||||
export SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD)
|
||||
```
|
||||
|
||||
4. **Build**
|
||||
|
||||
```bash
|
||||
# Using make
|
||||
make release
|
||||
|
||||
# Or using dotnet directly
|
||||
dotnet publish src/Cli/StellaOps.Cli/StellaOps.Cli.csproj \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
/p:Deterministic=true \
|
||||
/p:ContinuousIntegrationBuild=true \
|
||||
/p:SourceRevisionId=$(git rev-parse HEAD)
|
||||
```
|
||||
|
||||
5. **Compare checksums**
|
||||
|
||||
```bash
|
||||
sha256sum dist/stella-* | diff - path/to/evidence-pack/checksums/SHA256SUMS
|
||||
```
|
||||
|
||||
## CI Verification
|
||||
|
||||
The CI pipeline automatically verifies reproducibility:
|
||||
|
||||
1. Builds artifacts twice with the same `SOURCE_DATE_EPOCH`
|
||||
2. Compares checksums between builds
|
||||
3. Fails if checksums don't match
|
||||
|
||||
See `.gitea/workflows/verify-reproducibility.yml`.
|
||||
|
||||
## What Can Cause Non-Reproducibility
|
||||
|
||||
### Timestamps
|
||||
|
||||
- **Problem**: Build tools embed current time
|
||||
- **Solution**: Use `SOURCE_DATE_EPOCH`
|
||||
|
||||
### Path Information
|
||||
|
||||
- **Problem**: Absolute paths embedded in binaries/PDBs
|
||||
- **Solution**: Use `PathMap` to normalize paths
|
||||
|
||||
### Random Values
|
||||
|
||||
- **Problem**: GUIDs, random seeds
|
||||
- **Solution**: Use deterministic generation or inject via DI
|
||||
|
||||
### Unordered Collections
|
||||
|
||||
- **Problem**: Dictionary/HashSet iteration order varies
|
||||
- **Solution**: Use `ImmutableSortedDictionary` or explicit sorting
|
||||
|
||||
### External Resources
|
||||
|
||||
- **Problem**: Network fetches return different content
|
||||
- **Solution**: Pin dependencies, use hermetic builds
|
||||
|
||||
### Compiler/Tool Versions
|
||||
|
||||
- **Problem**: Different tool versions produce different output
|
||||
- **Solution**: Pin all tool versions in `global.json` and CI
|
||||
|
||||
## Debugging Non-Reproducible Builds
|
||||
|
||||
### Compare binaries
|
||||
|
||||
```bash
|
||||
# Install diffoscope
|
||||
pip install diffoscope
|
||||
|
||||
# Compare two builds
|
||||
diffoscope build1/stella.dll build2/stella.dll
|
||||
```
|
||||
|
||||
### Check for timestamps
|
||||
|
||||
```bash
|
||||
# Look for embedded timestamps
|
||||
strings stella.dll | grep -E '20[0-9]{2}-[0-9]{2}'
|
||||
```
|
||||
|
||||
### Check PDB content
|
||||
|
||||
```bash
|
||||
# Examine PDB for path information
|
||||
dotnet tool install -g dotnet-symbol
|
||||
dotnet symbol --symbols stella.dll
|
||||
```
|
||||
|
||||
## Verification in Evidence Pack
|
||||
|
||||
The Release Evidence Pack includes:
|
||||
|
||||
1. **SOURCE_DATE_EPOCH** in `manifest.json`
|
||||
2. **Source commit** for exact source checkout
|
||||
3. **Checksums** for comparison
|
||||
4. **Build instructions** in `VERIFY.md`
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Release Evidence Pack](./RELEASE_EVIDENCE_PACK.md)
|
||||
- [SLSA Compliance](./SLSA_COMPLIANCE.md)
|
||||
- [Release Engineering Playbook](./RELEASE_ENGINEERING_PLAYBOOK.md)
|
||||
207
docs/releases/SLSA_COMPLIANCE.md
Normal file
207
docs/releases/SLSA_COMPLIANCE.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# SLSA Compliance
|
||||
|
||||
This document describes Stella Ops' compliance with the [Supply-chain Levels for Software Artifacts (SLSA)](https://slsa.dev/) framework.
|
||||
|
||||
## Current SLSA Level
|
||||
|
||||
Stella Ops releases target **SLSA Level 2** with ongoing work toward Level 3.
|
||||
|
||||
| Level | Status | Description |
|
||||
|-------|--------|-------------|
|
||||
| SLSA 1 | ✅ Complete | Provenance exists and shows build process |
|
||||
| SLSA 2 | ✅ Complete | Provenance is signed and generated by hosted build service |
|
||||
| SLSA 3 | 🔄 In Progress | Build platform provides strong isolation guarantees |
|
||||
|
||||
## SLSA v1.0 Provenance
|
||||
|
||||
### Predicate Type
|
||||
|
||||
Stella Ops uses the standard SLSA v1.0 provenance predicate:
|
||||
|
||||
```
|
||||
https://slsa.dev/provenance/v1
|
||||
```
|
||||
|
||||
### Provenance Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"_type": "https://in-toto.io/Statement/v1",
|
||||
"subject": [
|
||||
{
|
||||
"name": "stella-1.2.3-linux-x64.tar.gz",
|
||||
"digest": {
|
||||
"sha256": "abc123..."
|
||||
}
|
||||
}
|
||||
],
|
||||
"predicateType": "https://slsa.dev/provenance/v1",
|
||||
"predicate": {
|
||||
"buildDefinition": {
|
||||
"buildType": "https://stella-ops.io/ReleaseBuilder/v1",
|
||||
"externalParameters": {
|
||||
"version": "1.2.3",
|
||||
"target": "linux-x64"
|
||||
},
|
||||
"resolvedDependencies": [
|
||||
{
|
||||
"uri": "git+https://git.stella-ops.org/stella-ops.org/git.stella-ops.org@v1.2.3",
|
||||
"digest": {
|
||||
"gitCommit": "abc123..."
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"runDetails": {
|
||||
"builder": {
|
||||
"id": "https://ci.stella-ops.org/builder/v1"
|
||||
},
|
||||
"metadata": {
|
||||
"invocationId": "12345/1",
|
||||
"startedOn": "2025-01-15T10:30:00Z",
|
||||
"finishedOn": "2025-01-15T10:45:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### Verifying Provenance Signature
|
||||
|
||||
```bash
|
||||
cosign verify-blob \
|
||||
--key cosign.pub \
|
||||
--signature provenance/stella-cli.slsa.intoto.jsonl.sig \
|
||||
provenance/stella-cli.slsa.intoto.jsonl
|
||||
```
|
||||
|
||||
### Inspecting Provenance
|
||||
|
||||
```bash
|
||||
# View full provenance
|
||||
cat provenance/stella-cli.slsa.intoto.jsonl | jq .
|
||||
|
||||
# Extract builder ID
|
||||
cat provenance/stella-cli.slsa.intoto.jsonl | jq -r '.predicate.runDetails.builder.id'
|
||||
|
||||
# Extract source commit
|
||||
cat provenance/stella-cli.slsa.intoto.jsonl | jq -r '.predicate.buildDefinition.resolvedDependencies[0].digest.gitCommit'
|
||||
```
|
||||
|
||||
### Policy Verification
|
||||
|
||||
Verify provenance matches your policy:
|
||||
|
||||
```bash
|
||||
# Example: Verify builder ID
|
||||
BUILDER_ID=$(cat provenance/stella-cli.slsa.intoto.jsonl | jq -r '.predicate.runDetails.builder.id')
|
||||
if [ "$BUILDER_ID" != "https://ci.stella-ops.org/builder/v1" ]; then
|
||||
echo "ERROR: Unknown builder"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Strict Validation Mode
|
||||
|
||||
Stella Ops supports strict SLSA validation that enforces:
|
||||
|
||||
1. **Valid builder ID URI** - Must be a valid absolute URI
|
||||
2. **Approved digest algorithms** - sha256, sha384, sha512, sha3-*
|
||||
3. **RFC 3339 timestamps** - All timestamps must be properly formatted
|
||||
4. **Minimum SLSA level** - Configurable minimum level requirement
|
||||
|
||||
### Configuration
|
||||
|
||||
In `appsettings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"Attestor": {
|
||||
"Slsa": {
|
||||
"ValidationMode": "Strict",
|
||||
"MinimumSlsaLevel": 2,
|
||||
"AllowedBuilderIds": [
|
||||
"https://ci.stella-ops.org/builder/v1",
|
||||
"https://github.com/actions/runner"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## SLSA Requirements Mapping
|
||||
|
||||
### Source Requirements
|
||||
|
||||
| Requirement | Implementation |
|
||||
|-------------|----------------|
|
||||
| Version controlled | Git with signed commits |
|
||||
| Verified history | Protected branches, PR reviews |
|
||||
| Retained indefinitely | Git history preserved |
|
||||
| Two-person reviewed | Required PR approvals |
|
||||
|
||||
### Build Requirements
|
||||
|
||||
| Requirement | Implementation |
|
||||
|-------------|----------------|
|
||||
| Scripted build | Makefile + CI workflows |
|
||||
| Build service | GitHub Actions / Gitea Actions |
|
||||
| Build as code | `.gitea/workflows/*.yml` |
|
||||
| Ephemeral environment | Fresh CI runners per build |
|
||||
| Isolated | Containerized build environment |
|
||||
| Parameterless | Build inputs from version control only |
|
||||
| Hermetic | Pinned dependencies, reproducible builds |
|
||||
|
||||
### Provenance Requirements
|
||||
|
||||
| Requirement | Implementation |
|
||||
|-------------|----------------|
|
||||
| Available | Published with every release |
|
||||
| Authenticated | Cosign signatures |
|
||||
| Service generated | CI generates provenance |
|
||||
| Non-falsifiable | Signed by CI identity |
|
||||
| Dependencies complete | All inputs listed with digests |
|
||||
|
||||
## Verification Tools
|
||||
|
||||
### Using slsa-verifier
|
||||
|
||||
```bash
|
||||
# Install slsa-verifier
|
||||
go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest
|
||||
|
||||
# Verify artifact
|
||||
slsa-verifier verify-artifact \
|
||||
artifacts/stella-1.2.3-linux-x64.tar.gz \
|
||||
--provenance-path provenance/stella-cli.slsa.intoto.jsonl \
|
||||
--source-uri github.com/stella-ops/stella-ops \
|
||||
--builder-id https://ci.stella-ops.org/builder/v1
|
||||
```
|
||||
|
||||
### Using Stella CLI
|
||||
|
||||
```bash
|
||||
stella attest verify \
|
||||
--artifact artifacts/stella-1.2.3-linux-x64.tar.gz \
|
||||
--provenance provenance/stella-cli.slsa.intoto.jsonl \
|
||||
--slsa-level 2 \
|
||||
--builder-id https://ci.stella-ops.org/builder/v1
|
||||
```
|
||||
|
||||
## Roadmap to SLSA Level 3
|
||||
|
||||
Current gaps and planned improvements:
|
||||
|
||||
| Gap | Plan |
|
||||
|-----|------|
|
||||
| Build isolation | Migrate to hardened build runners |
|
||||
| Non-forgeable provenance | Implement OIDC-based signing |
|
||||
| Isolated build inputs | Hermetic build environment |
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Release Evidence Pack](./RELEASE_EVIDENCE_PACK.md)
|
||||
- [Reproducible Builds](./REPRODUCIBLE_BUILDS.md)
|
||||
- [Attestor Architecture](../modules/attestor/architecture.md)
|
||||
257
docs/releases/evidence-pack-schema.json
Normal file
257
docs/releases/evidence-pack-schema.json
Normal file
@@ -0,0 +1,257 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stella-ops.io/schemas/evidence-pack-manifest/v1.0.0",
|
||||
"title": "Release Evidence Pack Manifest",
|
||||
"description": "Schema for Stella Ops Release Evidence Pack manifest.json files",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"bundleFormatVersion",
|
||||
"releaseVersion",
|
||||
"createdAt",
|
||||
"sourceCommit",
|
||||
"artifacts"
|
||||
],
|
||||
"properties": {
|
||||
"bundleFormatVersion": {
|
||||
"type": "string",
|
||||
"description": "Version of the evidence pack format",
|
||||
"pattern": "^\\d+\\.\\d+\\.\\d+$",
|
||||
"examples": ["1.0.0"]
|
||||
},
|
||||
"releaseVersion": {
|
||||
"type": "string",
|
||||
"description": "Version of the Stella Ops release",
|
||||
"examples": ["2.5.0", "1.2.3-beta.1"]
|
||||
},
|
||||
"createdAt": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp when the evidence pack was created"
|
||||
},
|
||||
"sourceCommit": {
|
||||
"type": "string",
|
||||
"description": "Git commit SHA of the source code",
|
||||
"pattern": "^[a-f0-9]{40}$"
|
||||
},
|
||||
"sourceDateEpoch": {
|
||||
"type": "integer",
|
||||
"description": "Unix timestamp used for reproducible builds (SOURCE_DATE_EPOCH)",
|
||||
"minimum": 0
|
||||
},
|
||||
"artifacts": {
|
||||
"type": "array",
|
||||
"description": "List of release artifacts in this pack",
|
||||
"items": {
|
||||
"$ref": "#/$defs/artifactEntry"
|
||||
},
|
||||
"minItems": 1
|
||||
},
|
||||
"checksums": {
|
||||
"type": "object",
|
||||
"description": "Checksum files included in the pack",
|
||||
"properties": {
|
||||
"sha256": {
|
||||
"$ref": "#/$defs/checksumEntry"
|
||||
},
|
||||
"sha512": {
|
||||
"$ref": "#/$defs/checksumEntry"
|
||||
}
|
||||
}
|
||||
},
|
||||
"sboms": {
|
||||
"type": "array",
|
||||
"description": "Software Bill of Materials files",
|
||||
"items": {
|
||||
"$ref": "#/$defs/sbomReference"
|
||||
}
|
||||
},
|
||||
"provenanceStatements": {
|
||||
"type": "array",
|
||||
"description": "SLSA v1.0 provenance statements",
|
||||
"items": {
|
||||
"$ref": "#/$defs/provenanceReference"
|
||||
}
|
||||
},
|
||||
"attestations": {
|
||||
"type": "array",
|
||||
"description": "DSSE attestation bundles",
|
||||
"items": {
|
||||
"$ref": "#/$defs/attestationReference"
|
||||
}
|
||||
},
|
||||
"rekorProofs": {
|
||||
"type": "array",
|
||||
"description": "Rekor transparency log inclusion proofs",
|
||||
"items": {
|
||||
"$ref": "#/$defs/rekorProofEntry"
|
||||
}
|
||||
},
|
||||
"signingKeyFingerprint": {
|
||||
"type": "string",
|
||||
"description": "SHA-256 fingerprint of the signing public key"
|
||||
},
|
||||
"rekorLogId": {
|
||||
"type": "string",
|
||||
"description": "Rekor log ID (tree ID) for transparency log entries"
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"artifactEntry": {
|
||||
"type": "object",
|
||||
"required": ["name", "path", "sha256"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Display name of the artifact"
|
||||
},
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Relative path within the evidence pack"
|
||||
},
|
||||
"sha256": {
|
||||
"type": "string",
|
||||
"description": "SHA-256 hash of the artifact",
|
||||
"pattern": "^[a-f0-9]{64}$"
|
||||
},
|
||||
"sha512": {
|
||||
"type": "string",
|
||||
"description": "SHA-512 hash of the artifact",
|
||||
"pattern": "^[a-f0-9]{128}$"
|
||||
},
|
||||
"signaturePath": {
|
||||
"type": "string",
|
||||
"description": "Relative path to the detached signature file"
|
||||
},
|
||||
"size": {
|
||||
"type": "integer",
|
||||
"description": "File size in bytes",
|
||||
"minimum": 0
|
||||
},
|
||||
"platform": {
|
||||
"type": "string",
|
||||
"description": "Target platform (e.g., linux-x64, macos-arm64, windows-x64)"
|
||||
},
|
||||
"mediaType": {
|
||||
"type": "string",
|
||||
"description": "MIME type of the artifact"
|
||||
}
|
||||
}
|
||||
},
|
||||
"checksumEntry": {
|
||||
"type": "object",
|
||||
"required": ["path"],
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Relative path to the checksum file"
|
||||
},
|
||||
"signaturePath": {
|
||||
"type": "string",
|
||||
"description": "Relative path to the signature of the checksum file"
|
||||
}
|
||||
}
|
||||
},
|
||||
"sbomReference": {
|
||||
"type": "object",
|
||||
"required": ["path", "format"],
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Relative path to the SBOM file"
|
||||
},
|
||||
"format": {
|
||||
"type": "string",
|
||||
"description": "SBOM format",
|
||||
"enum": ["cyclonedx", "spdx"]
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"description": "SBOM format version (e.g., 1.5 for CycloneDX)"
|
||||
},
|
||||
"signaturePath": {
|
||||
"type": "string",
|
||||
"description": "Relative path to the signature file"
|
||||
},
|
||||
"component": {
|
||||
"type": "string",
|
||||
"description": "Component this SBOM describes"
|
||||
}
|
||||
}
|
||||
},
|
||||
"provenanceReference": {
|
||||
"type": "object",
|
||||
"required": ["path", "predicateType"],
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Relative path to the provenance file"
|
||||
},
|
||||
"predicateType": {
|
||||
"type": "string",
|
||||
"description": "SLSA predicate type URI",
|
||||
"examples": ["https://slsa.dev/provenance/v1"]
|
||||
},
|
||||
"signaturePath": {
|
||||
"type": "string",
|
||||
"description": "Relative path to the signature file"
|
||||
},
|
||||
"builderId": {
|
||||
"type": "string",
|
||||
"description": "Builder ID from the provenance"
|
||||
},
|
||||
"slsaLevel": {
|
||||
"type": "integer",
|
||||
"description": "SLSA level of this provenance (1-4)",
|
||||
"minimum": 1,
|
||||
"maximum": 4
|
||||
}
|
||||
}
|
||||
},
|
||||
"attestationReference": {
|
||||
"type": "object",
|
||||
"required": ["path", "type"],
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Relative path to the attestation file"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"description": "Attestation type",
|
||||
"enum": ["dsse", "sigstore-bundle", "in-toto"]
|
||||
},
|
||||
"predicateType": {
|
||||
"type": "string",
|
||||
"description": "Predicate type URI for in-toto/DSSE attestations"
|
||||
}
|
||||
}
|
||||
},
|
||||
"rekorProofEntry": {
|
||||
"type": "object",
|
||||
"required": ["uuid", "logIndex"],
|
||||
"properties": {
|
||||
"uuid": {
|
||||
"type": "string",
|
||||
"description": "Rekor entry UUID"
|
||||
},
|
||||
"logIndex": {
|
||||
"type": "integer",
|
||||
"description": "Index in the Rekor log",
|
||||
"minimum": 0
|
||||
},
|
||||
"integratedTime": {
|
||||
"type": "integer",
|
||||
"description": "Unix timestamp when entry was added to log"
|
||||
},
|
||||
"inclusionProofPath": {
|
||||
"type": "string",
|
||||
"description": "Relative path to the inclusion proof JSON file"
|
||||
},
|
||||
"artifactName": {
|
||||
"type": "string",
|
||||
"description": "Name of the artifact this proof applies to"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
278
docs/releases/offline-verification.md
Normal file
278
docs/releases/offline-verification.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# Offline Verification Guide
|
||||
|
||||
This guide explains how to verify Stella Ops releases in air-gapped or offline environments without network access.
|
||||
|
||||
## Overview
|
||||
|
||||
The Release Evidence Pack is designed for complete offline verification. All cryptographic materials and proofs are bundled together, allowing verification without contacting external services.
|
||||
|
||||
## Verification Levels
|
||||
|
||||
Stella Ops supports multiple verification levels depending on your security requirements and available tools:
|
||||
|
||||
| Level | Tools Required | Network | Security Assurance |
|
||||
|-------|---------------|---------|-------------------|
|
||||
| 1 - Checksum | sha256sum | None | Artifact integrity |
|
||||
| 2 - Signature | sha256sum + cosign | None | Authenticity + integrity |
|
||||
| 3 - Provenance | sha256sum + cosign + jq | None | Build chain verification |
|
||||
| 4 - Transparency | sha256sum + cosign + rekor-cli | Optional | Non-repudiation |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Minimal (Level 1)
|
||||
|
||||
Standard Unix tools available on most systems:
|
||||
- `sha256sum` or `shasum`
|
||||
- `cat`, `diff`
|
||||
|
||||
### Full Verification (Levels 2-4)
|
||||
|
||||
Install cosign for signature verification:
|
||||
|
||||
```bash
|
||||
# Linux
|
||||
curl -sSL https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 -o cosign
|
||||
chmod +x cosign
|
||||
sudo mv cosign /usr/local/bin/
|
||||
|
||||
# macOS
|
||||
brew install cosign
|
||||
|
||||
# Windows (PowerShell)
|
||||
scoop install cosign
|
||||
# or download from GitHub releases
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Using the Verification Script
|
||||
|
||||
The evidence pack includes a self-contained verification script:
|
||||
|
||||
```bash
|
||||
# Extract the evidence pack
|
||||
tar -xzf stella-release-2.5.0-evidence-pack.tgz
|
||||
cd stella-release-2.5.0-evidence-pack
|
||||
|
||||
# Run verification
|
||||
./verify.sh
|
||||
|
||||
# For verbose output
|
||||
./verify.sh --verbose
|
||||
|
||||
# For JSON output (CI integration)
|
||||
./verify.sh --json
|
||||
```
|
||||
|
||||
On Windows (PowerShell 7+):
|
||||
|
||||
```powershell
|
||||
# Extract
|
||||
Expand-Archive stella-release-2.5.0-evidence-pack.zip -DestinationPath .
|
||||
cd stella-release-2.5.0-evidence-pack
|
||||
|
||||
# Run verification
|
||||
./verify.ps1
|
||||
```
|
||||
|
||||
### Exit Codes
|
||||
|
||||
The verification scripts return specific exit codes:
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | All verifications passed |
|
||||
| 1 | Checksum verification failed |
|
||||
| 2 | Signature verification failed |
|
||||
| 3 | Provenance verification failed |
|
||||
| 4 | Configuration error |
|
||||
|
||||
## Manual Verification Steps
|
||||
|
||||
### Level 1: Checksum Verification
|
||||
|
||||
Verify artifact integrity using SHA-256 checksums:
|
||||
|
||||
```bash
|
||||
cd artifacts/
|
||||
sha256sum -c ../checksums/SHA256SUMS
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
stella-2.5.0-linux-x64.tar.gz: OK
|
||||
stella-2.5.0-linux-arm64.tar.gz: OK
|
||||
stella-2.5.0-macos-universal.tar.gz: OK
|
||||
stella-2.5.0-windows-x64.zip: OK
|
||||
```
|
||||
|
||||
### Level 2: Signature Verification
|
||||
|
||||
Verify that artifacts were signed by Stella Ops:
|
||||
|
||||
```bash
|
||||
# Verify the checksums file signature
|
||||
cosign verify-blob \
|
||||
--key cosign.pub \
|
||||
--signature checksums/SHA256SUMS.sig \
|
||||
checksums/SHA256SUMS
|
||||
|
||||
# Verify individual artifact signatures
|
||||
cosign verify-blob \
|
||||
--key cosign.pub \
|
||||
--signature artifacts/stella-2.5.0-linux-x64.tar.gz.sig \
|
||||
artifacts/stella-2.5.0-linux-x64.tar.gz
|
||||
```
|
||||
|
||||
### Level 3: Provenance Verification
|
||||
|
||||
Verify SLSA provenance and inspect build details:
|
||||
|
||||
```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 contents
|
||||
cat provenance/stella-cli.slsa.intoto.jsonl | jq '.'
|
||||
|
||||
# Verify builder ID
|
||||
BUILDER_ID=$(cat provenance/stella-cli.slsa.intoto.jsonl | \
|
||||
jq -r '.predicate.runDetails.builder.id')
|
||||
echo "Builder: $BUILDER_ID"
|
||||
|
||||
# Verify it matches expected value
|
||||
if [ "$BUILDER_ID" != "https://ci.stella-ops.org/builder/v1" ]; then
|
||||
echo "WARNING: Unexpected builder ID"
|
||||
fi
|
||||
|
||||
# Check source commit
|
||||
SOURCE_COMMIT=$(cat provenance/stella-cli.slsa.intoto.jsonl | \
|
||||
jq -r '.predicate.buildDefinition.resolvedDependencies[0].digest.gitCommit')
|
||||
echo "Source commit: $SOURCE_COMMIT"
|
||||
```
|
||||
|
||||
### Level 4: Transparency Log Verification
|
||||
|
||||
Verify Rekor inclusion proofs (requires network OR pre-fetched proofs):
|
||||
|
||||
#### With Network Access
|
||||
|
||||
```bash
|
||||
rekor-cli verify \
|
||||
--artifact artifacts/stella-2.5.0-linux-x64.tar.gz \
|
||||
--signature artifacts/stella-2.5.0-linux-x64.tar.gz.sig \
|
||||
--public-key cosign.pub
|
||||
```
|
||||
|
||||
#### Offline (using bundled proofs)
|
||||
|
||||
The evidence pack includes pre-fetched Rekor proofs in `rekor-proofs/`:
|
||||
|
||||
```bash
|
||||
# List included proofs
|
||||
cat rekor-proofs/inclusion-proofs.json | jq '.proofs'
|
||||
|
||||
# View a specific entry
|
||||
cat rekor-proofs/log-entries/<uuid>.json | jq '.'
|
||||
```
|
||||
|
||||
## SBOM Verification
|
||||
|
||||
Verify Software Bill of Materials:
|
||||
|
||||
```bash
|
||||
# Verify SBOM signature
|
||||
cosign verify-blob \
|
||||
--key cosign.pub \
|
||||
--signature sbom/stella-cli.cdx.json.sig \
|
||||
sbom/stella-cli.cdx.json
|
||||
|
||||
# Inspect SBOM contents
|
||||
cat sbom/stella-cli.cdx.json | jq '.components | length'
|
||||
```
|
||||
|
||||
## Reproducible Build Verification
|
||||
|
||||
Stella Ops releases are reproducible. You can rebuild from source and compare:
|
||||
|
||||
```bash
|
||||
# Get the SOURCE_DATE_EPOCH from manifest
|
||||
SOURCE_DATE_EPOCH=$(cat manifest.json | jq -r '.sourceDateEpoch')
|
||||
SOURCE_COMMIT=$(cat manifest.json | jq -r '.sourceCommit')
|
||||
|
||||
# Clone and checkout
|
||||
git clone https://git.stella-ops.org/stella-ops.org/git.stella-ops.org.git
|
||||
cd git.stella-ops.org
|
||||
git checkout $SOURCE_COMMIT
|
||||
|
||||
# Set reproducible timestamp
|
||||
export SOURCE_DATE_EPOCH
|
||||
|
||||
# Build
|
||||
make release
|
||||
|
||||
# Compare checksums
|
||||
sha256sum dist/stella-* | diff - path/to/evidence-pack/checksums/SHA256SUMS
|
||||
```
|
||||
|
||||
## Verification in CI/CD
|
||||
|
||||
For automated verification in pipelines:
|
||||
|
||||
```bash
|
||||
# Download and verify in one step
|
||||
curl -sSL https://releases.stella-ops.org/v2.5.0/evidence-pack.tgz | tar -xz
|
||||
cd stella-release-2.5.0-evidence-pack
|
||||
|
||||
# Run verification with JSON output
|
||||
./verify.sh --json > verification-result.json
|
||||
|
||||
# Check result
|
||||
if [ "$(jq -r '.overall' verification-result.json)" != "PASS" ]; then
|
||||
echo "Verification failed!"
|
||||
jq '.steps[] | select(.status == "FAIL")' verification-result.json
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "cosign: command not found"
|
||||
|
||||
Install cosign from https://docs.sigstore.dev/cosign/installation/
|
||||
|
||||
### Checksum Mismatch
|
||||
|
||||
1. Re-download the artifact
|
||||
2. Verify download completed (check file size)
|
||||
3. Try a different mirror if available
|
||||
4. Check for file corruption during transfer
|
||||
|
||||
### Signature Verification Failed
|
||||
|
||||
1. Ensure you're using `cosign.pub` from the evidence pack
|
||||
2. Check the signature file hasn't been corrupted
|
||||
3. Verify the artifact hasn't been modified
|
||||
|
||||
### "Error: no matching entries in transparency log"
|
||||
|
||||
This can happen if:
|
||||
- The artifact was signed with key-based signing (not keyless)
|
||||
- The Rekor server is unreachable
|
||||
- Use the bundled proofs in `rekor-proofs/` instead
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Verify the evidence pack itself** - Download only from official sources
|
||||
2. **Compare public key fingerprint** - Verify `cosign.pub` fingerprint matches published key
|
||||
3. **Check provenance builder ID** - Ensure it matches expected CI system
|
||||
4. **Review SBOM for known vulnerabilities** - Scan dependencies before deployment
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Release Evidence Pack](./RELEASE_EVIDENCE_PACK.md)
|
||||
- [SLSA Compliance](./SLSA_COMPLIANCE.md)
|
||||
- [Reproducible Builds](./REPRODUCIBLE_BUILDS.md)
|
||||
Reference in New Issue
Block a user