From b1054d9513bd917d1bcbd1b83d722f60d90ecf8e Mon Sep 17 00:00:00 2001 From: Anindra Date: Tue, 17 Nov 2026 18:43:43 +0530 Subject: [PATCH 1/2] docs: record the image-build and scan gotchas Both cost a failed release to learn: - the Dockerfile fetches Maven itself because the wrapper's curl/unzip are not in the base image; do not simplify it back to ./mvnw without building the image - .trivyignore.yaml is not auto-detected, so the release workflow passes it explicitly; every entry carries a statement and an expiry, so an accepted CVE fails the gate again on that date --- AGENTS.md | 10 ++++++++++ SECURITY.md | 1 + 2 files changed, 11 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2a0a7a1..70b3f35 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -158,6 +158,16 @@ a smoke check. Never claim a fix without running both. version — Central is immutable. After a `-P release` build the jar in `target/` is the plain library, so rebuild before running the smoke suite. - CI pins `ubuntu-26.04` (latest LTS) instead of `ubuntu-latest`; bump it deliberately. +- **The Dockerfile fetches Maven itself, not through `./mvnw`.** The wrapper shells out to + curl/unzip, which `eclipse-temurin` does not fully ship; inside the image it downloaded a + file that failed its own SHA-256 check and broke every container build. The build stage + installs those tools and verifies the pin from + `.mvn/wrapper/maven-wrapper.properties` explicitly. Do not "simplify" it back to `./mvnw` + without building the image. +- **`.trivyignore.yaml` must be passed to Trivy explicitly.** The YAML form (the one that + supports `expired_at`) is not auto-detected; the release workflow sets `ignorefile`. Every + entry carries a `statement` and a deadline, so an accepted CVE fails the gate again on + that date instead of living forever. - **Every action is pinned to a commit SHA**, with the tag in a trailing comment (`actions/checkout@3d3c42e5... # v7.0.1`). A mutable tag can be repointed at any commit, which is exactly the supply-chain hole this closes. Bump by merging the Dependabot diff --git a/SECURITY.md b/SECURITY.md index 2d5a628..33f7026 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -36,6 +36,7 @@ Every pull request runs: | Static analysis for Java | CodeQL | | Secrets and misconfiguration in the tree | Trivy | | Repointed action tags (every `uses:` is pinned to a commit SHA) | Dependabot + review | +| Accepted CVEs (`.trivyignore.yaml`, each with a statement and an expiry date) | release gate + review | | Admin auth brute force (10 failures / 5 min per address) | built-in limiter | | Unit, integration and end-to-end tests | Maven + the smoke suite | From 8b1d3d65d489ea2cf640a5100962ca7cfff42e9c Mon Sep 17 00:00:00 2001 From: Anindra Date: Tue, 17 Nov 2026 18:55:18 +0530 Subject: [PATCH 2/2] =?UTF-8?q?release:=20v0.2.2=20=E2=80=94=20pass=20the?= =?UTF-8?q?=20Trivy=20ignore=20file=20under=20the=20right=20input?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit v0.2.1 did fix the vulnerabilities, then failed the scan anyway: Unexpected input(s) 'ignorefile', valid inputs are [..., 'trivyignores', ...] trivy-action only warns about an unknown input, so the scan ran without the exceptions and still saw the two accepted Spring CVEs. The input is `trivyignores` (plural, comma-separated). Fixed, with a comment saying why the name matters. 0.2.2 rather than another re-tag: v0.2.1's image was pushed to GHCR before the scan failed, so that version has published artifacts too. Tests unchanged at 164; this touches the workflow and the version only. --- .github/workflows/release.yml | 8 ++- CHANGELOG.md | 1 + changelog/v0.2.2.md | 111 ++++++++++++++++++++++++++++++++++ deploy/helm/path/Chart.yaml | 4 +- pom.xml | 2 +- 5 files changed, 120 insertions(+), 6 deletions(-) create mode 100644 changelog/v0.2.2.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2e423bc..f1fec82 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -87,9 +87,11 @@ jobs: # 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 + # trivy-action's input is `trivyignores` (plural, comma-separated), not the + # CLI's `--ignorefile`; passing the wrong name is only a warning, so the scan + # silently ran without the exceptions. The YAML form is not auto-detected, so + # it has to be named explicitly. + trivyignores: .trivyignore.yaml severity: CRITICAL exit-code: "1" ignore-unfixed: true diff --git a/CHANGELOG.md b/CHANGELOG.md index 19c53e1..974dd68 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.2 | 2026-11-17 | [changelog/v0.2.2.md](changelog/v0.2.2.md) | | 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.2.md b/changelog/v0.2.2.md new file mode 100644 index 0000000..73b7170 --- /dev/null +++ b/changelog/v0.2.2.md @@ -0,0 +1,111 @@ +# v0.2.2 + +Supersedes `v0.2.0` and `v0.2.1`, neither of which completed: both pushed a container image +and then stopped at the vulnerability scan, so no GitHub release or notes were published +for either tag. + +`v0.2.1` fixed the vulnerabilities; it failed because the workflow passed the Trivy ignore +file under the wrong input name (`ignorefile` instead of `trivyignores`), which the action +only warns about, so the scan ran without the exceptions and failed on the two accepted +CVEs. + +Adds the dependency updates that scan demanded, and the workflow input that makes them +take effect. 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 853fe84..aec1efa 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.1 -appVersion: "0.2.1" +version: 0.2.2 +appVersion: "0.2.2" kubeVersion: ">=1.27.0-0" home: https://github.com/an1ndra/path sources: diff --git a/pom.xml b/pom.xml index 68cc028..032475e 100644 --- a/pom.xml +++ b/pom.xml @@ -13,7 +13,7 @@ io.github.an1ndra path - 0.2.1 + 0.2.2 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