VEX Proof Object Schema Reference

Schema: stellaops.vex-proof.v1  ·  Version: 1.0  ·  Last updated: 2026-05-30

This is the field-level reference for the StellaOps VEX Proof Object — the cryptographically verifiable record of how a VEX consensus verdict was reached. It is written for integrators consuming the VexLens consensus API, policy authors wiring up the proof gate, and reviewers auditing a release decision.

Overview

A VEX Proof Object provides a cryptographically verifiable audit trail of how a VEX consensus verdict is computed. Every VEX resolution in StellaOps produces a proof object that documents the inputs considered, the resolution process, and the decision rationale — so a verdict can be independently re-derived and trusted offline.

Implementation reference: the canonical record types are defined in src/VexLens/StellaOps.VexLens/Proof/VexProof.cs, built by VexProofBuilder (VexProofBuilder.cs), and serialized/digested by VexProofSerializer (VexProofSerializer.cs). The proof is surfaced over HTTP by the POST /api/v1/vexlens/consensus:withProof endpoint (see API Access). There is no separate JSON Schema (*.schema.json) artifact shipped for the proof object; the structure below is derived directly from the serialized C# record graph (System.Text.Json, camelCase property names).

Object Shape

The proof object is the JSON serialization of the VexProof record. Property names use camelCase. The schema constant is exposed as VexProof.SchemaVersion = "stellaops.vex-proof.v1".

Notes:

• digest is a plain hex string, not a nested {algorithm, value} object.
• Nullable fields (propagation, conditions, digest, verdict.justification) are omitted from the output when null (JsonIgnoreCondition.WhenWritingNull).

Object Definitions

Verdict

The final consensus result (VexProofVerdict).

{
  "vulnerabilityId": "CVE-2023-12345",
  "productKey": "pkg:npm/lodash@4.17.21",
  "status": "not_affected",
  "justification": "vulnerable_code_not_in_execute_path",
  "confidence": 0.78
}

VEX Status values

VexStatus (src/VexLens/StellaOps.VexLens/Models/NormalizedVexModels.cs) serializes to the OpenVEX-aligned snake_case values:

• not_affected
• affected
• fixed
• under_investigation
• unknown

Justification values

VexJustification serializes to the OpenVEX justification codes:

• component_not_present
• vulnerable_code_not_present
• vulnerable_code_not_in_execute_path
• vulnerable_code_cannot_be_controlled_by_adversary
• inline_mitigations_already_exist

Inputs

All VEX statements considered, plus the evaluation context (VexProofInputs).

Note: qualified/disqualified counts are not on inputs; they live on resolution (qualifiedStatements, disqualifiedStatements, disqualificationReasons). Each statement is tagged individually with qualified and an optional disqualificationReason.

Statement Object

A single VEX statement with its computed trust weight (VexProofStatement).

Context Object

Evaluation context for the proof (VexProofContext).

Issuer Object

Issuer information for a statement (VexProofIssuer). The category and trustTier enums declare uppercase JSON member names via [JsonPropertyName] on IssuerCategory / TrustTier.

Weight Object

Trust weight breakdown for a statement (VexProofWeight).

Weight factors (all required, [0.0, 1.0]):

• issuer: Issuer trust factor
• signature: Signature verification factor
• freshness: Freshness/recency factor
• format: Format quality factor
• specificity: Specificity factor (how targeted the statement is)

Resolution

Resolution computation details (VexProofResolution). This object replaces the older “merge trace” naming.

Consensus Modes

ConsensusMode serializes to snake_case:

• highest_weight: Use the statement with highest trust weight
• weighted_vote: Weighted voting among all statements (default for the API service)
• lattice: Lattice-based consensus (most conservative status wins ties; default in VexProofBuilder)
• authoritative_first: Prefer vendor/authoritative sources over others

Lattice Computation

Lattice-based computation details (VexProofLatticeComputation).

Merge Step

A single merge step in lattice computation (VexProofMergeStep).

Conflict Analysis

Conflict analysis for the resolution (VexProofConflictAnalysis).

Conflict

A single conflict between statements (VexProofConflict).

Propagation

Dependency-graph propagation analysis (VexProofPropagation). The whole object is omitted (null) when no propagation rules or graph paths were evaluated.

Propagation Rule

Each evaluated rule (VexProofPropagationRule) records:

