# VulnExplorer Triage API

## Module
VulnExplorer

## Status
VERIFIED

## Description
Backend API for the vulnerability triage workspace providing VEX decision endpoints, audit bundle creation, SPDX 3.0.1 data model integration, and triage workflow state management with evidence-linked decisions.

## Implementation Details
- **VEX Decision Store**: `src/VulnExplorer/StellaOps.VulnExplorer.Api/Data/VexDecisionStore.cs` -- in-memory store for VEX triage decisions; manages decision state (not_affected, affected, fixed, under_investigation) with evidence references and analyst justifications.
- **VEX Decision Models**: `src/VulnExplorer/StellaOps.VulnExplorer.Api/Models/VexDecisionModels.cs` -- data models for VEX decisions including status, justification, impact statement, action statement, and linked evidence artifacts.
- **Vulnerability Models**: `src/VulnExplorer/StellaOps.VulnExplorer.Api/Models/VulnModels.cs` -- core vulnerability data models (CVE ID, CVSS scores, affected components, fix availability) used by the triage workspace.
- **Fix Verification Models**: `src/VulnExplorer/StellaOps.VulnExplorer.Api/Models/FixVerificationModels.cs` -- models for fix verification status tracking (fix applied, verified by scanner, verified by binary diff, pending verification).
- **Attestation Models**: `src/VulnExplorer/StellaOps.VulnExplorer.Api/Models/AttestationModels.cs` -- models for creating audit bundles that attest to triage decisions, linking VEX statements with the evidence that supports them.
- **IVexOverrideAttestorClient**: `src/VulnExplorer/StellaOps.VulnExplorer.Api/Data/IVexOverrideAttestorClient.cs` -- client interface for submitting VEX override decisions to the Attestor service for cryptographic signing and transparency log recording.
- **Evidence Subgraph Contracts**: `src/VulnExplorer/StellaOps.VulnExplorer.WebService/Contracts/EvidenceSubgraphContracts.cs` -- API contracts for querying evidence subgraphs associated with a vulnerability, including reachability analysis, binary diff results, and proof chain references.
- **Sample Data**: `src/VulnExplorer/StellaOps.VulnExplorer.Api/Data/SampleData.cs` -- seed data for development and demo scenarios with pre-populated vulnerabilities, components, and triage decisions.
- **API Program**: `src/VulnExplorer/StellaOps.VulnExplorer.Api/Program.cs` -- ASP.NET Minimal API host exposing triage endpoints for VEX decisions, evidence queries, and audit bundle creation.

## E2E Test Plan
- [ ] Create a VEX decision via the triage API (POST) with status "not_affected" and a justification, then retrieve it (GET) and verify all fields match
- [ ] Create a VEX decision, submit it to the Attestor via `IVexOverrideAttestorClient`, and verify the returned attestation contains the decision digest and transparency log entry
- [ ] Query the evidence subgraph for a specific CVE and verify the response includes linked reachability analysis, binary diff results, and proof chain references
- [ ] Create a fix verification record, update it through the verification workflow (pending -> verified_by_scanner -> verified_by_diff), and verify each state transition is recorded
- [ ] Create an audit bundle for a triage session with multiple VEX decisions and verify the bundle contains all decisions with their linked evidence artifacts
- [ ] Attempt to create a VEX decision with an invalid status value and verify the API returns a 400 error with a descriptive validation message


## Verification
- Verified via QA FLOW on 2026-02-11 using run-001 (failure evidence) and run-002 (pass after fixes).
- Tier 0 artifact: docs/qa/feature-checks/runs/vulnexplorer/vulnexplorer-triage-api/run-002/tier0-source-check.json.
- Tier 1 artifact: docs/qa/feature-checks/runs/vulnexplorer/vulnexplorer-triage-api/run-002/tier1-build-check.json.
- Tier 2 artifact: docs/qa/feature-checks/runs/vulnexplorer/vulnexplorer-triage-api/run-002/tier2-api-check.json.