up

docs/modules/vuln-explorer/architecture.md

@@ -75,3 +75,122 @@ CLI mirrors these endpoints (`stella findings list|view|update|export`). Console
   - `reports/` (generated PDFs/CSVs).
   - `signatures/` (DSSE envelopes).
 - Bundles produced deterministically; Export Center consumes them for mirror profiles.
+
+## 8) VEX-First Triage UX
+
+> Reference: Product advisory `28-Nov-2025 - Vulnerability Triage UX & VEX-First Decisioning.md`
+
+### 8.1 Evidence-First Finding Cards
+
+Each vulnerability finding is displayed as an evidence-first card showing:
+- CVE/vulnerability identifier with severity badge
+- Package name, version, ecosystem
+- Location (file path, container layer, function, call path)
+- Scanner and database date
+- Status badges: `New`, `VEX: Not affected`, `Policy: blocked`
+
+Primary actions per card:
+- **VEX: Set status** - Opens VEX decision modal
+- **Fix PR / View Fix** - When available from connected scanners (Snyk/GitLab)
+- **Attach Evidence** - Link PRs, tickets, docs, commits
+- **Copy audit reference** - findingId + attestation digest
+
+### 8.2 VEX Decision Model
+
+VEX decisions follow the `VexDecision` schema (`docs/schemas/vex-decision.schema.json`):
+
+**Status values:**
+- `NOT_AFFECTED` - Vulnerability does not apply to this artifact
+- `AFFECTED_MITIGATED` - Vulnerable but mitigations in place
+- `AFFECTED_UNMITIGATED` - Vulnerable without mitigations
+- `FIXED` - Vulnerability has been remediated
+
+**Justification types (CSAF/VEX aligned):**
+- `CODE_NOT_PRESENT`
+- `CODE_NOT_REACHABLE`
+- `VULNERABLE_CODE_NOT_IN_EXECUTE_PATH`
+- `CONFIGURATION_NOT_AFFECTED`
+- `OS_NOT_AFFECTED`
+- `RUNTIME_MITIGATION_PRESENT`
+- `COMPENSATING_CONTROLS`
+- `ACCEPTED_BUSINESS_RISK`
+- `OTHER`
+
+**Scope and validity:**
+- Decisions can be scoped to specific environments and projects
+- Validity windows with `notBefore` and `notAfter` timestamps
+- Expired decisions are surfaced with warnings
+
+### 8.3 Explainability Panel
+
+Right-side panel with tabs for each finding:
+
+**Overview tab:**
+- Title, severity, package/version
+- Scanner + DB date
+- Finding history timeline
+- Current VEX decision summary
+
+**Reachability tab:**
+- Call path visualization
+- Module dependency list
+- Runtime usage indicators (when available)
+
+**Policy tab:**
+- Policy evaluation result (PASS/WARN/FAIL)
+- Gate details with "this gate failed because..." explanations
+- Links to gate definitions
+
+**Attestations tab:**
+- Attestations mentioning this artifact/vulnerability/scan
+- Type, subject, predicate, signer, verified status
+- "Signed evidence" pill linking to attestation detail
+
+### 8.4 VEX Decision APIs
+
+New endpoints for VEX decisions:
+
+- `POST /v1/vex-decisions` - Create new VEX decision with optional attestation
+- `PATCH /v1/vex-decisions/{id}` - Update existing decision (creates superseding record)
+- `GET /v1/vex-decisions` - List decisions with filters
+- `GET /v1/vex-decisions/{id}` - Get decision detail
+
+Request/response follows `VexDecisionDto` per schema.
+
+### 8.5 Audit Bundle Export
+
+Immutable audit bundles follow the `AuditBundleIndex` schema (`docs/schemas/audit-bundle-index.schema.json`):
+
+**Bundle contents:**
+- Vulnerability reports (scanner outputs)
+- SBOM (CycloneDX/SPDX)
+- VEX decisions
+- Policy evaluations
+- Raw attestations (DSSE envelopes)
+- `audit-bundle-index.json` manifest with integrity hashes
+
+**APIs:**
+- `POST /v1/audit-bundles` - Create new bundle (async generation)
+- `GET /v1/audit-bundles/{bundleId}` - Download bundle (ZIP or OCI)
+- `GET /v1/audit-bundles` - List previously created bundles
+
+### 8.6 Industry Pattern Alignment
+
+The triage UX aligns with industry patterns from:
+
+| Tool | Pattern Adopted |
+|------|-----------------|
+| **Snyk** | PR checks, Fix PRs, ignore with reasons |
+| **GitLab SCA** | Vulnerability Report, status workflow, activity log |
+| **Harbor/Trivy** | Artifact-centric navigation, attestation accessories |
+| **Anchore** | Policy gates with trigger explanations, allowlists |
+
+## 9) Schemas
+
+The following JSON schemas define the data contracts for VEX and audit functionality:
+
+- `docs/schemas/vex-decision.schema.json` - VEX decision form and persistence
+- `docs/schemas/attestation-vuln-scan.schema.json` - Vulnerability scan attestation predicate
+- `docs/schemas/audit-bundle-index.schema.json` - Audit bundle manifest
+
+These schemas are referenced by both backend DTOs and frontend TypeScript interfaces.