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,108 @@
---
checkId: check.auth.config
plugin: stellaops.doctor.auth
severity: fail
tags: [auth, security, core, config]
---
# Auth Configuration
## What It Checks
Validates the overall authentication configuration by inspecting three layers in sequence:
1. **Authentication configured** -- verifies that the auth subsystem has been set up (issuer URL present, basic config loaded). If not: **Fail** with "Authentication not configured".
2. **Signing keys available** -- checks whether signing keys exist for token issuance. If configured but no keys: **Fail** with "No signing keys available".
3. **Signing key expiration** -- checks if the active signing key is approaching expiration. If it will expire soon: **Warn** with the number of days remaining.
4. **All healthy** -- issuer URL configured, signing keys available, key not near expiry. Result: **Pass**.
Evidence collected: `AuthConfigured` (YES/NO), `IssuerConfigured` (YES/NO), `IssuerUrl`, `SigningKeysConfigured`/`SigningKeysAvailable` (YES/NO), `KeyExpiration` (days), `ActiveClients` count, `ActiveScopes` count.
The check always runs (`CanRun` returns true).
## Why It Matters
Authentication is the foundation of every API call in Stella Ops. If the auth subsystem is not configured, no user can log in, no service-to-service call can authenticate, and the entire platform is non-functional. Missing signing keys mean tokens cannot be issued, and an expiring key that is not rotated will cause a hard outage when it expires.
## Common Causes
- Authority service not configured (fresh installation without `stella setup auth`)
- Missing issuer URL configuration in environment variables or config files
- Signing keys not yet generated (first-run setup incomplete)
- Key material corrupted (disk failure, accidental deletion)
- HSM/PKCS#11 module not accessible (hardware key store offline)
- Signing key approaching expiration without scheduled rotation
## How to Fix
### Docker Compose
```bash
# Check Authority service configuration
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
cat /app/appsettings.json | grep -A5 "Issuer\|Signing"
# Set issuer URL via environment variable
# In .env or docker-compose.override.yml:
# AUTHORITY__ISSUER__URL=https://stella-ops.local/authority
# Restart Authority service after config changes
docker compose -f devops/compose/docker-compose.stella-ops.yml restart authority
# Generate signing keys
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
stella keys generate --type rsa
```
### Bare Metal / systemd
```bash
# Run initial auth setup
stella setup auth
# Configure issuer URL
stella auth configure --issuer https://auth.yourdomain.com
# Generate signing keys
stella keys generate --type rsa
# Rotate signing keys (if approaching expiration)
stella keys rotate
# Schedule automatic key rotation
stella keys rotate --schedule 30d
# Check key store health
stella doctor run --check check.crypto.keystore
```
### Kubernetes / Helm
```bash
# Check authority pod configuration
kubectl get configmap stellaops-authority-config -n stellaops -o yaml
# Set issuer URL in Helm values
# authority:
# issuer:
# url: "https://auth.yourdomain.com"
helm upgrade stellaops stellaops/stellaops -f values.yaml
# Generate keys via job
kubectl exec -it deploy/stellaops-authority -n stellaops -- \
stella keys generate --type rsa
# Check secrets for key material
kubectl get secret stellaops-signing-keys -n stellaops
```
## Verification
```
stella doctor run --check check.auth.config
```
## Related Checks
- `check.auth.signing-key` -- deeper signing key health (algorithm, size, rotation schedule)
- `check.auth.token-service` -- verifies token endpoint is responsive
- `check.auth.oidc` -- external OIDC provider connectivity