checkId: check.vex.issuer-trust plugin: stellaops.doctor.vex severity: warn tags: [vex, trust, issuer, security]

VEX Issuer Trust Registry

Doctor check that confirms Stella Ops trusts the right VEX issuers and holds the keys needed to verify their signatures. Aimed at operators and security engineers configuring which VEX document sources the platform will accept.

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.
ConditionResult
Registry not configuredFail
Registry configured but no trusted issuersWarn
Registry configured with trusted issuers and active keysPass

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

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