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

2.0 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

TSA Root Certificate Expiry

What It Checks

Checks if TSA trust anchor (root) certificates are approaching expiry. The check:

Evaluates each root certificate in the RootCertificates configuration list.
Calculates days remaining until expiry.
Fails (unhealthy) if any root certificate is expired or within the critical threshold (default 180 days).
Warns (degraded) if within the warning threshold (default 365 days).
Uses longer thresholds than leaf certificates because root renewal requires more coordination.

Why It Matters

Root certificates anchor the entire TSA trust chain. When a root expires, all timestamps signed by TSAs chained to that root become unverifiable. Root certificate renewal requires updating trust stores across the entire deployment, which takes significant lead time.

Common Causes

Root certificate approaching end-of-life (typically 10-20 year lifetime)
Using a custom root CA with a shorter validity period
Trust store not updated after provider rotated roots

How to Fix

Docker Compose

Update root certificate trust store:

# Update trust anchors
docker exec <platform-container> stella trust-anchor update --cert /certs/new-root.pem

Bare Metal / systemd

# Update the trust anchor
stella trust-anchor update --cert /path/to/new-root.pem

# Or update the system trust store
sudo cp /path/to/new-root.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates

Kubernetes / Helm

timestamping:
  rootCertificates:
    warnDays: 365
    criticalDays: 180

Verification

stella doctor run --check check.timestamp.tsa.root-expiry

check.timestamp.tsa.cert-expiry — checks TSA signing certificate expiry
check.timestamp.tsa.chain-valid — validates TSA certificate chain integrity

2.0 KiB Raw Blame History