Files

master c58a236d70 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>

2026-03-27 12:28:00 +02:00

3.7 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

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:

Registry configuration: whether the issuer trust registry is set up and operational.
Trusted issuer count: the number of issuers currently in the trust registry.
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

# 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

# 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

# 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"

# 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

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

3.7 KiB Raw Blame History