Files
git.stella-ops.org/docs/features/unchecked/policy/vex-format-normalization.md

2.4 KiB

VEX Format Normalization (CycloneDX, OpenVEX, CSAF)

Module

Policy

Status

IMPLEMENTED

Description

Normalizers for CSAF and OpenVEX formats to convert heterogeneous VEX statements into the unified trust lattice representation.

Implementation Details

  • TrustLatticeEngine: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/TrustLatticeEngine.cs
    • Three VEX format normalizers integrated into evaluation pipeline:
      • CycloneDX normalizer: converts CycloneDX VEX analysis states to K4 claims
      • OpenVEX normalizer: converts OpenVEX status to K4 claims
      • CSAF normalizer: converts CSAF product status to K4 claims
    • All normalizers produce unified claim objects for K4 lattice evaluation
    • Format-specific metadata preserved in claim provenance
  • K4Lattice: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/K4Lattice.cs
    • Unified representation: Unknown=0, True=1, False=2, Conflict=3
    • FromSupport() maps normalized evidence to K4 values
  • ClaimBuilder: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/TrustLatticeEngine.cs
    • Fluent API for building claims from any format:
      • Assert(cve).Present(component).Mitigated() -> K4 True
      • Assert(cve).Present(component).Applies() -> K4 False (affected)
      • Assert(cve).Present(component).Fixed() -> K4 True (fixed version)
      • Assert(cve).Present(component).Misattributed() -> K4 True (not applicable)
  • Trust lattice directory: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ (15 files total)

E2E Test Plan

  • Normalize CycloneDX VEX with status "not_affected" and justification "code_not_reachable"; verify K4 True claim with correct provenance
  • Normalize OpenVEX with status "affected"; verify K4 False claim
  • Normalize CSAF with status "known_affected" and remediation "vendor_fix"; verify K4 claim reflects affected + fix available
  • Normalize CycloneDX VEX with status "fixed"; verify K4 True claim (vulnerability fixed)
  • Normalize all 3 formats for same CVE; merge via ClaimScoreMerger; verify deterministic result
  • Normalize VEX with invalid format; verify error handling (parse failure does not crash pipeline)
  • Verify format-specific metadata preserved: CycloneDX justification, OpenVEX statement, CSAF product_status
  • Normalize VEX from unknown format; verify treated as Unknown K4 value
  • Verify all normalizers produce claims compatible with K4Lattice.Join() and Meet()