stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Doctor plugin checks: implement health check classes and documentation

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

110
docs/doctor/articles/vex/issuer-trust.md Normal file
View File

@@ -0,0 +1,110 @@
---
checkId: check.vex.issuer-trust
plugin: stellaops.doctor.vex
severity: warn
tags: [vex, trust, issuer, security]
---
# VEX Issuer Trust Registry
## What It Checks
Verifies that the VEX issuer trust registry is configured and that key material is available for signature verification. The check evaluates:
1. **Registry configuration**: whether the issuer trust registry is set up and operational.
2. **Trusted issuer count**: the number of issuers currently in the trust registry.
3. **Key availability**: how many signing keys are available and how many are currently active.
| Condition | Result |
|---|---|
| Registry not configured | Fail |
| Registry configured but no trusted issuers | Warn |
| Registry configured with trusted issuers and active keys | Pass |
Evidence collected: `RegistryConfigured`, `TrustedIssuers`, `KeysAvailable`, `ActiveKeys`.
This check always runs (no precondition).
## Why It Matters
The issuer trust registry determines which VEX document sources are trusted. Without a configured registry, no VEX documents can have their signatures verified, which means all incoming vulnerability assessments are treated as unverified. Without any trusted issuers, even valid VEX documents from legitimate sources will be rejected or flagged. This undermines the VEX processing pipeline and means vulnerability status updates cannot be reliably applied to releases, potentially blocking compliant releases or allowing vulnerable ones.
## Common Causes
- Issuer directory not configured during initial setup
- Trust anchors not imported after deployment
- Configuration file missing or incorrect path
- All issuers expired or revoked without replacement
- No issuers added to the trust registry after installation
## How to Fix
### Docker Compose
```bash
# Configure issuer directory
docker compose exec vex-hub stella issuer directory configure
# Import default trust anchors
docker compose exec vex-hub stella trust-anchors import --defaults
# List available issuer keys
docker compose exec vex-hub stella issuer keys list --available
# Trust a known issuer
docker compose exec vex-hub stella issuer trust --url https://example.com/.well-known/vex-issuer
# Check current trust registry status
docker compose exec vex-hub stella issuer status
```
### Bare Metal / systemd
```bash
# Configure issuer directory
stella issuer directory configure
# Import default trust anchors
stella trust-anchors import --defaults
# List available keys
stella issuer keys list --available
# Trust a specific issuer
stella issuer trust --url https://example.com/.well-known/vex-issuer
# Check trust registry status
stella issuer status
sudo systemctl restart stellaops-vex-hub
```
### Kubernetes / Helm
```yaml
# values.yaml
vexHub:
issuerTrust:
importDefaults: true
trustedIssuers:
- name: "upstream-vendor"
url: "https://vendor.example.com/.well-known/vex-issuer"
- name: "internal-security"
url: "https://security.internal/.well-known/vex-issuer"
```
```bash
# Configure issuer directory
kubectl exec deploy/stellaops-vex-hub -- stella issuer directory configure
# Import trust anchors
kubectl exec deploy/stellaops-vex-hub -- stella trust-anchors import --defaults
# Check status
kubectl exec deploy/stellaops-vex-hub -- stella issuer status
helm upgrade stellaops ./charts/stellaops -f values.yaml
```
## Verification
```
stella doctor run --check check.vex.issuer-trust
```
## Related Checks
- `check.vex.validation` — document validation depends on issuer trust for signature verification
- `check.vex.schema` — schema compliance is checked alongside issuer trust
- `check.compliance.attestation-signing` — attestation signing uses related trust infrastructure

105
docs/doctor/articles/vex/schema.md Normal file
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

118
docs/doctor/articles/vex/validation.md Normal file
View File

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