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

Debian Buildinfo Cache

What It Checks

Verifies Debian buildinfo service accessibility and local cache directory configuration. The check:

Tests HTTPS connectivity to buildinfos.debian.net and reproduce.debian.net via HEAD requests.
Checks the local cache directory (default /var/cache/stella/buildinfo, configurable via BinaryAnalysis:BuildinfoCache:Directory) for existence and writability by creating and deleting a temp file.
Fails if both services are unreachable AND the cache directory does not exist.
Warns if services are unreachable but the cache exists (offline mode possible), or if services are reachable but the cache directory is missing or not writable.

Why It Matters

Buildinfo files from Debian are used for reproducible-build verification. Without access to buildinfo services or a local cache, binary analysis cannot verify whether packages were built reproducibly, degrading supply-chain assurance for Debian-based container images.

Common Causes

Firewall blocking HTTPS access to Debian buildinfo services
Network connectivity issues or DNS resolution failure
Proxy configuration required but not set
Cache directory not created
Insufficient permissions on cache directory

How to Fix

Docker Compose

environment:
  BinaryAnalysis__BuildinfoCache__Directory: "/var/cache/stella/buildinfo"
volumes:
  - buildinfo-cache:/var/cache/stella/buildinfo

Test connectivity:

docker exec <binaryindex-container> curl -I https://buildinfos.debian.net

Bare Metal / systemd

# Create cache directory
sudo mkdir -p /var/cache/stella/buildinfo
sudo chmod 755 /var/cache/stella/buildinfo

# Test connectivity
curl -I https://buildinfos.debian.net

# If behind a proxy
export HTTPS_PROXY=http://proxy.example.com:8080

Kubernetes / Helm

binaryAnalysis:
  buildinfo:
    cacheDirectory: "/var/cache/stella/buildinfo"
    persistence:
      enabled: true
      size: 5Gi

For air-gapped environments, pre-populate the buildinfo cache with required files or disable this check.

Verification

stella doctor run --check check.binaryanalysis.buildinfo.cache

check.binaryanalysis.symbol.recovery.fallback — meta-check ensuring at least one symbol recovery path is available
check.binaryanalysis.debuginfod.available — verifies debuginfod service connectivity

2.5 KiB Raw Blame History