VEX Trust Lattice Specification

Status: Implementation Complete (Sprint 7100) Version: 1.0.0 Last Updated: 2025-12-22 Source Advisory: docs/product/advisories/archived/22-Dec-2026 - Building a Trust Lattice for VEX Sources.md

1. Overview

The VEX Trust Lattice provides a mathematically rigorous framework for converting heterogeneous VEX claims from multiple sources into a single, signed, reproducible verdict with a numeric confidence and a complete audit trail.

Goals

1. Explainability: Every verdict includes a full breakdown of how it was computed
2. Reproducibility: Same inputs always produce identical verdicts (deterministic)
3. Auditability: Signed verdict manifests with pinned inputs for regulatory compliance
4. Tunability: Per-tenant, per-source trust configuration without code changes

Non-Goals

• Real-time vulnerability detection (handled by Scanner)
• VEX document ingestion (handled by Excititor core)
• Policy enforcement (handled by Policy Engine)

2. Trust Vector Model

Each VEX source is assigned a 3-component trust vector scored in the range [0…1].

2.1 Provenance (P)

Measures cryptographic and process integrity of the source.

2.2 Coverage ©

Measures how well the statement’s scope maps to the target asset.

2.3 Replayability ®

Measures whether the claim can be deterministically re-derived.

2.4 Weight Configuration

The base trust score is computed as:

BaseTrust(S) = wP * P + wC * C + wR * R

Default weights:

• wP = 0.45 (Provenance)
• wC = 0.35 (Coverage)
• wR = 0.20 (Replayability)

Weights are tunable per policy and sum to 1.0.

3. Claim Scoring

3.1 Base Trust Calculation

double BaseTrust(double P, double C, double R, TrustWeights W)
    => W.wP * P + W.wC * C + W.wR * R;

3.2 Claim Strength Multipliers (M)

Each VEX claim carries a strength multiplier based on evidence quality:

3.3 Freshness Decay (F)

Time-decay curve with configurable half-life:

double Freshness(DateTime issuedAt, DateTime cutoff, double halfLifeDays = 90, double floor = 0.35)
{
    var ageDays = (cutoff - issuedAt).TotalDays;
    var decay = Math.Exp(-Math.Log(2) * ageDays / halfLifeDays);
    return Math.Max(decay, floor);
}

Parameters:

• halfLifeDays = 90 (default): Score halves every 90 days
• floor = 0.35 (default): Minimum freshness unless revoked

3.4 ClaimScore Formula

ClaimScore = BaseTrust(S) * M * F

Example calculation:

Source: Red Hat (Vendor)
  P = 0.90, C = 0.75, R = 0.60
  BaseTrust = 0.45*0.90 + 0.35*0.75 + 0.20*0.60 = 0.405 + 0.2625 + 0.12 = 0.7875

Claim: ConfigWithEvidence (M = 0.80)
Freshness: 30 days old (F = 0.79)

ClaimScore = 0.7875 * 0.80 * 0.79 = 0.498

4. Lattice Merge Algorithm

4.1 Partial Ordering

Claims are ordered by a tuple: (scope_specificity, ClaimScore).

Scope specificity levels:

1. Exact digest match (highest)
2. Exact version match
3. Version range match
4. Product family match
5. Platform match (lowest)

4.2 Conflict Detection

Conflicts occur when claims for the same (CVE, Asset) have different statuses:

bool HasConflict(IEnumerable<Claim> claims)
    => claims.Select(c => c.Status).Distinct().Count() > 1;

4.3 Conflict Penalty

When conflicts exist, apply a penalty to weaker/older claims:

const double ConflictPenalty = 0.25;

if (contradictory)
{
    var strongest = claims.OrderByDescending(c => c.Score).First();
    foreach (var claim in claims.Where(c => c.Status != strongest.Status))
    {
        claim.AdjustedScore = claim.Score * (1 - ConflictPenalty);
    }
}

4.4 Winner Selection

Final verdict is selected by:

var winner = scored
    .OrderByDescending(x => (x.Claim.ScopeSpecificity, x.AdjustedScore))
    .First();

4.5 Audit Trail Generation

Every merge produces:

public sealed record MergeResult
{
    public VexStatus Status { get; init; }
    public double Confidence { get; init; }
    public ImmutableArray<VerdictExplanation> Explanations { get; init; }
    public ImmutableArray<string> EvidenceRefs { get; init; }
    public string PolicyHash { get; init; }
    public string LatticeVersion { get; init; }
}

5. Policy Gates

Gates are evaluated after merge to enforce policy requirements.

5.1 MinimumConfidenceGate

Requires minimum confidence by environment for certain statuses.

gates:
  minimumConfidence:
    enabled: true
    thresholds:
      production: 0.75
      staging: 0.60
      development: 0.40
    applyToStatuses:
      - not_affected
      - fixed

Behavior: Fails if confidence < threshold for specified statuses.

5.2 UnknownsBudgetGate

Limits exposure to unknown/unscored dependencies.

gates:
  unknownsBudget:
    enabled: true
    maxUnknownCount: 5
    maxCumulativeUncertainty: 2.0

Behavior: Fails if:

