stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/vuln/explorer-api.md
StellaOps Bot 18d87c64c5 feat: add PolicyPackSelectorComponent with tests and integration 
- Implemented PolicyPackSelectorComponent for selecting policy packs.
- Added unit tests for component behavior, including API success and error handling.
- Introduced monaco-workers type declarations for editor workers.
- Created acceptance tests for guardrails with stubs for AT1–AT10.
- Established SCA Failure Catalogue Fixtures for regression testing.
- Developed plugin determinism harness with stubs for PL1–PL10.
- Added scripts for evidence upload and verification processes.
2025-12-05 21:24:34 +02:00

2.8 KiB
Raw Permalink Blame History

Vuln Explorer API (Md.XI draft)

Status: DRAFT — depends on GRAP0101 contract and console/CLI payload samples. Publish only after schemas freeze and hashes recorded.

Scope

  • Describe public Explorer API endpoints, query schema, grouping, errors, and rate limits.
  • Include deterministic examples with hashed request/response payloads.

Prerequisites

  • GRAP0101 contract (final field names, query params).
  • Payload samples from console/CLI asset drop (due 2025-12-09).
  • Current architecture reference: docs/modules/vuln-explorer/architecture.md.

Endpoints (to finalize)

  • GET /v1/findings — list with filters (tenant, advisory, status, reachability, VEX, priority, owner); pagination & sorting.
  • GET /v1/findings/{id} — detail (policy context, explain trace, attachments, history).
  • POST /v1/findings/{id}/actions — create action (assign, comment, status change, remediation, ticket link) with DSSE optional.
  • POST /v1/reports — create report; returns manifest + location.
  • GET /v1/reports/{id} — fetch report metadata/download.
  • GET /v1/exports/offline — download deterministic bundle (JSONL + manifests + signatures).
  • POST /v1/vex-decisions / PATCH /v1/vex-decisions/{id} / GET /v1/vex-decisions — decision lifecycle (aligns with vex-decision.schema.json).

Query Schema (draft)

  • Filters: tenant, advisoryId, vexStatus, reachability, priority, status, owner, artifactId, sbomComponentId.
  • Pagination: page, pageSize (cap tbd per GRAP0101).
  • Sorting: sort (supports multi-field, stable order; default priority desc, updatedAt desc).
  • Projection: fields allowlist to shrink payloads; defaults tbd.
  • ETag/If-None-Match for cache-aware clients (confirm in GRAP0101).

Errors & Rate Limits

  • Standard error envelope (status, code, message, correlationId); attach hint when policy gate blocks action.
  • Rate limits: per-tenant and per-service-account quotas; retry after header; offline bundles exempt.

Determinism & Offline

  • All example payloads must be fixed fixtures; record hashes in docs/assets/vuln-explorer/SHA256SUMS.
  • Use canonical ordering for list responses; include sample ETag and manifest hash where relevant.

Fixtures to Capture (when assets drop)

  • assets/vuln-explorer/api-findings-list.json (filtered list response)
  • assets/vuln-explorer/api-finding-detail.json (detail with history/actions)
  • assets/vuln-explorer/api-action-post.json (action request/response)
  • assets/vuln-explorer/api-report-create.json (report creation + manifest)
  • assets/vuln-explorer/api-vex-decision.json (create/list payloads)

Open Items

  • Fill in finalized parameter names, limits, and error codes from GRAP0101.
  • Add example requests/responses once asset drop is delivered; include hashes.
  • Confirm DSSE optional flag shape for actions endpoint.

Last updated: 2025-12-05 (UTC)