965cbf9574
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Scanner Analyzers / Discover Analyzers (push) Has been cancelled
Scanner Analyzers / Build Analyzers (push) Has been cancelled
Scanner Analyzers / Test Language Analyzers (push) Has been cancelled
Scanner Analyzers / Validate Test Fixtures (push) Has been cancelled
Scanner Analyzers / Verify Deterministic Output (push) Has been cancelled
Findings Ledger CI / build-test (push) Has been cancelled
Findings Ledger CI / migration-validation (push) Has been cancelled
Manifest Integrity / Validate Schema Integrity (push) Has been cancelled
Manifest Integrity / Validate Contract Documents (push) Has been cancelled
Manifest Integrity / Validate Pack Fixtures (push) Has been cancelled
Manifest Integrity / Audit SHA256SUMS Files (push) Has been cancelled
Manifest Integrity / Verify Merkle Roots (push) Has been cancelled
Findings Ledger CI / generate-manifest (push) Has been cancelled
- Implement comprehensive tests for PhpFrameworkSurface, covering scenarios such as empty surfaces, presence of routes, controllers, middlewares, CLI commands, cron jobs, and event listeners. - Validate metadata creation for route counts, HTTP methods, protected and public routes, and route patterns. - Introduce tests for PhpPharScanner, including handling of non-existent files, null or empty paths, invalid PHAR files, and minimal PHAR structures. - Ensure correct computation of SHA256 for valid PHAR files and validate the properties of PhpPharArchive, PhpPharEntry, and PhpPharScanResult.
59 lines
3.0 KiB
Markdown
59 lines
3.0 KiB
Markdown
# Console Search & Downloads · Draft v0.2
|
|
|
|
Scope: unblock WEB-CONSOLE-23-004/005 by defining deterministic ranking, caching rules, and the download manifest structure (including signed metadata option) for console search and offline bundle downloads. Final guild sign-off still required.
|
|
|
|
## 1) Deterministic search ranking
|
|
- Primary sort: `severity (desc)` → `exploitScore (desc)` → `reachability (reachable > unknown > unreachable)` → `policyBadge (fail > warn > pass > waived)` → `vexState (under_investigation > fixed > not_affected > unknown)` → `findingId (asc)`.
|
|
- Secondary tie-breakers (when above fields absent): `advisoryId (asc)` then `product (asc)`.
|
|
- All pages are pre-sorted server-side; clients MUST NOT re-order.
|
|
|
|
## 2) Caching + freshness
|
|
- Response headers: `Cache-Control: public, max-age=300, stale-while-revalidate=60, stale-if-error=300`.
|
|
- `ETag` is a stable SHA-256 over the sorted payload; clients send `If-None-Match` for revalidation.
|
|
- `Last-Modified` reflects the newest `updatedAt` in the result set.
|
|
- Retry/backoff guidance: honor `Retry-After` when present; default client backoff `1s,2s,4s,8s` capped at 30s.
|
|
- Deterministic page cursors: opaque base64url, signed; include `sortKeys` and `tenant` to avoid cross-tenant reuse.
|
|
|
|
## 3) Download manifest (for `/console/downloads` and export outputs)
|
|
Top-level:
|
|
```jsonc
|
|
{
|
|
"version": "2025-12-07",
|
|
"exportId": "console-export::tenant-default::2025-12-07::0009",
|
|
"tenantId": "tenant-default",
|
|
"generatedAt": "2025-12-07T10:15:00Z",
|
|
"items": [
|
|
{
|
|
"type": "vuln", // advisory|vex|policy|scan|chart|bundle
|
|
"id": "CVE-2024-12345",
|
|
"format": "json",
|
|
"url": "https://downloads.local/exports/0009/vuln/CVE-2024-12345.json?sig=...",
|
|
"sha256": "f1c5…",
|
|
"size": 18432
|
|
}
|
|
],
|
|
"checksums": {
|
|
"manifest": "sha256:8bbf…",
|
|
"bundle": "sha256:12ae…" // optional when a tar/zip bundle is produced
|
|
},
|
|
"expiresAt": "2025-12-14T10:15:00Z"
|
|
}
|
|
```
|
|
|
|
### 3.1 Signed metadata
|
|
- Optional DSSE envelope for `checksums.manifest`, using `sha256` digest and `application/json` payload type `stellaops.console.manifest`.
|
|
- Envelope is attached as `manifest.dsse` or provided via `Link: <...>; rel="alternate"; type="application/dsse+json"`.
|
|
- Signers: Authority-issued short-lived key scoped to `console:export`.
|
|
|
|
### 3.2 Error handling
|
|
- Known error codes: `ERR_CONSOLE_DOWNLOAD_INVALID_CURSOR`, `ERR_CONSOLE_DOWNLOAD_EXPIRED`, `ERR_CONSOLE_DOWNLOAD_RATE_LIMIT`, `ERR_CONSOLE_DOWNLOAD_UNAVAILABLE`.
|
|
- On error, respond with deterministic JSON body including `requestId` and `retryAfterSeconds` when applicable.
|
|
|
|
## 4) Sample manifest
|
|
- `docs/api/console/samples/console-download-manifest.json` illustrates the exact shape above.
|
|
|
|
## 5) Open items for guild sign-off
|
|
- Final TTL values for `max-age` and `stale-*`.
|
|
- Whether DSSE envelope is mandatory for sealed tenants.
|
|
- Maximum bundle size / item count caps (proposal: 1000 items, 500 MiB compressed per export).
|