Doctor plugin checks: implement health check classes and documentation
Implement remediation-aware health checks across all Doctor plugin modules (Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment, EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release, Scanner, Storage, Vex) and their backing library counterparts (AI, Attestation, Authority, Core, Cryptography, Database, Docker, Integration, Notify, Observability, Security, ServiceGraph, Sources, Verification). Each check now emits structured remediation metadata (severity, category, runbook links, and fix suggestions) consumed by the Doctor dashboard remediation panel. Also adds: - docs/doctor/articles/ knowledge base for check explanations - Advisory AI search seed and allowlist updates for doctor content - Sprint plan for doctor checks documentation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
102
docs/doctor/articles/compliance/provenance-completeness.md
Normal file
102
docs/doctor/articles/compliance/provenance-completeness.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user