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