---
checkId: check.compliance.provenance-completeness
plugin: stellaops.doctor.compliance
severity: fail
tags: [compliance, provenance, slsa]
---
# Provenance Completeness

## What It Checks
Verifies that provenance records exist for all releases by querying the Provenance service at `/api/v1/provenance/completeness`. The check computes a completeness rate as `(totalReleases - missingCount) / totalReleases` and evaluates the SLSA (Supply-chain Levels for Software Artifacts) level:

| Condition | Result |
|---|---|
| Provenance service unreachable | Warn |
| Completeness rate < 99% | Fail |
| SLSA level < 2 (but completeness >= 99%) | Warn |
| Completeness >= 99% and SLSA level >= 2 | Pass |

Evidence collected: `completeness_rate`, `total_releases`, `missing_count`, `slsa_level`.

The check only runs when `Provenance:Url` or `Services:Provenance:Url` is configured. It uses a 15-second HTTP timeout. If no releases exist (`totalReleases == 0`), completeness defaults to 100%.

## Why It Matters
Provenance records document the complete history of how a software artifact was built, including the source code, build system, and build steps. Without provenance, there is no verifiable link between source code and the deployed artifact. This is a foundational requirement for SLSA compliance and supply-chain security. Missing provenance for even a small percentage of releases creates audit gaps that undermine the trustworthiness of the entire release pipeline.

## Common Causes
- Build pipeline not configured to generate provenance attestations
- Provenance upload failures due to network or authentication issues
- Legacy releases created before provenance generation was enabled
- Manual deployments that bypass the standard build pipeline
- Build system not meeting SLSA level 2+ requirements

## How to Fix

### Docker Compose
```bash
# List releases missing provenance
docker compose exec provenance stella provenance audit --missing

# Generate backfill provenance for existing releases (dry run first)
docker compose exec provenance stella provenance backfill --dry-run

# If dry run looks correct, run the actual backfill
docker compose exec provenance stella provenance backfill

# Check SLSA level
docker compose exec provenance stella provenance slsa-level

# Ensure provenance generation is enabled in the pipeline
# Provenance__Enabled=true
# Provenance__SlsaLevel=2
```

### Bare Metal / systemd
```bash
# List releases missing provenance
stella provenance audit --missing

# Backfill provenance (dry run first)
stella provenance backfill --dry-run

# Check SLSA level configuration
stella provenance slsa-level

# Configure in appsettings.json
# "Provenance": { "Enabled": true, "SlsaLevel": 2 }

sudo systemctl restart stellaops-provenance
```

### Kubernetes / Helm
```yaml
# values.yaml
provenance:
  enabled: true
  slsaLevel: 2
  backfill:
    enabled: true
    schedule: "0 3 * * 0"  # Weekly Sunday 3am
```

```bash
# List missing provenance
kubectl exec deploy/stellaops-provenance -- stella provenance audit --missing

# Backfill
kubectl exec deploy/stellaops-provenance -- stella provenance backfill --dry-run

helm upgrade stellaops ./charts/stellaops -f values.yaml
```

## Verification
```
stella doctor run --check check.compliance.provenance-completeness
```

## Related Checks
- `check.compliance.attestation-signing` — signing key required for provenance attestations
- `check.compliance.evidence-rate` — evidence generation rate includes provenance records
- `check.compliance.evidence-integrity` — integrity of provenance evidence
- `check.evidencelocker.provenance` — provenance chain integrity at the storage level
- `check.compliance.framework` — compliance frameworks may require specific SLSA levels