---
checkId: check.binaryanalysis.debuginfod.available
plugin: stellaops.doctor.binaryanalysis
severity: warn
tags: [binaryanalysis, debuginfod, symbols, security]
---
# 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
```yaml
environment:
  DEBUGINFOD_URLS: "https://debuginfod.fedoraproject.org"
```

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

### Bare Metal / systemd
```bash
# 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
```yaml
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
```

## 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