diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0096cd8..2e423bc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -86,6 +86,10 @@ jobs: image-ref: ghcr.io/${{ github.repository }}:${{ github.ref_name }} # CRITICAL blocks the release; HIGH is visible in the scan output but the # Debian base image rotates packages too often to gate on it. + # + # The ignore file is passed explicitly: its YAML form (which supports an + # expiry date, so an exception cannot rot) is not auto-detected. + ignorefile: .trivyignore.yaml severity: CRITICAL exit-code: "1" ignore-unfixed: true diff --git a/.trivyignore.yaml b/.trivyignore.yaml new file mode 100644 index 0000000..fa10011 --- /dev/null +++ b/.trivyignore.yaml @@ -0,0 +1,24 @@ +# Time-boxed, reviewable exceptions for the container gate. +# +# Everything here is a CRITICAL that the gate would otherwise block on, with a date after +# which the ignore stops working and the release fails again — so this cannot rot quietly. +# +# Re-check when Spring Boot 4 lands: both are fixed only in Spring Framework 7.0.9, and +# Boot 3.5.x (the latest 3.5 line) still ships 6.2.19. +vulnerabilities: + - id: CVE-2026-47884 + statement: >- + RCE via XsltView path limitation in spring-webmvc. Fixed only in Spring Framework + 7.0.9 (Spring Boot 4). Path is a REST-only application: every controller returns + JSON or SSE via @RestController, there is no view resolver, no View implementation + and no JSP or XSLT rendering on the classpath, so the affected code path is not + reachable. Revisit with the Spring Boot 4 migration. + expired_at: 2027-02-01 + + - id: CVE-2026-47890 + statement: >- + SSE stream corruption when view rendering is involved, fixed only in Spring + Framework 7.0.9 (Spring Boot 4). Path does stream SSE, but it writes the response + body directly from StreamService rather than through a view, and the advisory's + affected path is view rendering. Revisit with the Spring Boot 4 migration. + expired_at: 2027-02-01 diff --git a/CHANGELOG.md b/CHANGELOG.md index a17b956..19c53e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ verbatim as the body of the matching GitHub release. | Version | Date | Notes | |---|---|---| +| v0.2.1 | 2026-11-17 | [changelog/v0.2.1.md](changelog/v0.2.1.md) | | v0.2.0 | 2026-11-17 | [changelog/v0.2.0.md](changelog/v0.2.0.md) | | v0.1.0 | 2026-11-17 | [changelog/v0.1.0.md](changelog/v0.1.0.md) | diff --git a/changelog/v0.2.1.md b/changelog/v0.2.1.md new file mode 100644 index 0000000..179746c --- /dev/null +++ b/changelog/v0.2.1.md @@ -0,0 +1,104 @@ +# v0.2.1 + +Supersedes `v0.2.0`, which never completed: its container image was pushed but the release +job stopped at the vulnerability scan, so no GitHub release or notes were published. + +Adds the dependency updates that scan demanded. Everything else since the `v0.1.0` tag: the gateway gains a second routing strategy, guardrails, +an end-user billing axis, a semantic cache, Azure OpenAI and a Helm chart — plus the +fixes from a twelve-point security and billing audit. + +## Added + +### Routing and model selection + +- **Adaptive routing.** A route can declare `strategy`: `priority` (the default, unchanged), + `fastest` (ordered by an exponentially weighted latency) or `cheapest-viable` (cheapest + route under a `latency_slo_ms`, the rest demoted to fallback). Route views expose + `ewma_latency_ms` and `ewma_error_rate` so the decision is auditable, and `provider.order` + still overrides any strategy. +- **Operator-defined aliases.** `GET/POST /admin/aliases` stores an ordered chain + (`prod-chat` → `claude-sonnet-4.5`, then `gpt-4o`). Chains are validated at write time — + an unknown model, a self-reference or more than ten hops is a 400, so a broken alias + cannot become a 500 on a customer request. The four computed aliases (`cheap`, `fast`, + `long-context`, `vision`) are unchanged. + +### Billing and limits + +- **End-user attribution.** `end_user` (or OpenAI's `user`) is stored on every usage row + and indexed, `/v1/usage` returns a per-end-user breakdown, `/admin/usage` and the CSV + export filter by it, and a key can cap each customer with `end_user_daily_limit_usd` — + reserved with an atomic conditional update, so concurrency cannot overshoot. +- **Project rate limits.** Projects carry `rpm_limit` and `max_concurrent_requests`, + enforced in addition to each key's caps, and shared across replicas through the Valkey + limiter. +- **Project budget alerts.** `project.budget_low` and `project.budget_exhausted` fire once + per project, window and period. +- **`POST /v1/tokens/count`.** Free but authenticated: reports prompt tokens and whether the + prompt fits, counting tool definitions, which is where estimates are usually wrong. +- **Idempotent embeddings.** `/v1/embeddings` honours `Idempotency-Key`; a retried batch is + no longer billed twice. + +### Safety and privacy + +- **Guardrails.** PII redaction for prompt logs (on by default) and optionally before send, + plus opt-in moderation passthrough that refuses a flagged prompt with 400 + `content_flagged`. `GET /admin/settings` reports what is active. +- **Semantic cache tier.** With `semantic_cache_enabled` on a route and + `GATEWAY_SEMANTIC_MODEL` set, a near-duplicate prompt can reuse a stored completion, + under the same `temperature: 0`, tool-free, per-key rules as the exact cache. + +### Providers and deployment + +- **Azure OpenAI.** Setting `api_version` on a provider puts the deployment in the path, the + version in `?api-version` and the credential in the `api-key` header, for chat, + embeddings, moderation and the probe. +- **Helm chart** in `deploy/helm/path`: drain-aware grace period enforced at render time, + HPA with a custom-metric hook, PDB, optional Postgres and Valkey, ServiceMonitor. +- **Per-provider health** at `/actuator/health/providers`; overall health only reports + OUT_OF_SERVICE when every enabled provider is circuit-open. + +## Fixed + +The post-0.1.0 audit found twelve issues; all are fixed: + +- `models/sync` imported unpriced routes enabled, serving inference for free. +- 500 responses returned internal exception messages; they now return a reference id and + log the detail server-side. +- Chunked request bodies bypassed the size limit; reading is now counted and 413s. +- The demo API key was created by default, including in the `prod` profile. +- A large `max_tokens` could reserve credit the call would never use. +- Reservation now uses the expected cost while still refusing when it does not fit. +- `/v3/api-docs` was served in production; off in the `prod` profile. +- The in-memory rate-limit windows were never evicted. +- Release tags were not verified to be on `main`. +- `UpstreamClient` allocated an `ObjectMapper` per error. +- Project filters were missing from `/admin/usage`, `/admin/stats` and the CSV export. +- Admin auth had no lockout; ten failures in five minutes now return 429. + +Also fixed: the end-user cap was skipped for keys without a credit limit, and `api_version` +was ignored on provider `PATCH`. + +## Security + +- **Tomcat 10.1.55 → 10.1.62** and **Netty 4.1.135 → 4.1.141**, both of which Spring Boot + 3.5.16 still pins and both of which carry CRITICAL advisories. Overridden in the pom + rather than by moving the framework version; drop the overrides when Boot manages them. +- **Two Spring Framework CVEs are accepted, with a deadline.** `CVE-2026-47884` (RCE via + `XsltView` path limitation) and `CVE-2026-47890` (SSE corruption during view rendering) + are fixed only in Spring Framework 7.0.9, which means Spring Boot 4. Path registers no + view resolver and renders nothing through a `View`, so neither path is reachable. They + are listed in `.trivyignore.yaml` with a `statement` and an `expired_at` of 2027-02-01, + after which the release gate fails again until they are revisited. + +- Every GitHub Action is pinned to a commit SHA; a mutable tag can be repointed at any + commit and would run with this repository's token. +- Master key rotation (`POST /admin/rotate-master-key`) re-encrypts stored credentials + before switching the active key. + +## Notes + +- Maven Central publishing is configured (`-P release`, `io.github.an1ndra:path`) and + verified locally against a throwaway key; the upload itself is pending a namespace and a + Portal token. See `docs/PUBLISHING.md`. +- Five stories remain open: Spring AI module, Vertex/Gemini native, Valkey-shared breaker, + usage partitioning, and the Central publication. diff --git a/deploy/helm/path/Chart.yaml b/deploy/helm/path/Chart.yaml index 62d1dd1..853fe84 100644 --- a/deploy/helm/path/Chart.yaml +++ b/deploy/helm/path/Chart.yaml @@ -2,8 +2,8 @@ apiVersion: v2 name: path description: Path — a provider-agnostic LLM gateway with routing, fallback, credits and cache-aware token metering type: application -version: 0.2.0 -appVersion: "0.2.0" +version: 0.2.1 +appVersion: "0.2.1" kubeVersion: ">=1.27.0-0" home: https://github.com/an1ndra/path sources: diff --git a/pom.xml b/pom.xml index b0e004a..68cc028 100644 --- a/pom.xml +++ b/pom.xml @@ -13,7 +13,7 @@ io.github.an1ndra path - 0.2.0 + 0.2.1 path Provider-agnostic LLM gateway: routing, fallback, credits and cache-aware token metering for OpenAI, Anthropic and any OpenAI-compatible API https://github.com/an1ndra/path @@ -43,6 +43,15 @@ 21 + + + 10.1.62 + 4.1.141.Final