checkId: check.binaryanalysis.corpus.mirror.freshness plugin: stellaops.doctor.binaryanalysis severity: warn tags: [binaryanalysis, corpus, mirrors, freshness, security, groundtruth]

Corpus Mirror Freshness

This Stella Ops Doctor check verifies that the local ground-truth corpus mirrors used by binary analysis are present and recently synced. 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 that local corpus mirrors are not stale. The check:

Reads the mirrors root directory (default /var/lib/stella/mirrors, configurable via BinaryAnalysis:Corpus:MirrorsDirectory).
Inspects five known mirror subdirectories: debian/archive, debian/snapshot, ubuntu/usn-index, alpine/secdb, and osv.
For each existing mirror, finds the most recent file modification time (sampling up to 1000 files) and compares it against a staleness threshold (default 7 days, configurable via BinaryAnalysis:Corpus:StalenessThresholdDays).
Fails if no mirrors exist or all mirrors are stale. Warns if some mirrors are stale. Reports info if all present mirrors are fresh but optional mirrors are missing.

Why It Matters

Corpus mirrors provide ground-truth vulnerability and package data for binary analysis. Stale mirrors mean symbol recovery operates on outdated data, leading to missed vulnerabilities and inaccurate matching in security scans.

Common Causes

Corpus mirrors have not been initialized
Mirror sync job has not run recently or is disabled
Network connectivity issues preventing sync
Air-gapped setup incomplete (mirrors not pre-populated)

How to Fix

Docker Compose

# Initialize all mirrors
docker exec <binaryindex-container> stella groundtruth mirror sync --all

Bare Metal / systemd

# Create mirrors directory
sudo mkdir -p /var/lib/stella/mirrors

# Sync all mirrors
stella groundtruth mirror sync --all

# Set up a timer for automatic sync
sudo systemctl enable stella-mirror-sync.timer
sudo systemctl start stella-mirror-sync.timer

Kubernetes / Helm

binaryAnalysis:
  corpus:
    mirrorsDirectory: "/var/lib/stella/mirrors"
    syncSchedule: "0 2 * * *"  # daily at 2am
    persistence:
      enabled: true
      size: 50Gi

For air-gapped environments, transfer pre-populated mirrors from an online system.

Verification

stella doctor run --check check.binaryanalysis.corpus.mirror.freshness

check.binaryanalysis.corpus.kpi.baseline — verifies KPI baseline exists for regression detection
check.binaryanalysis.symbol.recovery.fallback — meta-check for symbol recovery path availability