stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity
Files
965cbf9574ac796a189b86addb770b969a712537
git.stella-ops.org/docs/api/console/search-downloads.md
StellaOps Bot 965cbf9574
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Scanner Analyzers / Discover Analyzers (push) Has been cancelled
Details
Scanner Analyzers / Build Analyzers (push) Has been cancelled
Details
Scanner Analyzers / Test Language Analyzers (push) Has been cancelled
Details
Scanner Analyzers / Validate Test Fixtures (push) Has been cancelled
Details
Scanner Analyzers / Verify Deterministic Output (push) Has been cancelled
Details
Findings Ledger CI / build-test (push) Has been cancelled
Details
Findings Ledger CI / migration-validation (push) Has been cancelled
Details
Manifest Integrity / Validate Schema Integrity (push) Has been cancelled
Details
Manifest Integrity / Validate Contract Documents (push) Has been cancelled
Details
Manifest Integrity / Validate Pack Fixtures (push) Has been cancelled
Details
Manifest Integrity / Audit SHA256SUMS Files (push) Has been cancelled
Details
Manifest Integrity / Verify Merkle Roots (push) Has been cancelled
Details
Findings Ledger CI / generate-manifest (push) Has been cancelled
Details
Add unit tests for PhpFrameworkSurface and PhpPharScanner 
- 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.
2025-12-07 13:44:13 +02:00

3.0 KiB
Raw Blame History

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:

{
  "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).