VEX Evidence Gateway Contract (draft v0.1)

This contract describes the forward Web V gateway surface for reading VEX (Vulnerability Exploitability eXchange) statements and their supporting evidence with tenant scoping, deterministic ordering, and export helpers for offline bundles.

Audience: API client integrators and SDK/UI authors consuming VEX evidence through the gateway.

Status: design draft — not yet implemented as gateway routes. The /vex/statements* paths below are a forward Web V proxy contract. Today VEX statement/evidence/export reads are served by Excititor (StellaOps.Excititor.WebService, routed under the service’s own prefix) and by the Authority console (GET /console/vex/statements). All Excititor VEX routes — including export/mirror handlers — are guarded by the vex:read scope (ExcititorPolicies.VexRead); there is no vex:export scope in the canonical catalog (StellaOps.Auth.Abstractions/StellaOpsScopes.cs). VEX ingestion uses vex:ingest and provider/review administration uses vex.admin.

Security / headers

• Authorization: Bearer <token> (or DPoP where configured)
• X-StellaOps-TenantId: <tenantId> (required; see Gateway Tenant Auth & ABAC Contract)
• X-StellaOps-Project: <projectId> (optional; legacy alias X-Stella-Project is accepted only when the gateway is started with EnableLegacyHeaders=true)
• X-StellaOps-TraceId: <traceId> (optional; clients SHOULD send one)
• Scopes:
  • vex:read for list/detail/evidence and export handlers (Excititor guards all VEX routes, including export/mirror, with vex:read)
  • There is no separate vex:export scope; vex:ingest covers ingestion and vex.admin covers provider/review administration

Endpoints

• GET /vex/statements — list statements (tenant-scoped).
  • Query params: vulnId, status, search, limit, continuationToken
• GET /vex/statements/{statementId} — statement detail.
• GET /vex/statements/{statementId}/evidence — evidence links (signed URLs, optional DSSE).
• GET /vex/statements/{statementId}/export?format=json|ndjson|spdx|cyclonedx — export helper returning a signed URL and checksums.

Error codes

Gateway maps upstream/validation errors to stable codes for SDK/UI:

• ERR_AGG_BAD_REQUEST (400)
• ERR_AGG_UNAUTHORIZED (401/403)
• ERR_AGG_NOT_FOUND (404)
• ERR_AGG_RATE_LIMIT (429)
• ERR_AGG_UPSTREAM (5xx)
• ERR_AGG_UNKNOWN (fallback)

Caching & pagination

• limit max: 200.
• Cursor/paging uses continuationToken (opaque string).
• ETag MUST be stable over sorted payload; clients MAY send If-None-Match.

Determinism rules

• Ordering: list responses sorted by (statementId asc) unless specified otherwise; ties break by statementId.
• Timestamps: ISO-8601 UTC.

Samples

• vex-statements-list.json — list response.
• vex-statement-detail.json — statement detail.
• vex-evidence-list.json — evidence links.