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

3.5 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

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:

No active key -- if HasActiveKey is false: Fail with "No active signing key available". Evidence includes ActiveKey: NONE and total key count.
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.
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

# 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

# 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

# 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

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)

3.5 KiB Raw Blame History