40 lines
2.9 KiB
Markdown
40 lines
2.9 KiB
Markdown
# 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
|