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,75 @@
---
checkId: check.integration.oidc
plugin: stellaops.doctor.integration
severity: warn
tags: [connectivity, oidc, auth, identity]
---
# OIDC Provider
## What It Checks
Reads the OIDC issuer URL from `Oidc:Issuer`, `Authentication:Oidc:Issuer`, or `Authority:Oidc:Issuer`. Fetches the OpenID Connect discovery document at `<issuer>/.well-known/openid-configuration`. On a successful response, parses the JSON for three required endpoints: `authorization_endpoint`, `token_endpoint`, and `jwks_uri`. The check **passes** if all three are present, **warns** if the discovery document is incomplete (missing one or more endpoints), **fails** if the discovery endpoint returns a non-success status code, and **fails** on connection errors.
## Why It Matters
OIDC authentication is the primary identity mechanism for Stella Ops operators and API clients. If the OIDC provider is unreachable or misconfigured, users cannot log in, API tokens cannot be validated, and all authenticated workflows halt. An incomplete discovery document causes subtle failures where some auth flows work but others (e.g., token refresh) silently break.
## Common Causes
- OIDC issuer URL is incorrect or has a trailing slash issue
- OIDC provider (Authority, Keycloak, Azure AD, etc.) is down
- Network connectivity issues between Stella Ops and the identity provider
- Provider does not support OpenID Connect discovery
- Discovery document is missing required endpoints
## How to Fix
### Docker Compose
```bash
# Check OIDC configuration
grep 'OIDC__ISSUER\|AUTHENTICATION__OIDC' .env
# Test discovery endpoint
docker compose exec gateway curl -sv \
https://auth.example.com/.well-known/openid-configuration
# Verify the Authority service is running
docker compose ps authority
# Update issuer URL
echo 'Oidc__Issuer=https://auth.example.com' >> .env
docker compose restart gateway platform
```
### Bare Metal / systemd
```bash
# Verify configuration
cat /etc/stellaops/appsettings.Production.json | jq '.Oidc'
# Test discovery
curl -v https://auth.example.com/.well-known/openid-configuration
# Check required fields in the response
curl -s https://auth.example.com/.well-known/openid-configuration \
| jq '{authorization_endpoint, token_endpoint, jwks_uri}'
# Fix configuration
sudo nano /etc/stellaops/appsettings.Production.json
sudo systemctl restart stellaops-platform
```
### Kubernetes / Helm
```yaml
# values.yaml
oidc:
issuer: https://auth.example.com
clientId: stellaops-ui
```
```bash
helm upgrade stellaops ./chart -f values.yaml
```
## Verification
```
stella doctor run --check check.integration.oidc
```
## Related Checks
- `check.integration.ldap` -- alternative directory-based authentication