Files

master c58a236d70 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>

2026-03-27 12:28:00 +02:00

3.7 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

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

# 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

# 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

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

# 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

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

3.7 KiB Raw Blame History