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.5 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

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

environment:
  DEBUGINFOD_URLS: "https://debuginfod.fedoraproject.org"

Test connectivity:

docker exec <binaryindex-container> curl -I https://debuginfod.fedoraproject.org

Bare Metal / systemd

# 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

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

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

2.5 KiB Raw Blame History