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,69 @@
---
checkId: check.binaryanalysis.symbol.recovery.fallback
plugin: stellaops.doctor.binaryanalysis
severity: warn
tags: [binaryanalysis, symbols, fallback, security, meta]
---
# Symbol Recovery Fallback
## What It Checks
Meta-check that ensures at least one symbol recovery path is available. The check aggregates results from three child checks:
- **Debuginfod Availability** (`check.binaryanalysis.debuginfod.available`)
- **Ubuntu Ddeb Repository** (`check.binaryanalysis.ddeb.enabled`) -- skipped on non-Linux
- **Debian Buildinfo Cache** (`check.binaryanalysis.buildinfo.cache`)
Fails if zero sources are available. Reports info if some but not all sources are available. Passes if all sources are operational.
## Why It Matters
Symbol recovery is critical for binary analysis accuracy. If all symbol sources are unavailable, binary matching operates without debug information, severely degrading vulnerability detection quality. Having at least one source ensures a minimum level of binary analysis capability; having multiple sources provides redundancy.
## Common Causes
- All symbol recovery endpoints unreachable
- Network connectivity issues affecting all sources
- Firewall blocking access to symbol servers
- Air-gapped environment without offline symbol cache configured
## How to Fix
### Docker Compose
Configure at least one symbol source:
```yaml
environment:
DEBUGINFOD_URLS: "https://debuginfod.fedoraproject.org"
BinaryAnalysis__BuildinfoCache__Directory: "/var/cache/stella/buildinfo"
```
### Bare Metal / systemd
```bash
# Option 1: Configure debuginfod
export DEBUGINFOD_URLS="https://debuginfod.fedoraproject.org"
# Option 2: Set up buildinfo cache
sudo mkdir -p /var/cache/stella/buildinfo
# Option 3: Configure ddeb repository (Ubuntu)
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ddebs.list
```
### Kubernetes / Helm
```yaml
binaryAnalysis:
debuginfod:
urls: "https://debuginfod.fedoraproject.org"
buildinfo:
cacheDirectory: "/var/cache/stella/buildinfo"
```
For air-gapped environments, set up an offline symbol bundle. See `docs/modules/binary-index/ground-truth-corpus.md` for instructions on creating and importing offline symbol packs.
## Verification
```
stella doctor run --check check.binaryanalysis.symbol.recovery.fallback
```
## Related Checks
- `check.binaryanalysis.debuginfod.available` — individual debuginfod connectivity check
- `check.binaryanalysis.ddeb.enabled` — individual Ubuntu ddeb repository check
- `check.binaryanalysis.buildinfo.cache` — individual Debian buildinfo cache check