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

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

VEX Document Validation

What It Checks

Verifies the VEX document validation pipeline health by testing three subsystems:

Schema validation: confirms the schema validation service can parse and validate VEX documents against supported schemas. Reports valid and invalid document counts.
Signature verification: confirms that VEX document signatures can be verified using available issuer key material.
Processing pipeline: confirms the VEX processing queue is operational and measures queue depth and processing rate.

Results are aggregated across all three subsystems:

Condition	Result
Any subsystem failed (schema, signature, or pipeline)	Fail
All subsystems pass but warnings exist (e.g., high queue depth > 100)	Warn
All subsystems pass with no warnings	Pass

Evidence collected: SchemaValidation, SignatureVerification, ProcessingPipeline, ValidDocuments, InvalidDocuments, QueueDepth, QueueStatus.

This check always runs (no precondition).

Why It Matters

VEX (Vulnerability Exploitability eXchange) documents are the primary mechanism for communicating vulnerability status in the release pipeline. If schema validation fails, invalid VEX documents may be accepted, leading to incorrect vulnerability assessments. If signature verification fails, forged or tampered VEX documents could influence release decisions. If the processing pipeline is down or backed up, vulnerability status updates are delayed, potentially allowing releases with unresolved vulnerabilities to proceed.

Common Causes

VEX schema validation service unavailable or crashed
Invalid VEX document format detected in the incoming queue
Signature verification key material missing or expired
VEX processing queue backed up due to high volume
Issuer keys not imported into the trust registry
VEX processing worker not running

How to Fix

Docker Compose

# Check VEX processing status
docker compose exec vex-hub stella vex status

# Verify VEX document schema compliance
docker compose exec vex-hub stella vex verify --schema

# Check issuer key availability
docker compose exec vex-hub stella issuer keys list

# Check processing queue status
docker compose exec vex-hub stella vex queue status

# Review documents with validation warnings
docker compose exec vex-hub stella vex list --status warning

# Restart VEX processing worker if stuck
docker compose restart vex-hub

Bare Metal / systemd

# Check VEX processing status
stella vex status

# Verify schema compliance
stella vex verify --schema

# Check issuer keys
stella issuer keys list

# Check queue status
stella vex queue status

# List warning documents
stella vex list --status warning

sudo systemctl restart stellaops-vex-hub

Kubernetes / Helm

# Check VEX pod status
kubectl get pods -l app=stellaops-vex-hub

# Check processing status
kubectl exec deploy/stellaops-vex-hub -- stella vex status

# Verify schemas
kubectl exec deploy/stellaops-vex-hub -- stella vex verify --schema

# Check queue depth
kubectl exec deploy/stellaops-vex-hub -- stella vex queue status

# Check for OOM or resource issues
kubectl top pod -l app=stellaops-vex-hub

# values.yaml
vexHub:
  processing:
    workers: 2
    maxQueueDepth: 500
    schema:
      validation: strict

Verification

stella doctor run --check check.vex.validation

check.vex.issuer-trust — issuer trust registry provides keys for signature verification
check.vex.schema — schema compliance for supported VEX formats
check.compliance.evidence-integrity — VEX documents are evidence artifacts subject to integrity checks

3.7 KiB Raw Blame History