stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/features/checked/attestor/vex-findings-api-with-proof-artifacts.md
master e9aeadc040 save checkpoint
2026-02-14 09:11:48 +02:00

2.8 KiB
Raw Permalink Blame History

VEX Findings API with Proof Artifacts

Module

Attestor

Status

VERIFIED

Description

VEX verdict models, VEX delta predicates, and a VexProofSpineService exist in the backend, but the full API contract (GET /vex/findings/:id with proof artifacts) is not visible as a standalone endpoint.

What's Implemented

  • VEX Attestation Predicate: src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/VexAttestationPredicate.cs -- VEX verdict predicate with proof references.
  • VEX Verdict Summary: Predicates/VexVerdictSummary.cs -- VEX verdict summary model.
  • VEX Proof Integrator: Generators/VexProofIntegrator.cs (with .Helpers, .Metadata) -- proof integration for VEX verdicts.
  • VEX Verdict Proof Payload: Generators/VexVerdictProofPayload.cs -- proof-carrying VEX verdict payload.
  • VEX Verdict Statement: Statements/VexVerdictStatement.cs -- in-toto statement for VEX verdicts.
  • VEX Verdict ID: Identifiers/VexVerdictId.cs -- content-addressed VEX verdict identifier.
  • Proof Spine System: Assembly/ProofSpineRequest.cs, ProofSpineResult.cs, ProofSpineSubject.cs -- proof spine for evidence assembly.
  • Verdict Controller: StellaOps.Attestor.WebService/Controllers/VerdictController.cs -- existing verdict API.
  • Proofs Controller: WebService/Controllers/ProofsController.cs -- existing proofs API.

What's Missing

  • GET /vex/findings/:id endpoint: No REST endpoint returning VEX findings with attached proof artifacts for a specific finding ID.
  • Proof artifact packaging: No service that packages proof artifacts (DSSE signatures, Rekor receipts, Merkle proofs) alongside VEX findings in API responses.
  • Finding-level proof resolution: No resolver that collects all proof artifacts for a specific finding (CVE + component combination).
  • Proof artifact download: No endpoint for downloading individual proof artifacts as files.
  • Finding search with proof status filter: No search endpoint filtering findings by proof availability (e.g., "show only findings with proof").

Implementation Plan

  • Add GET /vex/findings/:id endpoint returning finding details with proof artifacts
  • Create a proof artifact resolver collecting all proofs for a finding
  • Add proof artifact packaging in API responses (inline or as download links)
  • Add GET /vex/findings/:id/proofs endpoint for downloading proof artifacts
  • Implement finding search with proof status filtering
  • Add tests for finding retrieval, proof packaging, and search filtering

Related Documentation

  • Source: See feature catalog

Verification

Check Result
Tier 0 - Source Verification PASS
Tier 1 - Build + Code Review PASS
Tier 2 - Behavioral Verification PASS
Verified Date 2026-02-13
Run ID run-001