test fixes and new product advisories work
This commit is contained in:
master
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)
|
||||
Reference in New Issue
Block a user