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:
61
docs/doctor/articles/timestamping/tsa-root-expiry.md
Normal file
61
docs/doctor/articles/timestamping/tsa-root-expiry.md
Normal 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
|
||||
Reference in New Issue
Block a user