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,61 @@
---
checkId: check.binaryanalysis.ddeb.enabled
plugin: stellaops.doctor.binaryanalysis
severity: warn
tags: [binaryanalysis, ddeb, ubuntu, symbols, security]
---
# Ubuntu Ddeb Repository
## What It Checks
Verifies Ubuntu debug symbol repository (ddebs.ubuntu.com) is configured and accessible. The check (Linux only):
- Parses `/etc/apt/sources.list` and `/etc/apt/sources.list.d/*.list` (and `.sources` DEB822 files) for entries containing `ddebs.ubuntu.com`.
- Tests HTTP connectivity to `http://ddebs.ubuntu.com` via a HEAD request.
- Detects the distribution codename from `/etc/lsb-release` or `/etc/os-release`.
- Reports different warnings based on whether the repo is configured, reachable, or both.
- Skips on non-Linux platforms.
## Why It Matters
The Ubuntu ddeb repository provides debug symbol packages (`-dbgsym`) needed for binary analysis of Ubuntu-based container images. Without debug symbols, binary matching accuracy is significantly reduced, weakening vulnerability detection for Ubuntu workloads.
## Common Causes
- Ddeb repository not added to apt sources
- Network connectivity issues preventing access to ddebs.ubuntu.com
- Firewall blocking HTTP access
- Running on a non-Ubuntu Linux distribution
## How to Fix
### Docker Compose
Add ddeb repository inside the binary analysis container:
```bash
docker exec <binaryindex-container> bash -c \
'echo "deb http://ddebs.ubuntu.com $(lsb_release -cs) main restricted universe multiverse" > /etc/apt/sources.list.d/ddebs.list'
docker exec <binaryindex-container> apt-key adv --keyserver keyserver.ubuntu.com \
--recv-keys F2EDC64DC5AEE1F6B9C621F0C8CAB6595FDFF622
docker exec <binaryindex-container> apt update
```
### Bare Metal / systemd
```bash
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs) main restricted universe multiverse" \
| sudo tee /etc/apt/sources.list.d/ddebs.list
sudo apt-key adv --keyserver keyserver.ubuntu.com \
--recv-keys F2EDC64DC5AEE1F6B9C621F0C8CAB6595FDFF622
sudo apt update
```
### Kubernetes / Helm
Include the ddeb repository in your container image's Dockerfile or use an init container to configure it at startup.
For air-gapped environments, set up a local ddeb mirror or use offline symbol packages.
## Verification
```
stella doctor run --check check.binaryanalysis.ddeb.enabled
```
## Related Checks
- `check.binaryanalysis.debuginfod.available` — verifies debuginfod service availability
- `check.binaryanalysis.symbol.recovery.fallback` — meta-check for symbol recovery path availability