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:
master
2026-03-27 12:28:00 +02:00
parent fbd24e71de
commit c58a236d70
326 changed files with 18500 additions and 463 deletions

View 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