VexTrustGate Rollout Guide

This guide describes the phased rollout procedure for VexTrustGate, the Policy Engine gate that enforces VEX signature-verification trust thresholds before a finding’s status is allowed to transition.

Audience: platform operators and policy owners enabling trust-gated VEX enforcement across Dev, Stage, and Prod. Roll out the gate incrementally — warn first, then block — so you can tune thresholds against real traffic before any release is blocked.

Overview

VexTrustGate is a Policy Engine gate that:

Validates VEX signature-verification trust scores.
Enforces per-environment thresholds (production stricter than staging/development).
Blocks or warns on status transitions when trust is insufficient.
Contributes to confidence scoring via VexTrustConfidenceFactorProvider.

Gate Order

VexTrustGate runs at order 250 in the policy gate chain:

Order	Gate
100	EvidenceCompleteness
200	LatticeState
250	VexTrust
300	UncertaintyTier
400	Confidence

Prerequisites

VEX signature-verification pipeline active.
Issuer Directory populated with trusted VEX sources (see Issuer Directory and Trust).
Excititor populating VexTrustStatus in API responses.

Rollout Phases

Phase 1: Feature Flag Deployment

Deploy with gate disabled to establish baseline:

PolicyGates:
  VexTrust:
    Enabled: false  # Gate off initially

Duration: 1-2 days Monitoring: Verify deployment health, no regression in existing gates.

Phase 2: Shadow Mode (Warn Everywhere)

Enable gate in warn-only mode across all environments:

PolicyGates:
  VexTrust:
    Enabled: true
    Thresholds:
      production:
        MinCompositeScore: 0.80
        RequireIssuerVerified: true
        FailureAction: Warn  # Changed from Block
      staging:
        MinCompositeScore: 0.60
        RequireIssuerVerified: true
        FailureAction: Warn
      development:
        MinCompositeScore: 0.40
        RequireIssuerVerified: false
        FailureAction: Warn
    MissingTrustBehavior: Warn

Duration: 1-2 weeks Monitoring:

Review stellaops.policy.vex_trust_gate.decisions.total metrics.
Analyze warn events to understand threshold impact.
Collect operator feedback on false positives.

Phase 3: Threshold Tuning

Based on Phase 2 data, adjust thresholds:

Review decision breakdown by reason:
- composite_score: May need to lower threshold
- issuer_verified: Check IssuerDirectory completeness
- freshness: Consider expanding acceptable states

Tenant-specific adjustments (if needed):

PolicyGates:
  VexTrust:
    TenantOverrides:
      tenant-with-internal-vex:
        production:
          MinCompositeScore: 0.70  # Lower for self-signed internal VEX
      high-security-tenant:
        production:
          MinCompositeScore: 0.90  # Higher for regulated workloads

Duration: 1 week Outcome: Validated threshold configuration

Phase 4: Production Enforcement

Enable blocking in production only:

PolicyGates:
  VexTrust:
    Enabled: true
    Thresholds:
      production:
        MinCompositeScore: 0.80
        RequireIssuerVerified: true
        MinAccuracyRate: 0.85
        AcceptableFreshness:
          - fresh
        FailureAction: Block  # Now enforcing
      staging:
        FailureAction: Warn  # Still warn only
      development:
        FailureAction: Warn

Duration: Ongoing with monitoring Rollback: Set FailureAction: Warn or Enabled: false if issues arise.

Phase 5: Full Rollout

After production stabilization, optionally enable blocking in staging:

PolicyGates:
  VexTrust:
    Thresholds:
      staging:
        MinCompositeScore: 0.60
        RequireIssuerVerified: true
        FailureAction: Block  # Optional stricter staging

Monitoring

Key Metrics

Metric	Description	Alert Threshold
`stellaops.policy.vex_trust_gate.evaluations.total`	Total evaluations	Baseline variance
`stellaops.policy.vex_trust_gate.decisions.total{decision="block"}`	Block decisions	Sudden spike
`stellaops.policy.vex_trust_gate.trust_score`	Score distribution	Mean < 0.50
`stellaops.policy.vex_trust_gate.evaluation_duration_ms`	Latency	p99 > 100ms

Trace Spans

VexTrustGate.EvaluateAsync
- Attributes: environment, trust_score, decision, issuer_id

Audit Trail

PolicyAuditEntity now includes VEX trust fields:

VexTrustScore: Composite score at decision time
VexTrustTier: Tier classification
VexSignatureVerified: Whether signature was verified
VexIssuerId/VexIssuerName: Issuer info
VexTrustGateResult: Gate decision
VexTrustGateReason: Reason code

Rollback Procedure

Immediate Disable

PolicyGates:
  VexTrust:
    Enabled: false

Switch to Warn Mode

PolicyGates:
  VexTrust:
    Thresholds:
      production:
        FailureAction: Warn
      staging:
        FailureAction: Warn
      development:
        FailureAction: Warn

Per-Tenant Disable

PolicyGates:
  VexTrust:
    TenantOverrides:
      affected-tenant:
        production:
          MinCompositeScore: 0.01  # Effectively bypass
          RequireIssuerVerified: false

Troubleshooting

Common Issues

Symptom	Likely Cause	Resolution
All VEX blocked	Missing IssuerDirectory entries	Populate directory with trusted issuers
High false positive rate	Threshold too strict	Lower `MinCompositeScore`
“missing_vex_trust_data” warnings	Verification pipeline not running	Check Excititor logs
Inconsistent decisions	Stale trust cache	Verify cache TTL settings

Debug Logging

Enable debug logging for gate:

Logging:
  LogLevel:
    StellaOps.Policy.Engine.Gates.VexTrustGate: Debug

References

Component: StellaOps.Policy.Engine.Gates
Source:
- src/Policy/StellaOps.Policy.Engine/Gates/VexTrustGate.cs
- src/Policy/StellaOps.Policy.Engine/Gates/VexTrustGateOptions.cs
Related guides: Issuer Directory and Trust, Consensus overview