stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
44248482836423b62d07e1e00d78de38a7e3bcad
git.stella-ops.org/docs/features/unchecked/vulnexplorer/vulnexplorer-triage-api.md

3.4 KiB
Raw Blame History

VulnExplorer Triage API

Module

VulnExplorer

Status

IMPLEMENTED

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