---
checkId: check.vex.schema
plugin: stellaops.doctor.vex
severity: warn
tags: [vex, schema, compliance]
---
# 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
```bash
# 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
```bash
# 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
```yaml
# values.yaml
vexHub:
  schemas:
    autoUpdate: true
    formats:
      openVex: true
      csaf: true
      cycloneDx: true
```

```bash
# 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
```

## Related Checks
- `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