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