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,50 @@
---
checkId: check.timestamp.timesync.tsa-skew
plugin: stellaops.doctor.timestamping
severity: warn
tags: [timestamping, timesync, tsa, skew]
---
# TSA Time Skew
## What It Checks
Checks time skew between the system clock and TSA genTime. The check:
- For each active TSA provider, requests a timestamp token with a random hash.
- Compares the TSA genTime against the local system clock, accounting for network round-trip time.
- **Fails** if skew exceeds the critical threshold (default 30 seconds).
- **Warns** if skew is elevated but below critical.
## Why It Matters
Time skew between the system and TSA indicates that either the local clock or the TSA clock is drifting. This can produce timestamps that appear out of order relative to other events, undermining the temporal integrity of release evidence and audit trails.
## Common Causes
- Local system clock not synchronized with NTP
- TSA provider clock drifting
- High network latency distorting round-trip time estimation
- Proxy or load balancer adding variable latency
## How to Fix
### Docker Compose
Ensure the host clock is synchronized (see `check.timestamp.timesync.system`). If the TSA shows consistent skew, consider using a different provider.
### Bare Metal / systemd
```bash
# Verify system time sync
chronyc tracking
# Test TSA response time
curl -w "@curl-format.txt" -s -o /dev/null https://freetsa.org/tsr
```
### Kubernetes / Helm
Verify node-level NTP synchronization. If a specific TSA consistently shows skew, switch to an alternative provider.
## Verification
```
stella doctor run --check check.timestamp.timesync.tsa-skew
```
## Related Checks
- `check.timestamp.timesync.system` — checks system clock synchronization with NTP
- `check.timestamp.timesync.rekor-correlation` — checks TST-Rekor time correlation