checkId: check.vex.schema plugin: stellaops.doctor.vex severity: warn tags: [vex, schema, compliance]

VEX Schema Compliance

Doctor check that confirms Stella Ops has the schema definitions needed to validate VEX documents in every supported format. Aimed at operators verifying that a deployment can ingest VEX from any source in the software supply chain.

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