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:
105
docs/doctor/articles/vex/schema.md
Normal file
105
docs/doctor/articles/vex/schema.md
Normal 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
|
||||
Reference in New Issue
Block a user