stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
9ca2de05dff9c7db11eb49df6d4e47bbfe7a99f6
git.stella-ops.org/docs/features/checked/policy/belnap-k4-trust-lattice-engine.md
master 9ca2de05df more features checks. setup improvements
2026-02-13 02:04:55 +02:00

5.1 KiB
Raw Blame History

Belnap K4 Trust Lattice Engine (VEX Resolution, Trust Algebra)

Module

Policy

Status

VERIFIED

Description

Full K4 lattice implementation with 4-valued logic (unknown/true/false/conflict), trust labels, lattice store, claim score merging, conflict penalization, and disposition selection. VEX normalization for OpenVEX and CSAF formats. Deterministic, commutative, idempotent merge operations. Comprehensive tests including property-based tests.

Implementation Details

  • K4Lattice: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/K4Lattice.cs -- Belnap four-valued logic implementation
    • K4Value enum: Unknown (bottom), True, False, Conflict (top)
    • Knowledge ordering: Unknown < True|False < Conflict; True and False are incomparable
    • Join(a, b) -- knowledge join (union of support): T join F = Conflict; short-circuits on Conflict
    • JoinAll(values) -- order-independent aggregation over sequence; short-circuits on Conflict
    • Meet(a, b) -- knowledge meet (intersection): T meet F = Unknown; Conflict meet X = X
    • LessOrEqual(a, b) -- knowledge ordering predicate
    • Negate(v) -- swaps True/False; Unknown and Conflict are self-negating
    • FromSupport(hasTrueSupport, hasFalseSupport) -- constructs K4 value from support flags
    • Helper predicates: HasTrueSupport, HasFalseSupport, IsDefinite, IsIndeterminate
  • TrustLatticeEngine: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/TrustLatticeEngine.cs -- orchestrates complete trust evaluation pipeline
    • Pipeline: VEX normalization -> claim ingestion -> K4 lattice evaluation -> disposition selection -> proof bundle generation
    • IngestVex(document, format, principal, trustLabel?) -- ingests VEX document via registered normalizers
    • IngestClaim(claim) / IngestClaims(claims) -- direct claim ingestion into LatticeStore
    • GetDisposition(subject) -- evaluates subject and returns DispositionResult
    • MergeClaims(scoredClaims, policy?) -- merges scored VEX claims using ClaimScore-based algorithm
    • Evaluate(options?) -- evaluates all subjects with optional proof bundle generation and subject filtering
    • Fluent ClaimBuilder with Assert(atom, value), Present(), Applies(), Reachable(), Mitigated(), Fixed(), Misattributed()
  • ClaimScoreMerger: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ClaimScoreMerger.cs -- lattice-based merge with conflict penalization
    • Merge(scoredClaims, policy) -- orders by adjusted score, specificity, original score; selects winner
    • ConflictPenalizer applies configurable penalty (default 0.25) to conflicting claims
    • MergePolicy options: ConflictPenalty, PreferSpecificity, RequireReplayProofOnConflict
    • Returns MergeResult with: winning claim, all scored claims, conflict records, confidence, RequiresReplayProof flag
  • LatticeStore: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/LatticeStore.cs -- subject state storage and claim aggregation
  • DispositionSelector: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/DispositionSelector.cs -- applies policy rules to select final disposition
  • ConflictPenalizer: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ConflictPenalizer.cs -- applies configurable penalties to conflicting claims
  • SecurityAtom: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/SecurityAtom.cs -- atomic propositions (Present, Applies, Reachable, Mitigated, Fixed, Misattributed)
  • VEX Normalizers: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/VexNormalizers.cs, OpenVexNormalizer.cs, CsafVexNormalizer.cs -- normalize CycloneDX, OpenVEX, CSAF formats to claims
  • TrustLabel: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/TrustLabel.cs -- trust level annotations for claims
  • PolicyBundle / ProofBundle: src/Policy/__Libraries/StellaOps.Policy/TrustLattice/PolicyBundle.cs, ProofBundle.cs -- policy configuration and proof bundles with decision traces

E2E Test Plan

  • Create TrustLatticeEngine with default policy; ingest two claims with True and False assertions for same subject; verify K4 value is Conflict
  • Ingest claims from OpenVEX, CycloneDX, and CSAF documents; verify all three normalizers produce valid claims in the LatticeStore
  • Verify Join commutativity: Join(a, b) == Join(b, a) for all K4Value combinations
  • Verify Join idempotency: Join(a, a) == a for all K4Value values
  • Verify Meet/Join absorption: Join(a, Meet(a, b)) == a for all K4Value combinations
  • Verify conflict penalization: merge two claims with different VEX statuses; winning claim has lower adjusted score than original when conflict detected
  • Verify RequiresReplayProof is set when RequireReplayProofOnConflict=true and conflicts exist
  • Evaluate all subjects with GenerateProofBundle=true and verify proof bundle contains atom tables, claims, and decisions
  • Verify subject filter: evaluate with SubjectFilter containing one digest; only that subject's disposition is returned
  • Verify ClaimBuilder fluent API: create claim with Present().Reachable().Mitigated() and verify three assertions are ingested