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,83 @@
---
checkId: check.security.apikey
plugin: stellaops.doctor.security
severity: warn
tags: [security, apikey, authentication]
---
# API Key Security
## What It Checks
Validates API key configuration and security practices. The check only runs when an API key configuration section exists (`ApiKey`, `Authentication:ApiKey`, or `Security:ApiKey`). It inspects:
| Setting | Threshold/Condition | Issue |
|---|---|---|
| `MinLength` | Less than 32 characters | Key too short (escalates to `fail` if < 16) |
| `AllowInQueryString` | `true` | Keys in query strings get logged in access logs |
| `HeaderName` | Equals `Authorization` | Conflicts with other auth schemes |
| `RateLimitPerKey` | `false` or not set | Compromised key could abuse the API without limits |
| `RotationDays` | Not set | No rotation policy configured |
| `RotationDays` | Greater than 365 | Rotation period is very long |
If API key authentication is explicitly disabled (`Enabled: false`), the check reports an informational result and exits.
## Why It Matters
API keys are the primary authentication mechanism for service-to-service communication and CI/CD integrations. Short keys can be brute-forced. Keys passed in query strings are recorded in web server access logs, proxy logs, and browser history, creating exposure vectors. Without per-key rate limiting, a compromised key allows unlimited API abuse. Without rotation, a leaked key remains valid indefinitely.
## Common Causes
- Minimum API key length configured below 32 characters
- API keys allowed in query strings (`AllowInQueryString: true`)
- Using the `Authorization` header for API keys, conflicting with JWT/OAuth
- Per-key rate limiting not enabled
- API key rotation policy not configured or set to more than 365 days
## How to Fix
### Docker Compose
Set API key security configuration in environment variables:
```yaml
environment:
ApiKey__MinLength: "32"
ApiKey__AllowInQueryString: "false"
ApiKey__HeaderName: "X-API-Key"
ApiKey__RateLimitPerKey: "true"
ApiKey__RotationDays: "90"
```
### Bare Metal / systemd
Edit `appsettings.json`:
```json
{
"ApiKey": {
"Enabled": true,
"MinLength": 32,
"HeaderName": "X-API-Key",
"AllowInQueryString": false,
"RateLimitPerKey": true,
"RotationDays": 90
}
}
```
### Kubernetes / Helm
Set in Helm values:
```yaml
apiKey:
minLength: 32
headerName: "X-API-Key"
allowInQueryString: false
rateLimitPerKey: true
rotationDays: 90
```
## Verification
```
stella doctor run --check check.security.apikey
```
## Related Checks
- `check.security.ratelimit` validates global rate limiting configuration
- `check.security.secrets` ensures API keys are not stored as plain text
- `check.core.auth.config` validates overall authentication configuration