git.stella-ops.org/docs/modules/findings-ledger/export-http-surface.md

Findings Ledger Export HTTP Surface

Prep task: PREP-LEDGER-EXPORT-35-001-NO-HTTP-API-SURFACE (Sprint 0121)

Goals

• Publish an HTTP surface for deterministic, offline-friendly exports of Findings Ledger data (findings, VEX, advisories, SBOMs) so downstream SDK/OpenAPI tasks can proceed.
• Define filter contract, pagination, media types, and provenance fields required by Evidence Locker and Policy Engine consumers.

Non-goals

• Implementing the endpoints (covered by LEDGER-EXPORT-35-001).
• Final OAS/SDK generation (tracked in PREP-LEDGER-OAS-61-001/002/62-001/63-001).

Base Service

• Host: findings-ledger service (minimal API) under src/Findings/StellaOps.Findings.Ledger.
• Base path: /ledger/export.
• Auth: service-to-service bearer token; require scope=ledger.export.read.
• Tenancy: X-Stella-Tenant header (strictly required); responses never mix tenants.
• Determinism: server sorts by (event_sequence, projection_version, cycle_hash); pagination tokens encode the last emitted tuple and filter set. No wall-clock dependence.
• Media types: default application/x-ndjson; clients may request application/json (array) for small result sets. Always emit Content-Encoding: gzip when Accept-Encoding allows.

Endpoints

1) Findings

• GET /ledger/export/findings
• Filters (all optional unless noted):
  • shape (required): canonical | compact (controls payload shape; compact strips verbose provenance fields for air-gap bundles)
  • since_sequence (long, ≥0), until_sequence (long, inclusive) — enables range slicing.
  • since_observed_at, until_observed_at (ISO-8601 UTC) — observation window.
  • advisory_id (repeatable), component_purl (repeatable), finding_status (open|fixed|dismissed), severity (critical|high|medium|low|unknown).
  • risk_profile_version (string) — filters by attached risk profile revision.
• Response item (canonical shape):
  • finding_id, event_sequence, observed_at, component (purl, version, source), advisories (ids, cwes), status, severity, risk (score, severity, profile_version, explanation_id), projection_version, cycle_hash, evidence_bundle_ref (digest, dsse_digest, timeline_ref), provenance (ledger_root, projector_version, policy_version, datasource_ids).

2) VEX

• GET /ledger/export/vex
• Filters: shape, since_sequence/until_sequence, since_observed_at/until_observed_at, product_id (repeatable), advisory_id, status (affected|not_affected|under_investigation), statement_type (exploitation|justification).
• Response item adds vex_statement_id, product (purl or CPE), status_justification, known_exploited (bool), timestamp, projection_version, cycle_hash, provenance.

3) Advisories

• GET /ledger/export/advisories
• Filters: shape, since_sequence/until_sequence, severity, source (feed id), cwe_id, kev (bool), cvss_version, cvss_score_min, cvss_score_max.
• Response item: advisory_id, source, title, description, cwes, cvss (version, vector, base_score), published, modified, status, epss (score, percentile), projection_version, cycle_hash, provenance.

4) SBOMs

• GET /ledger/export/sboms
• Filters: shape, since_sequence/until_sequence, since_observed_at/until_observed_at, subject_digest (OCI digest), sbom_format (spdx-json | cyclonedx-json), component_purl (repeatable), contains_native (bool), slsa_build_type (string).
• Response item: sbom_id, subject (digest, media_type), sbom_format, created_at, components_count, has_vulnerabilities (bool), materials (digests), projection_version, cycle_hash, provenance.

Pagination

• Cursor param: page_token (opaque base64url JSON: { "last": { "event_sequence": long, "projection_version": string, "cycle_hash": string }, "filters_hash": sha256 }).
• Page size: page_size (default 500, max 5000). Server rejects if page_size differs across pages for same token.
• Response envelope (for both NDJSON and JSON array):
  • Header X-Stella-Next-Page-Token when more data exists.
  • Header X-Stella-Result-Count with items count.
  • When Prefer: return=minimal is set, omit envelope body for NDJSON; clients rely on headers.

Error Contract

• 400: unknown filter, invalid range, or filter combination mismatch with filters_hash inside page_token.
• 401/403: missing or insufficient scope.
• 409: requested shape not compatible with downstream air-gap mode (compact requested where policy mandates canonical).
• 429: enforcement of determinism guard (server detected projection drift vs cycle_hash); include X-Stella-Drift-Reason.

Observability & Determinism Hooks

• Emit structured logs ledger.export.request and ledger.export.emit with tenant, endpoint, filters_hash, page_size, result_count, duration_ms.
• Counters: ledger_export_items_total{endpoint,tenant} and ledger_export_failures_total{endpoint,reason}.
• Traces: span name ledger.export.{endpoint}; attach filters_hash, page_size, next_page_token_present attributes.

artefact location

• This document: docs/modules/findings-ledger/export-http-surface.md (hash stability: keep deterministic ordering as authored on 2025-11-20).
• Link from sprint 0121 PREP-LEDGER-EXPORT-35-001; downstream tasks should reference this path for contract details.