From 6176daa358c5eb21119911a5a56337e8067237aa Mon Sep 17 00:00:00 2001 From: Anindra Date: Tue, 17 Nov 2026 18:34:02 +0530 Subject: [PATCH] release: v0.2.1 with the dependency updates the scan demanded The v0.2.0 release job built and pushed its image, then failed at the Trivy gate with eight CRITICAL findings in the application jar: tomcat-embed-core 10.1.55 5 CVEs fixed in 10.1.62 netty-handler 4.1.135 1 CVE fixed in 4.1.141 spring-webmvc 6.2.19 2 CVEs fixed only in 7.0.9 (Spring Boot 4) Spring Boot 3.5.16 is the latest 3.5 and still pins the old tomcat and netty, so they are overridden in the pom. The two Spring CVEs have no 6.2.x fix; both live in view rendering (XsltView path handling and SSE with views) and 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 expired_at 2027-02-01, and the release workflow now passes that file explicitly because the YAML form is not auto-detected. Verified with the same scanner and flags as the gate: 8 CRITICAL -> 0 on the 0.2.1 jar. 164 tests, 157 smoke checks. 0.2.1 rather than re-tagging 0.2.0 again: the 0.2.0 image was already pushed to GHCR, so that version has published artifacts. --- .github/workflows/release.yml | 4 ++ .trivyignore.yaml | 24 ++++++++ CHANGELOG.md | 1 + changelog/v0.2.1.md | 104 ++++++++++++++++++++++++++++++++++ deploy/helm/path/Chart.yaml | 4 +- pom.xml | 11 +++- 6 files changed, 145 insertions(+), 3 deletions(-) create mode 100644 .trivyignore.yaml create mode 100644 changelog/v0.2.1.md 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