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,61 @@
---
checkId: check.timestamp.tsa.root-expiry
plugin: stellaops.doctor.timestamping
severity: warn
tags: [timestamping, tsa, root, certificate, expiry]
---
# 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:
```bash
# Update trust anchors
docker exec <platform-container> stella trust-anchor update --cert /certs/new-root.pem
```
### Bare Metal / systemd
```bash
# 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
```yaml
timestamping:
rootCertificates:
warnDays: 365
criticalDays: 180
```
## Verification
```
stella doctor run --check check.timestamp.tsa.root-expiry
```
## Related Checks
- `check.timestamp.tsa.cert-expiry` — checks TSA signing certificate expiry
- `check.timestamp.tsa.chain-valid` — validates TSA certificate chain integrity