---
checkId: check.vex.validation
plugin: stellaops.doctor.vex
severity: fail
tags: [vex, security, validation]
---
# VEX Document Validation

## What It Checks
Verifies the VEX document validation pipeline health by testing three subsystems:

1. **Schema validation**: confirms the schema validation service can parse and validate VEX documents against supported schemas. Reports valid and invalid document counts.
2. **Signature verification**: confirms that VEX document signatures can be verified using available issuer key material.
3. **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
```bash
# 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
```bash
# 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
```bash
# 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
```

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

## Verification
```
stella doctor run --check check.vex.validation
```

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