Files

master c58a236d70 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>

2026-03-27 12:28:00 +02:00

2.6 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

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:

environment:
  DEBUGINFOD_URLS: "https://debuginfod.fedoraproject.org"
  BinaryAnalysis__BuildinfoCache__Directory: "/var/cache/stella/buildinfo"

Bare Metal / systemd

# 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

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

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

2.6 KiB Raw Blame History