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,72 @@
---
checkId: check.timestamp.tsa.reachable
plugin: stellaops.doctor.timestamping
severity: fail
tags: [timestamping, tsa, availability, connectivity]
---
# TSA Availability
## What It Checks
Verifies that configured TSA (Time Stamp Authority) endpoints are reachable and responding. The check:
- Probes each endpoint from the `TsaEndpoints` configuration via HTTP HEAD requests.
- Considers HTTP 2xx and 405 (Method Not Allowed) as healthy responses (405 means the TSA is alive but only accepts POST).
- Reports the count of healthy vs. unhealthy endpoints.
- Degrades if no endpoints are configured. Fails if no endpoints are reachable. Warns if some are down.
## Why It Matters
TSA endpoints provide RFC-3161 timestamps that anchor release evidence in time. If no TSA is reachable, new evidence cannot be timestamped, blocking policy-gated releases that require verifiable timestamps. This is a critical-severity check.
## Common Causes
- TSA endpoint server is down or unreachable
- Network connectivity issues or firewall blocking HTTPS
- DNS resolution failure
- TSA provider maintenance or outage
## How to Fix
### Docker Compose
```yaml
environment:
Timestamping__TsaEndpoints__0__Name: "FreeTSA"
Timestamping__TsaEndpoints__0__Url: "https://freetsa.org/tsr"
Timestamping__TsaEndpoints__1__Name: "DigiCert"
Timestamping__TsaEndpoints__1__Url: "http://timestamp.digicert.com"
```
### Bare Metal / systemd
```json
{
"Timestamping": {
"TsaEndpoints": [
{ "Name": "FreeTSA", "Url": "https://freetsa.org/tsr" },
{ "Name": "DigiCert", "Url": "http://timestamp.digicert.com" }
]
}
}
```
Test connectivity:
```bash
curl -I https://freetsa.org/tsr
```
### Kubernetes / Helm
```yaml
timestamping:
tsaEndpoints:
- name: "FreeTSA"
url: "https://freetsa.org/tsr"
- name: "DigiCert"
url: "http://timestamp.digicert.com"
```
## Verification
```
stella doctor run --check check.timestamp.tsa.reachable
```
## Related Checks
- `check.timestamp.tsa.response-time` — measures TSA response latency
- `check.timestamp.tsa.valid-response` — verifies TSA returns valid RFC-3161 responses
- `check.timestamp.tsa.failover-ready` — confirms backup TSA endpoints for failover