git.stella-ops.org/docs/releases/SLSA_COMPLIANCE.md

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