• #unknown_deps > maxUnknownCount, OR
• sum(1 - ClaimScore) > maxCumulativeUncertainty

5.3 SourceQuotaGate

Prevents single-source dominance without corroboration.

gates:
  sourceQuota:
    enabled: true
    maxInfluencePercent: 60
    corroborationDelta: 0.10

Behavior: Fails if single source influence > 60% AND no second source within delta=0.10.

5.4 ReachabilityRequirementGate

Requires reachability proof for critical vulnerabilities.

gates:
  reachabilityRequirement:
    enabled: true
    severityThreshold: CRITICAL
    requiredForStatuses:
      - not_affected
    bypassReasons:
      - component_not_present

Behavior: Fails if not_affected on CRITICAL CVE without reachability proof (unless bypass reason applies).

6. Deterministic Replay

6.1 Input Pinning

To guarantee “same inputs → same verdict”, pin:

• SBOM digest(s)
• Vuln feed snapshot IDs
• VEX document digests
• Reachability graph IDs
• Policy file hash
• Lattice version
• Clock cutoff (evaluation timestamp)

6.2 Verdict Manifest

{
  "manifestId": "verd:tenant:asset:cve:1234567890",
  "tenant": "acme-corp",
  "assetDigest": "sha256:abc123...",
  "vulnerabilityId": "CVE-2025-12345",
  "inputs": {
    "sbomDigests": ["sha256:..."],
    "vulnFeedSnapshotIds": ["nvd:2025-12-22"],
    "vexDocumentDigests": ["sha256:..."],
    "reachabilityGraphIds": ["graph:..."],
    "clockCutoff": "2025-12-22T12:00:00Z"
  },
  "result": {
    "status": "not_affected",
    "confidence": 0.82,
    "explanations": [...]
  },
  "policyHash": "sha256:...",
  "latticeVersion": "1.2.0",
  "evaluatedAt": "2025-12-22T12:00:01Z",
  "manifestDigest": "sha256:..."
}

6.3 Signing

Verdict manifests are signed using DSSE with predicate type:

https://stella-ops.org/attestations/vex-verdict/1

6.4 Replay Verification

POST /api/v1/authority/verdicts/{manifestId}/replay

Response:
{
  "success": true,
  "originalManifest": {...},
  "replayedManifest": {...},
  "differences": [],
  "signatureValid": true
}

7. Configuration Reference

Full Configuration Example

# etc/trust-lattice.yaml
version: "1.0"

trustLattice:
  weights:
    provenance: 0.45
    coverage: 0.35
    replayability: 0.20

  freshness:
    halfLifeDays: 90
    floor: 0.35

  conflictPenalty: 0.25

  defaults:
    vendor:
      provenance: 0.90
      coverage: 0.70
      replayability: 0.60
    distro:
      provenance: 0.80
      coverage: 0.85
      replayability: 0.60
    internal:
      provenance: 0.85
      coverage: 0.95
      replayability: 0.90

gates:
  minimumConfidence:
    enabled: true
    thresholds:
      production: 0.75
      staging: 0.60
      development: 0.40

  unknownsBudget:
    enabled: true
    maxUnknownCount: 5
    maxCumulativeUncertainty: 2.0

  sourceQuota:
    enabled: true
    maxInfluencePercent: 60
    corroborationDelta: 0.10

  reachabilityRequirement:
    enabled: true
    severityThreshold: CRITICAL

8. API Reference

Endpoints

See docs/API_CLI_REFERENCE.md for complete API documentation.

9. Examples

Example 1: High-Confidence Verdict

Input:

• Red Hat VEX: not_affected with component_not_present
• Ubuntu VEX: not_affected with component_not_present

Calculation:

Red Hat: BaseTrust=0.78, M=0.80, F=0.95 → ClaimScore=0.59
Ubuntu:  BaseTrust=0.72, M=0.80, F=0.90 → ClaimScore=0.52

No conflict (both agree)
Winner: Red Hat (higher score)
Confidence: 0.59
Gates: All pass (> 0.40 threshold)

Example 2: Conflict Resolution

Input:

• Vendor VEX: not_affected
• Internal scan: affected

Calculation:

Vendor:   ClaimScore=0.65
Internal: ClaimScore=0.55

Conflict detected → penalty applied
Internal adjusted: 0.55 * 0.75 = 0.41

Winner: Vendor
Confidence: 0.65
Note: Conflict recorded in audit trail

10. Implementation Reference

10.1 Source Files

10.2 Configuration Files

10.3 Database Schema

• Calibration manifests: excititor.calibration_manifests / excititor.calibration_adjustments, created by the consolidated baseline src/Concelier/__Libraries/StellaOps.Excititor.Persistence/Migrations/001_v1_excititor_baseline.sql (lines 287 / 302). (Excititor was consolidated under src/Concelier/; there is no StellaOps.Excititor.Storage.Postgres project and no standalone 002_calibration_schema.sql.)
• Verdict storage: See Authority module for verdict manifest persistence

10.4 Test Coverage

Related Documentation

• Excititor Architecture
• Verdict Manifest Specification
• Policy Gates Configuration
• API Reference

Document Version: 1.0.0 Sprint: 7100.0003.0002 Created: 2025-12-22