Files

master c58a236d70 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>

2026-03-27 12:28:00 +02:00

2.2 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

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

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

{
  "Timestamping": {
    "TsaEndpoints": [
      { "Name": "FreeTSA", "Url": "https://freetsa.org/tsr" },
      { "Name": "DigiCert", "Url": "http://timestamp.digicert.com" }
    ]
  }
}

Test connectivity:

curl -I https://freetsa.org/tsr

Kubernetes / Helm

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

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

2.2 KiB Raw Blame History