The built-in rule IDs emitted by PropagationRuleEngine (src/VexLens/StellaOps.VexLens/Propagation/PropagationRuleEngine.cs) are hyphen-delimited:

• direct-dependency-affected: Affected status propagates to direct dependents
• transitive-dependency-affected: Affected status propagates through the transitive dependency tree
• dependency-fixed: Fixed status handling for dependencies
• dependency-not-affected: NotAffected propagation for dependencies

Graph Path

A path through the dependency graph (VexProofGraphPath).

Conditions

Condition evaluation results (VexProofConditions). The whole object is omitted (null) when no conditions were evaluated.

Note: condition coverage is not on this object; it is carried in confidence.breakdown.conditionCoverage (the fraction of conditions that resolved to a definite true/false).

Condition Result

A single condition evaluation (VexProofConditionResult).

Condition Types

ConditionType (src/VexLens/StellaOps.VexLens/Conditions/IConditionEvaluator.cs) — the supported condition handlers:

• Platform: OS/architecture (e.g., linux/amd64); supports * wildcards
• Distro: Distribution (e.g., rhel:9); supports * wildcards
• Feature: Feature flag condition
• BuildFlag: Compile-time flag
• Environment: Environment variable
• Custom: Custom expression (parsed for platform/distro/feature/env.KEY/buildFlag.KEY syntax)

Confidence

Confidence score breakdown (VexProofConfidence).

Confidence Tiers

ConfidenceTier serializes to snake_case and has five levels (classified by VexProofBuilder):

• very_high (score >= 0.9)
• high (score >= 0.75)
• medium (score >= 0.5)
• low (score >= 0.25)
• very_low (score < 0.25)

The VexProofGate policy gate only recognizes the three tiers low / medium / high for its MinimumConfidenceTier comparison (see Policy Integration); very_high and very_low are emitted by the proof but are not distinct comparison points in the gate’s tier ordering.

Confidence breakdown

Fields of breakdown (all required, in score order). The score is computed as weightSpread + conflictPenalty + freshnessBonus + signatureBonus, then multiplied by conditionCoverage, then clamped to [0.0, 1.0].

• weightSpread: Base weight from statement weights
• conflictPenalty: Penalty from conflicts (negative or zero)
• freshnessBonus: Bonus from recent statements
• signatureBonus: Bonus from verified signatures
• conditionCoverage: Coverage of conditions evaluated [0.0, 1.0]

Proof ID

proofId is generated by VexProofBuilder.GenerateProofId as:

proof-{computedAt:yyyy-MM-ddTHH:mm:ssZ}-{8 lowercase hex chars}

The 8-character suffix derives from a GUID provider (IGuidProvider). Because it is random, the proofId is not part of the digest computation in determinism tests (callers normalize it before digesting; see VexProofDeterminismTests).

Digest Computation

The proof digest is computed over the canonical (RFC 8785, sorted-key) JSON serialization, via VexProofSerializer.ComputeDigest:

1. Set digest to null and serialize the proof to canonical JSON using StellaOps.Canonical.Json.CanonJson (sorted keys, no whitespace, minimal escaping).
2. Compute the SHA-256 hash of the UTF-8 canonical JSON bytes.
3. Encode as lowercase hexadecimal (Convert.ToHexStringLower) — a 64-character string.

The result is stored in the top-level digest string field. VexProofSerializer.VerifyDigest recomputes the digest and compares case-insensitively. There is no algorithm/value wrapper object.

