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

3.2 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

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

# 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:

services:
  scanner:
    environment:
      Scanner__VulnDb__SyncIntervalHours: "6"
      Scanner__VulnDb__FeedSources: "nvd,osv,github"
      Scanner__VulnDb__RetryCount: "3"

Bare Metal / systemd

# 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:

{
  "VulnDb": {
    "SyncIntervalHours": 6,
    "FeedSources": ["nvd", "osv", "github"],
    "RetryCount": 3
  }
}

Kubernetes / Helm

# 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:

scanner:
  vulnDb:
    syncIntervalHours: 6
    feedSources:
      - nvd
      - osv
      - github
    retryCount: 3
  syncCronJob:
    schedule: "0 */6 * * *"

Verification

stella doctor run --check check.scanner.vuln

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

3.2 KiB Raw Blame History