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>
This commit is contained in:
master
2026-03-27 12:28:00 +02:00
parent fbd24e71de
commit c58a236d70
326 changed files with 18500 additions and 463 deletions

View File

@@ -0,0 +1,105 @@
---
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