stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
cf5b72974f923126944f4dcd47e85864ebb31a3b
git.stella-ops.org/docs/features/unchecked/cli/vex-generation-with-evidence-links.md

2.9 KiB
Raw Blame History

VEX Generation with Evidence Links (--link-evidence CLI Flag)

Module

Cli

Status

IMPLEMENTED

Description

Extension to stella vex gen command with --link-evidence flag that includes binary-diff evidence links in VEX output, showing evidence type, confidence score, and URI in both table and JSON formats. Generates OpenVEX documents from facet drift analysis with deterministic IDs.

Implementation Details

  • Command Group: src/Cli/StellaOps.Cli/Commands/VexGenCommandGroup.cs -- VexGenCommandGroup (internal static class)
    • Sprint: SPRINT_20260105_002_004_CLI (CLI-011 through CLI-015) and SPRINT_20260113_003_002_CLI_vex_evidence_integration
    • Uses IFacetDriftDetector, IFacetSealStore, IVexEvidenceLinker from DI
    • Generates deterministic IDs via SHA-256 of concatenated content
  • Evidence Integration: IVexEvidenceLinker.GetLinksAsync() fetches evidence links; AttachEvidenceLinksAsync() enriches VEX statements with evidence
  • Models (defined in same file):
    • OpenVexDocument (@context, @id, author, timestamp, version, statements)
    • OpenVexStatement (@id, status, timestamp, products, justification, action_statement, evidence)
    • OpenVexEvidence (type, uri, confidence, predicateType, envelopeDigest, validatedSignature, rekorIndex, signer)
    • EvidenceSummary (StatementId, Type, Confidence, EvidenceUri)
  • Commands:
    • stella vex gen --from-drift --image <ref> [--baseline <sealId>] [--output <path>] [--format openvex|csaf] [--status under_investigation|not_affected|affected] [--link-evidence] [--evidence-threshold 0.8] [--show-evidence-uri] -- generate VEX from facet drift with evidence linking
  • Output: OpenVEX JSON document to stdout or file; evidence summary table in console with confidence scores
  • Exit codes: 0 = success, 1 = error or missing --from-drift

E2E Test Plan

  • Run stella vex gen --from-drift --image registry/app@sha256:abc and verify OpenVEX JSON output
  • Run with --output vex.json and verify file written with correct OpenVEX schema (@context, @id, author, timestamp, statements)
  • Run with --link-evidence and verify evidence fields in statements (type, uri, confidence, validatedSignature)
  • Run with --evidence-threshold 0.5 and verify lower threshold includes more evidence links
  • Run with --evidence-threshold 1.0 and verify high threshold excludes low-confidence evidence
  • Run with --show-evidence-uri and verify full URIs in console evidence summary
  • Run with --format csaf and verify CSAF-formatted output
  • Run with --status not_affected and verify status field in generated statements
  • Run with --baseline <sealId> and verify specific baseline used for drift comparison
  • Run without --from-drift and verify error: "--from-drift is required"
  • Verify deterministic: running same command twice produces identical document IDs