stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
1bf6bbf3955ecbd8d20f5eeb767da5c7f8324b57
git.stella-ops.org/docs/features/unchecked/attestor/native-vex-ingestion-and-decisioning.md

3.1 KiB
Raw Blame History

Native VEX Ingestion and Decisioning

Module

Attestor

Status

IMPLEMENTED

Description

Full VEX pipeline with ingestion (Excititor), hub for VEX document management, lens for analysis, override system with DSSE-signed decisions, merge trace for conflict resolution, and multiple UI views (studio, hub, timeline).

Implementation Details

  • VEX Override Predicate System: src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/VexOverride/ -- complete VEX override system:
    • VexOverridePredicate.cs -- VEX override predicate model.
    • VexOverrideDecision.cs -- override decision (status, justification, impact statement).
    • VexOverridePredicateBuilder.cs (with .Build, .Serialize, .WithMethods) -- fluent builder for constructing VEX overrides.
    • VexOverridePredicateParser.cs (with .ParsePredicate, .DecisionValidation, .FieldValidation, .ExtractMetadata, .Helpers, .Validation) -- parser with comprehensive validation.
    • EvidenceReference.cs -- links override decisions to supporting evidence.
    • ToolInfo.cs -- metadata about the tool that produced the VEX data.
  • VEX Proof Integrator: __Libraries/StellaOps.Attestor.ProofChain/Generators/VexProofIntegrator.cs (with .Helpers, .Metadata) -- integrates VEX decisions into proof chain with supporting evidence.
  • VEX Verdict Proof Payload: Generators/VexVerdictProofPayload.cs -- combined VEX verdict + proof payload.
  • VEX Verdict Statement: __Libraries/StellaOps.Attestor.ProofChain/Statements/VexVerdictStatement.cs -- in-toto statement wrapping VEX verdicts.
  • VEX Predicates: Predicates/VexDeltaChange.cs, VexDeltaStatement.cs, VexDeltaSummary.cs, VexDocumentReference.cs, VexMergeTrace.cs, VexStatusCounts.cs, VexVerdictSummary.cs -- VEX delta tracking, merge traces, and summaries.
  • VEX Verdict ID: Identifiers/VexVerdictId.cs -- content-addressed ID for VEX verdicts.
  • DSSE Signing: Signing/ProofChainSigner.cs -- signs VEX decisions into DSSE envelopes.
  • Tests: __Tests/StellaOps.Attestor.StandardPredicates.Tests/VexOverrideTests.cs, __Tests/StellaOps.Attestor.ProofChain.Tests/VexProofIntegratorTests.cs

E2E Test Plan

  • Build a VEX override via VexOverridePredicateBuilder with status "not_affected", justification, and evidence references; verify the predicate structure
  • Parse a VEX override JSON via VexOverridePredicateParser and verify all fields (decision, evidence, tool info) are extracted
  • Validate a VEX override decision via .DecisionValidation and verify it rejects invalid statuses
  • Integrate a VEX verdict with proof chain evidence via VexProofIntegrator and verify the VexVerdictProofPayload combines both
  • Create a VexVerdictStatement and sign it into a DSSE envelope; verify the envelope is valid
  • Build a VexMergeTrace from two conflicting VEX documents and verify conflict resolution is recorded
  • Verify VexStatusCounts correctly aggregates counts by VEX status (affected, not_affected, under_investigation, fixed)
  • Round-trip: build a VEX override via builder, serialize, parse back, and verify semantic equivalence