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