58 lines
3.3 KiB
Markdown
58 lines
3.3 KiB
Markdown
# Console Search and Downloads
|
|
|
|
This document defines deterministic ranking, caching rules, and the download manifest shape used by Console search and export-style workflows.
|
|
|
|
## 1) Deterministic search ranking
|
|
- Primary sort: `severity (desc)` then `exploitScore (desc)` then `reachability (reachable > unknown > unreachable)` then `policyBadge (fail > warn > pass > waived)` then `vexState (under_investigation > fixed > not_affected > unknown)` then `findingId (asc)`.
|
|
- Secondary tie-breakers (when primary fields are absent): `advisoryId (asc)` then `product (asc)`.
|
|
- Pages are pre-sorted server-side; clients MUST NOT re-order results.
|
|
|
|
## 2) Caching and freshness
|
|
- Response headers (recommended defaults): `Cache-Control: private, max-age=300, stale-while-revalidate=60, stale-if-error=300`.
|
|
- `ETag` SHOULD be a stable SHA-256 over a canonicalized, sorted payload so identical inputs produce identical validators; clients send `If-None-Match` for revalidation.
|
|
- `Last-Modified` SHOULD reflect the newest `updatedAt` present in the result set.
|
|
- Retry/backoff: honor `Retry-After` when present; otherwise use deterministic client backoff (for example `1s, 2s, 4s, 8s` capped at 30s).
|
|
- Page cursors: opaque base64url, signed; bind to `tenant` and effective sort keys to avoid cross-tenant or cross-sort reuse.
|
|
|
|
## 3) Download manifest
|
|
When a Console workflow produces downloadable artifacts (individual documents or a bundle), services can return a manifest describing:
|
|
- What items are available,
|
|
- Where to download them (signed URLs or gateway-relative links),
|
|
- How to verify them offline (checksums and optional signature metadata).
|
|
|
|
Top-level fields:
|
|
- `version` (string): manifest schema/version label used by the producer.
|
|
- `exportId` (string): stable export identifier (content-addressable or run-id style).
|
|
- `tenantId` (string): tenant scope for this export.
|
|
- `generatedAt` (RFC 3339 / ISO-8601 UTC): generation timestamp.
|
|
- `items[]` (array): downloadable artifacts.
|
|
- `checksums` (object): checksum(s) for the manifest itself and optional bundle artifact.
|
|
- `expiresAt` (RFC 3339 / ISO-8601 UTC): optional expiry for signed URLs.
|
|
|
|
Item fields:
|
|
- `type` (string): artifact type (for example `vuln`, `vex`, `policy`, `scan`, `bundle`).
|
|
- `id` (string): stable identifier within the type (CVE id, statement id, export id, etc).
|
|
- `format` (string): `json`, `ndjson`, `tar.gz`, etc.
|
|
- `url` (string): download URL (often signed).
|
|
- `sha256` (string): lowercase hex digest of the bytes at `url`.
|
|
- `size` (int): byte size.
|
|
|
|
### Signed metadata (optional)
|
|
Producers MAY ship a DSSE envelope for the manifest checksum:
|
|
- Payload type: `stellaops.console.manifest`
|
|
- Media type: `application/json`
|
|
- Distribution: alongside the manifest (for example `manifest.dsse`) or via a link relation (for example `rel=\"alternate\"` with `type=\"application/dsse+json\"`).
|
|
|
|
## 4) Error handling
|
|
Known error codes for download/manifest flows:
|
|
- `ERR_CONSOLE_DOWNLOAD_INVALID_CURSOR`
|
|
- `ERR_CONSOLE_DOWNLOAD_EXPIRED`
|
|
- `ERR_CONSOLE_DOWNLOAD_RATE_LIMIT`
|
|
- `ERR_CONSOLE_DOWNLOAD_UNAVAILABLE`
|
|
|
|
On error, return the standard error envelope with deterministic fields (stable code/message, plus request/trace identifiers).
|
|
|
|
## 5) Samples and fixtures
|
|
- Download manifest example: `docs/api/console/samples/console-download-manifest.json`
|
|
|