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>
This commit is contained in:
master
2026-03-27 12:28:00 +02:00
parent fbd24e71de
commit c58a236d70
326 changed files with 18500 additions and 463 deletions

View File

@@ -0,0 +1,74 @@
---
checkId: check.binaryanalysis.buildinfo.cache
plugin: stellaops.doctor.binaryanalysis
severity: warn
tags: [binaryanalysis, buildinfo, debian, cache, security]
---
# 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
```yaml
environment:
BinaryAnalysis__BuildinfoCache__Directory: "/var/cache/stella/buildinfo"
volumes:
- buildinfo-cache:/var/cache/stella/buildinfo
```
Test connectivity:
```bash
docker exec <binaryindex-container> curl -I https://buildinfos.debian.net
```
### Bare Metal / systemd
```bash
# 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
```yaml
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
```
## Related Checks
- `check.binaryanalysis.symbol.recovery.fallback` — meta-check ensuring at least one symbol recovery path is available
- `check.binaryanalysis.debuginfod.available` — verifies debuginfod service connectivity