18d87c64c5
- 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.
51 lines
2.8 KiB
Markdown
51 lines
2.8 KiB
Markdown
# 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)_
|