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:
74
docs/doctor/articles/binary-analysis/buildinfo-cache.md
Normal file
74
docs/doctor/articles/binary-analysis/buildinfo-cache.md
Normal 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
|
||||
Reference in New Issue
Block a user