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,111 @@
---
checkId: check.scanner.vuln
plugin: stellaops.doctor.scanner
severity: warn
tags: [scanner, vulnerability, cve, database]
---
# Vulnerability Scan Health
## What It Checks
Queries the Scanner service at `/api/v1/vuln/stats` and evaluates vulnerability scanning health, focusing on database freshness:
- **Database freshness**: warn when the vulnerability database is older than 24 hours, fail when older than 72 hours.
- **Scan failure rate**: warn when scan failure rate exceeds 10%.
Evidence collected: `database_age_hours`, `last_db_update`, `total_cves`, `scans_completed`, `scan_failures`, `failure_rate`, `vulnerabilities_found`.
The check requires `Scanner:Url` or `Services:Scanner:Url` to be configured.
## Why It Matters
A stale vulnerability database means newly disclosed CVEs are not detected in scans, creating a false sense of security. Artifacts that pass policy gates with an outdated database may contain exploitable vulnerabilities that would have been caught with current data. In regulated environments, scan freshness is an auditable compliance requirement. High scan failure rates mean some artifacts are not being scanned at all.
## Common Causes
- Vulnerability database sync job failed or is not scheduled
- Feed source (NVD, OSV, vendor advisory) unavailable or rate-limited
- Network connectivity issue preventing feed downloads
- Scheduled sync delayed due to system overload
- Parsing errors on specific artifact formats
- Unsupported package ecosystem or lockfile format
## How to Fix
### Docker Compose
```bash
# Trigger an immediate database sync
stella scanner db sync
# Check sync job status
stella scanner db status
# View scanner logs for sync errors
docker compose -f docker-compose.stella-ops.yml logs scanner | grep -i "sync\|feed\|vuln"
```
Configure sync schedule in `docker-compose.stella-ops.yml`:
```yaml
services:
scanner:
environment:
Scanner__VulnDb__SyncIntervalHours: "6"
Scanner__VulnDb__FeedSources: "nvd,osv,github"
Scanner__VulnDb__RetryCount: "3"
```
### Bare Metal / systemd
```bash
# Trigger manual sync
stella scanner db sync
# Check sync schedule
stella scanner db schedule
# View sync logs
sudo journalctl -u stellaops-scanner --since "24 hours ago" | grep -i "sync\|feed"
```
Edit `/etc/stellaops/scanner/appsettings.json`:
```json
{
"VulnDb": {
"SyncIntervalHours": 6,
"FeedSources": ["nvd", "osv", "github"],
"RetryCount": 3
}
}
```
### Kubernetes / Helm
```bash
# Check scanner pod logs for sync status
kubectl logs -l app=stellaops-scanner --tail=100 | grep -i sync
# Verify CronJob for database sync exists and is running
kubectl get cronjobs -l app=stellaops-scanner-sync
```
Set in Helm `values.yaml`:
```yaml
scanner:
vulnDb:
syncIntervalHours: 6
feedSources:
- nvd
- osv
- github
retryCount: 3
syncCronJob:
schedule: "0 */6 * * *"
```
## Verification
```
stella doctor run --check check.scanner.vuln
```
## Related Checks
- `check.scanner.queue` -- scan failures may originate from queue processing issues
- `check.scanner.sbom` -- vulnerability matching depends on SBOM quality
- `check.scanner.reachability` -- reachability analysis uses vulnerability data to filter findings