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,106 @@
---
checkId: check.auth.signing-key
plugin: stellaops.doctor.auth
severity: fail
tags: [auth, security, keys]
---
# Signing Key Health
## What It Checks
Verifies the health of the active signing key used for token issuance. The check evaluates three conditions in sequence:
1. **No active key** -- if `HasActiveKey` is false: **Fail** with "No active signing key available". Evidence includes `ActiveKey: NONE` and total key count.
2. **Approaching expiration** -- if the active key expires within **30 days** (`ExpirationWarningDays`): **Warn** with the number of days remaining. Evidence includes key ID, algorithm, days until expiration, and whether rotation is scheduled.
3. **Healthy** -- active key exists with more than 30 days until expiration. Result: **Pass**. Evidence includes key ID, algorithm, key size (bits), days until expiration, and rotation schedule status.
The check always runs (`CanRun` returns true).
Evidence collected: `ActiveKeyId`, `Algorithm`, `KeySize`, `DaysUntilExpiration`, `RotationScheduled` (YES/NO), `TotalKeys`.
## Why It Matters
The signing key is used to sign every JWT token issued by the Authority service. If no active key exists, no tokens can be issued, and the entire platform's authentication stops working. If the key is approaching expiration without a rotation plan, the platform faces a hard outage on the expiration date -- all tokens signed with the key become unverifiable.
## Common Causes
- Signing keys not generated (incomplete setup)
- All keys expired without rotation
- Key store corrupted (file system issue, accidental deletion)
- Key rotation not scheduled (manual process that was forgotten)
- Previous rotation attempt failed (permissions, HSM connectivity)
## How to Fix
### Docker Compose
```bash
# Check current key status
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
stella keys status
# Generate new signing key
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
stella keys generate --type rsa --bits 4096
# Activate the new key
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
stella keys activate
# Rotate keys
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
stella keys rotate
```
### Bare Metal / systemd
```bash
# Generate new signing key
stella keys generate --type rsa --bits 4096
# Activate the key
stella keys activate
# Rotate signing key
stella keys rotate
# Schedule automatic rotation (every 30 days)
stella keys rotate --schedule 30d
# Check key status
stella keys status
```
### Kubernetes / Helm
```bash
# Check key status
kubectl exec -it deploy/stellaops-authority -n stellaops -- \
stella keys status
# Generate and activate key
kubectl exec -it deploy/stellaops-authority -n stellaops -- \
stella keys generate --type rsa --bits 4096
# Set automatic rotation in Helm values
# authority:
# signing:
# autoRotate: true
# rotationIntervalDays: 30
helm upgrade stellaops stellaops/stellaops -f values.yaml
# Check signing key secret
kubectl get secret stellaops-signing-keys -n stellaops -o jsonpath='{.data}' | base64 -d
```
## Verification
```
stella doctor run --check check.auth.signing-key
```
## Related Checks
- `check.auth.config` -- overall auth configuration including signing key presence
- `check.auth.token-service` -- token issuance depends on a healthy signing key
- `check.attestation.keymaterial` -- attestor signing keys (separate from auth signing keys)