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:
106
docs/doctor/articles/auth/signing-key.md
Normal file
106
docs/doctor/articles/auth/signing-key.md
Normal 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)
|
||||
Reference in New Issue
Block a user