git.stella-ops.org/docs/api/vuln.md

Vulnerability API (placeholder)

Status: Draft (2025-11-26) — awaiting Vuln Explorer v1 surface. This doc reserves the path and headers to align with upcoming releases.

Base URL

<gateway>/api/vuln (subject to final routing via API gateway).

Common headers

• X-Stella-Tenant (required)
• Authorization: Bearer <token>
• X-Stella-Scopes: expect vuln:read (TBD) and/or graph:read when graph-backed queries are invoked.
• Content-Type: application/json

Planned endpoints (subject to change)

• POST /vuln/search — filter vulnerabilities by component (purl/digest), advisory id, status, exploitability (OpenVEX).
• POST /vuln/impact — compute impacted assets using Graph overlays; may proxy to Graph API internally.
• GET /vuln/{id} — details with references, VEX status, nearest safe version.
• GET /vuln/{id}/evidence — raw evidence (SBOM snapshot refs, observations).
• GET /vuln/kev — Known Exploited Vulnerabilities view (cached).

Error envelope

Follows Graph/Platform standard:

{ "error": "VULN_VALIDATION_FAILED", "message": "details", "requestId": "optional" }

Notes

• This placeholder will be updated once Vuln Explorer API is finalized. Keep gateway clients tolerant to minor shape changes until status flips to READY.
• For current graph-backed queries, use /graph/search or /graph/query (see docs/api/graph.md).