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:
@@ -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
|
||||
Reference in New Issue
Block a user