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.3 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

VEX Schema Compliance

What It Checks

Verifies that VEX document schema definitions are available for all three supported formats:

OpenVEX: the open-source VEX document format (checks version availability).
CSAF (Common Security Advisory Framework): the OASIS standard for security advisories with VEX profiles (checks version availability).
CycloneDX VEX: VEX capabilities embedded in CycloneDX BOM format (checks version availability).

Condition	Result
Any of the three schemas missing or unavailable	Fail
All three schemas available	Pass

Evidence collected: OpenVEX (version or "MISSING"), CSAF (version or "MISSING"), CycloneDX (version or "MISSING").

This check always runs (no precondition).

Why It Matters

VEX documents arrive in multiple formats from different sources (upstream vendors, internal security teams, community advisories). If a schema definition is missing, documents in that format cannot be validated, which means they are either rejected (blocking legitimate vulnerability updates) or accepted without validation (creating a security risk). Supporting all three major formats ensures Stella Ops can process VEX documents from any source in the software supply chain.

Common Causes

Schema files not installed during deployment
Schema version mismatch after an upgrade
Configuration error pointing to wrong schema directory
Incomplete installation missing one or more schema packages
Schema files corrupted or deleted during maintenance

How to Fix

Docker Compose

# Update all VEX schemas
docker compose exec vex-hub stella vex schemas update

# List installed schemas and versions
docker compose exec vex-hub stella vex schemas list

# Check schema directory
docker compose exec vex-hub ls -la /data/vex/schemas/

# Verify specific format support
docker compose exec vex-hub stella vex schemas verify --format openvex
docker compose exec vex-hub stella vex schemas verify --format csaf
docker compose exec vex-hub stella vex schemas verify --format cyclonedx

# Restart after schema update
docker compose restart vex-hub

Bare Metal / systemd

# Update VEX schemas
stella vex schemas update

# List installed schemas
stella vex schemas list

# Verify schema directory
ls -la /var/lib/stellaops/vex/schemas/

# Verify each format
stella vex schemas verify --format openvex
stella vex schemas verify --format csaf
stella vex schemas verify --format cyclonedx

sudo systemctl restart stellaops-vex-hub

Kubernetes / Helm

# values.yaml
vexHub:
  schemas:
    autoUpdate: true
    formats:
      openVex: true
      csaf: true
      cycloneDx: true

# Update schemas in pod
kubectl exec deploy/stellaops-vex-hub -- stella vex schemas update

# Verify all formats
kubectl exec deploy/stellaops-vex-hub -- stella vex schemas list

helm upgrade stellaops ./charts/stellaops -f values.yaml

Verification

stella doctor run --check check.vex.schema

check.vex.validation — document validation uses these schemas to verify incoming VEX documents
check.vex.issuer-trust — issuer trust works alongside schema validation in the processing pipeline

3.3 KiB Raw Blame History