checkId: check.binaryanalysis.debuginfod.available plugin: stellaops.doctor.binaryanalysis severity: warn tags: [binaryanalysis, debuginfod, symbols, security, air-gap]

Debuginfod Availability

This Stella Ops Doctor check verifies that a debuginfod endpoint is configured and reachable so binary analysis can recover debug information on demand. It is part of the binary-analysis diagnostics surfaced by stella doctor; see the Doctor overview for how checks are run and reported.

What It Checks

Verifies the 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.

Air-Gap Behavior

When the deployment is sealed by AirGap policy, or STELLAOPS_DOCTOR_OFFLINE_PROFILE=true forces Doctor offline mode, this check returns Skip with airGapSealed=true instead of contacting public or external debuginfod endpoints.

Sealed deployments should provide symbols through a local debuginfod mirror or offline symbol bundles imported from the offline kit. Point DEBUGINFOD_URLS at the internal mirror when available; otherwise rely on the binary-analysis offline corpus and symbol-recovery fallback checks.

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 the ground-truth corpus guide 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