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,71 @@
---
checkId: check.binaryanalysis.debuginfod.available
plugin: stellaops.doctor.binaryanalysis
severity: warn
tags: [binaryanalysis, debuginfod, symbols, security]
---
# Debuginfod Availability
## What It Checks
Verifies DEBUGINFOD_URLS environment variable and debuginfod service connectivity. The check:
- Reads the `DEBUGINFOD_URLS` environment variable (space-separated list of URLs).
- If not set, falls back to the default Fedora debuginfod at `https://debuginfod.fedoraproject.org`.
- Tests HTTP connectivity to each URL via HEAD requests.
- Reports info if DEBUGINFOD_URLS is not set but the default is reachable.
- Warns if some configured URLs are unreachable. Fails if none are reachable.
## Why It Matters
Debuginfod provides on-demand debug information (DWARF, source) for ELF binaries. It is the primary mechanism for symbol recovery in binary analysis. Without a reachable debuginfod endpoint, binary matching accuracy drops significantly, reducing the effectiveness of vulnerability correlation and reachability analysis.
## Common Causes
- `DEBUGINFOD_URLS` environment variable is not set
- Configured debuginfod servers may be down
- Firewall blocking HTTPS access to debuginfod servers
- Proxy configuration required but not set
- DNS resolution failure for debuginfod hostnames
## How to Fix
### Docker Compose
```yaml
environment:
DEBUGINFOD_URLS: "https://debuginfod.fedoraproject.org"
```
Test connectivity:
```bash
docker exec <binaryindex-container> curl -I https://debuginfod.fedoraproject.org
```
### Bare Metal / systemd
```bash
# Set the environment variable
export DEBUGINFOD_URLS="https://debuginfod.fedoraproject.org"
# Or add to service file
sudo systemctl edit stellaops-binaryindex
# Add: Environment=DEBUGINFOD_URLS=https://debuginfod.fedoraproject.org
# Verify connectivity
curl -I https://debuginfod.fedoraproject.org
```
### Kubernetes / Helm
```yaml
binaryAnalysis:
debuginfod:
urls: "https://debuginfod.fedoraproject.org"
```
For air-gapped environments, deploy a local debuginfod instance or use offline symbol bundles. See `docs/modules/binary-index/ground-truth-corpus.md` for offline setup.
## Verification
```
stella doctor run --check check.binaryanalysis.debuginfod.available
```
## Related Checks
- `check.binaryanalysis.ddeb.enabled` — verifies Ubuntu ddeb repository availability
- `check.binaryanalysis.buildinfo.cache` — verifies Debian buildinfo service and cache
- `check.binaryanalysis.symbol.recovery.fallback` — meta-check aggregating all symbol sources