{
  "digest": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Example Proof Object

The example below reflects the actual serialized shape (camelCase, digest as a hex string, resolution object, confidence.breakdown, per-statement qualified flag, and an inputs.context block).

{
  "schema": "stellaops.vex-proof.v1",
  "proofId": "proof-2026-01-02T10:30:00Z-1a2b3c4d",
  "computedAt": "2026-01-02T10:30:00Z",
  "verdict": {
    "vulnerabilityId": "CVE-2023-12345",
    "productKey": "pkg:npm/lodash@4.17.21",
    "status": "not_affected",
    "justification": "vulnerable_code_not_in_execute_path",
    "confidence": 0.78
  },
  "inputs": {
    "statements": [
      {
        "id": "stmt-001",
        "source": "openvex",
        "issuer": {
          "id": "lodash-maintainers",
          "category": "VENDOR",
          "trustTier": "AUTHORITATIVE"
        },
        "status": "not_affected",
        "justification": "vulnerable_code_not_in_execute_path",
        "weight": {
          "composite": 0.85,
          "factors": {
            "issuer": 0.90,
            "signature": 1.00,
            "freshness": 0.95,
            "format": 1.00,
            "specificity": 0.70
          }
        },
        "timestamp": "2023-06-15T10:30:00Z",
        "signatureVerified": true,
        "qualified": true
      }
    ],
    "context": {
      "platform": "linux/amd64",
      "features": ["esm"],
      "buildFlags": [],
      "evaluationTime": "2026-01-02T10:30:00Z"
    }
  },
  "resolution": {
    "mode": "lattice",
    "qualifiedStatements": 1,
    "disqualifiedStatements": 0,
    "disqualificationReasons": [],
    "latticeComputation": {
      "ordering": ["affected", "unknown", "under_investigation", "fixed", "not_affected"],
      "mergeSteps": [
        {
          "step": 1,
          "statementId": "stmt-001",
          "inputPosition": "not_affected",
          "weight": 0.85,
          "action": "initialize",
          "conflict": false,
          "resultPosition": "not_affected"
        }
      ],
      "finalPosition": "not_affected"
    },
    "conflictAnalysis": {
      "hasConflicts": false,
      "conflicts": [],
      "conflictPenalty": 0.00
    }
  },
  "confidence": {
    "score": 0.78,
    "tier": "high",
    "breakdown": {
      "weightSpread": 0.85,
      "conflictPenalty": 0.00,
      "freshnessBonus": 0.00,
      "signatureBonus": 0.00,
      "conditionCoverage": 1.00
    },
    "improvements": []
  },
  "digest": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

API Access

The proof object is produced by the VexLens service. The relevant endpoint is mapped in src/VexLens/StellaOps.VexLens.WebService/Extensions/VexLensEndpointExtensions.cs:

Scope note: the vexlens.read / vexlens.write authorization policies are registered locally by the VexLens WebService (Program.cs, auth.AddStellaOpsScopePolicy("vexlens.read", "vexlens.read")). As of this writing they are not declared in the canonical scope catalog src/Authority/.../StellaOps.Auth.Abstractions/StellaOpsScopes.cs (which declares VEX-ingestion scopes vex:read, vex:ingest, vex.admin and VexHub scopes vexhub:read, vexhub:admin). Treat vexlens.read/vexlens.write as service-scoped names pending catalog reconciliation.

Request: ComputeConsensusWithProofRequest

Response: ComputeConsensusWithProofResponse.proof (ProofResponse)

The HTTP response embeds a flattened proof summary plus the full serialized proof. The summary (ProofResponse) fields are:

Note: the flattened summary fields (e.g. finalStatus, mergeAlgorithm) use .ToString() on the enums (PascalCase member names such as NotAffected, Lattice), whereas rawProofJson uses the JSON serializer’s snake_case/uppercase member names described in the field tables above.

Policy Integration

VEX proofs integrate with the policy gate system via VexProofGate (src/Policy/__Libraries/StellaOps.Policy/Gates/VexProofGate.cs), configured through VexProofGateOptions:

The gate reads proof attributes from PolicyGateContext.Metadata keys: vex_proof_id, vex_proof_confidence_tier, vex_proof_confidence_score, vex_proof_conflict_count, vex_proof_statement_count, vex_proof_all_signed, vex_proof_computed_at, vex_proof_consensus_outcome, and (anchor-aware) vex_proof_anchored, vex_proof_envelope_digest, vex_proof_rekor_verified, vex_proof_rekor_log_index. A preset VexProofGateOptions.StrictAnchorAware enables strict production settings (high tier, signed statements, anchoring + Rekor, 0 conflicts, 72-hour max age).

Persistence

VexLens persists consensus projections (not the proof object itself) under the vexlens PostgreSQL schema. Migrations are embedded in StellaOps.VexLens.Persistence (Migrations/001_consensus_projections.sql, Migrations/002_noise_gating_state.sql) and applied on startup. The full proof object is returned inline by the consensus:withProof endpoint as rawProofJson; it is not stored as a standalone row in the projection tables.

Related Documentation

• VEX Consensus Guide — how statements are gathered, weighted, and resolved
• Trust weight breakdown — the per-statement weight factors that feed consensus (in this document)
• Policy Integration — how proofs are consumed by the VexProofGate (in this document)
• OpenVEX Specification
• CycloneDX VEX