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