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