# Zentinel

> A security-first reverse proxy built on Pingora: explicit configuration, bounded resources, and WAF and auth in isolated agents.

## What Zentinel is

Zentinel is a security-first reverse proxy built to guard the free web. It is written in Rust on Cloudflare's [Pingora](https://github.com/cloudflare/pingora), through a fork published on crates.io as `zentinel-pingora-*`.

- **Configuration:** KDL, in one file or several joined with `include`. Validated with `zentinel test`; `zentinel lint` reports settings that are being ignored. Reloaded on `SIGHUP`, or on file change with `auto-reload`, and validated before an atomic swap.
- **Routing and upstreams:** routes match on host and path; load balancing includes round robin, least connections, consistent hashing, Maglev and power of two choices; active health checks over HTTP, TCP and gRPC; retries and circuit breakers.
- **TLS:** termination with per-SNI certificates, client certificates (mTLS) and ACME issuance. HTTP/1.1 and HTTP/2 downstream and upstream; HTTP/3 is not implemented.
- **Traffic handling:** response caching, rate limiting, GeoIP filtering (MaxMind and IP2Location databases), response compression with gzip, Brotli or zstd negotiated from `Accept-Encoding`, and static file serving.
- **Agents:** WAF, authentication and other policy run in agents, separate processes the proxy talks to over Unix domain sockets or gRPC (optionally with TLS) using agent protocol v2. Each agent has its own timeout and a `failure-mode` of open or closed, so a slow or crashed agent does not take the proxy down. The [agent registry](https://registry.zentinelproxy.io/) lists agents for WAF and ModSecurity rules, bot management, IP reputation, authentication and SPIFFE identity, GraphQL, gRPC and SOAP inspection, and scripting in Lua, JavaScript or WebAssembly. SDKs for writing agents exist for Rust, Go, Python, TypeScript, Kotlin, Elixir and Haskell.
- **Observability:** Prometheus metrics and structured access, error and audit logs. OpenTelemetry tracing and Redis or memcached-backed distributed rate limiting are build features (`opentelemetry`, `distributed-rate-limit`), not in the default build.
- **Licence:** Apache 2.0.

Current release: 26.10_8 (GitHub release tag; the crate on crates.io is `zentinel-proxy`).

## Site

- [Benchmarks](https://zentinelproxy.io/benchmarks/): Performance, soak testing, and chaos engineering results for Zentinel reverse proxy
- [Compare](https://zentinelproxy.io/compare/): How Zentinel differs from nginx, HAProxy, Envoy, Caddy and Traefik — on design, not on benchmarks.
- [Contributing](https://zentinelproxy.io/contributing/): How to contribute to Zentinel: where to start, what belongs in the core, and where to ask questions.
- [Control Plane](https://zentinelproxy.io/control-plane/): Fleet management for Zentinel reverse proxies. Declarative configuration distribution with safe rollouts, real-time monitoring, and audit logging.
- [Config Converter](https://zentinelproxy.io/converter/): Convert nginx, HAProxy, Traefik, Caddy, and Envoy configurations to Zentinel KDL format
- [Customize Your Installation](https://zentinelproxy.io/customize/): Configure Zentinel with the agents you need. Generate installation commands and starter configuration for your use case.
- [Features](https://zentinelproxy.io/features/): Comprehensive feature list of Zentinel reverse proxy with source code references
- [Manifesto](https://zentinelproxy.io/manifesto/): Why Zentinel exists: boring infrastructure, explicit security, and guarding the free web
- [Playground](https://zentinelproxy.io/playground/): Interactive Zentinel configuration playground - validate configs, simulate requests, and visualize routing decisions
- [Security](https://zentinelproxy.io/security/): How to report a vulnerability in Zentinel, which versions receive fixes, and how to verify what you deploy.
- [Supply Chain Security](https://zentinelproxy.io/supply-chain/): Every Zentinel release is signed, attested, and ships with a full software bill of materials. Verify what you deploy.
- [Support](https://zentinelproxy.io/support/): Support Zentinel's mission to guard the free web. Community support, sponsorship, and enterprise builds.

## Documentation

The documentation is a separate site at https://docs.zentinelproxy.io/ (served at its root; there is no /docs/ path on zentinelproxy.io).

- [Installation](https://docs.zentinelproxy.io/getting-started/installation/)
- [Configuration](https://docs.zentinelproxy.io/configuration/)
- [Agents](https://docs.zentinelproxy.io/agents/)
- [Known limitations](https://docs.zentinelproxy.io/reference/known-limitations/): settings that are accepted but not yet applied
- [Changelog](https://docs.zentinelproxy.io/appendix/changelog/)

## Blog

- [Why Zentinel Runs on a Fork of Pingora](https://zentinelproxy.io/blog/why-we-fork-pingora/) (2026-10-20): Twice this year we wrote that our Pingora fork was temporary, kept only until upstream caught up on a security fix. It is still here, it is now published on crates.io, and it no longer exists for security reasons. Here is what it changes, why a proxy needs those changes, and what keeping a fork actually costs.
- [It Parsed, and Did Nothing](https://zentinelproxy.io/blog/it-parsed-and-did-nothing/) (2026-10-19): Between August and October we fixed more than a dozen Zentinel features that were accepted, validated and logged as running, and had no effect. Timeouts, failure modes, TLS settings, health checks, agents, WAF rules. None of them produced an error, because none of them failed. Here is the shape they share, why ordinary testing cannot see it, and the checks that catch it now.
- [Zentinel 26.09–26.10: Pingora 0.9, Health Checks That Probe, and a Security Sweep](https://zentinelproxy.io/blog/zentinel-26-09-26-10/) (2026-10-18): Nine releases in seven weeks, from 26.09_1 to 26.10_3. Health checks that had never sent a probe now do, agents that restart are no longer lost, bundle install works for non-root users, the engine moves to Pingora 0.9.0, ACME renewal follows the CA's window, and 26.10_3 brings wasmtime 49 and rustls 0.23.46. Here is what changed and what to check when you upgrade.
- [A Gateway for Agentic Protocols](https://zentinelproxy.io/blog/the-gateway-for-agentic-protocols/) (2026-09-02): Zentinel now does for MCP what a reverse proxy has always done for HTTP: per-tool metrics, per-tool rate limits, a tool list cut to what the route permits, and a health check that speaks the protocol. Here is what shipped, two things it caught that had been silently broken for months, and an honest outlook on the harder question — whether a proxy should also be an MCP server.
- [Header Says Read, Body Says Delete](https://zentinelproxy.io/blog/header-says-read-body-says-delete/) (2026-08-23): MCP's Streamable HTTP transport mirrors the tool name into an HTTP header so that gateways can route without parsing the body. Read that header and enforce policy on it, and you have built an allowlist that allows everything. Here's the desync, the version-downgrade that defeats the obvious fix, and what Zentinel does instead.
- [Benchmarks Should Be Able to Fail](https://zentinelproxy.io/blog/benchmarks-should-be-able-to-fail/) (2026-08-22): If the work your benchmark measures is conditional, the benchmark can silently measure nothing — and it will report that as your best result. Here's the guard we added to zentinel-modsec's WAF benchmarks, why transaction setup overhead is easy to mistake for rule-engine throughput, and the figures we now stand behind: 4-11x faster than libmodsecurity.
- [One Config, Many Files: Merging Included KDL in Zentinel](https://zentinelproxy.io/blog/splitting-config-across-files/) (2026-06-23): Zentinel has always let you split configuration across files with `include`. But until recently, each top-level block could only live in one file — a second `routes {}` silently won. As of 26.06_3, blocks merge across includes, with duplicate IDs caught at parse time. Here's how it works and the per-vhost pattern it unlocks.
- [Parsing Isn't Running: Making Pure-Rust ModSecurity Pass Stock OWASP CRS v4](https://zentinelproxy.io/blog/pure-rust-modsecurity-crs-v4/) (2026-06-16): Our pure-Rust ModSecurity engine loaded 666 OWASP CRS v4 rules without complaint — and then blocked every single request, including GET /. A precise community bug report traced it to six SecLang semantics that parsed fine but executed wrong. Here's the anatomy of the fix, shipped in zentinel-modsec 0.1.3.
- [NGINX Ingress Is Dead. Here's What to Do Next.](https://zentinelproxy.io/blog/nginx-ingress-is-dead/) (2026-03-14): NGINX Ingress Controller maintenance halted in March 2026, with no more releases or security patches. We built a Gateway API controller for Zentinel. Here's the migration story.
- [Three HTTP Smuggling CVEs in Pingora, and How Zentinel Responded](https://zentinelproxy.io/blog/pingora-cve-response/) (2026-03-10): A security researcher found four vulnerabilities in Cloudflare's Pingora framework, including three HTTP request smuggling bugs. Here's what each one means for Zentinel, how operators could have mitigated before the fix, and why we were already running the patched version before the CVEs went public.
- [Zentinel Upgrades to Pingora 0.8: Keepalive Limits, Stricter HTTP Framing, and a Leaner Builder API](https://zentinelproxy.io/blog/pingora-0-8-upgrade/) (2026-03-05): Pingora 0.8.0 brings connection reuse limits, stricter HTTP/1 validation, upload write-pending diagnostics, and a new builder pattern for proxy services. Here's what changed in Zentinel and what operators should know.
- [598 Attack Payloads, Three WAF Engines, One Verdict](https://zentinelproxy.io/blog/waf-agent-comparison/) (2026-03-04): We built wafworth, an open-source WAF testing framework with 598 tests across 18 OWASP-aligned categories, and used it to benchmark Zentinel's three WAF agent implementations against each other. No engine won everywhere. Here's what the confusion matrices actually say.
- [How zentinel bundle Works: A Static API, a Lock File, and 26 Agents](https://zentinelproxy.io/blog/bundle-command-and-agent-registry/) (2026-02-23): The zentinel bundle command installs agents from a static JSON API served by Zola. No database, no package manager runtime, no registry service to operate. Here's how api.zentinelproxy.io generates the metadata and how the CLI consumes it.
- [Sentinel Is Now Zentinel](https://zentinelproxy.io/blog/sentinel-is-now-zentinel/) (2026-02-18): We've rebranded from Sentinel to Zentinel and moved to a new home at zentinelproxy.io. Here's what changed, what didn't, and what you need to do.
- [Introducing the Zentinel Control Plane: Fleet Management Built on Elixir](https://zentinelproxy.io/blog/introducing-control-plane/) (2026-02-16): The Zentinel Control Plane is a fleet management system for Zentinel reverse proxies — built with Elixir/Phoenix and LiveView. It handles configuration distribution, deployment orchestration, and real-time node monitoring. Here's what we built, why we chose Elixir, and how the internals work.
- [Zentinel Upgrades to Pingora 0.7: Dropping the Fork, Gaining New Capabilities](https://zentinelproxy.io/blog/pingora-0-7-upgrade/) (2026-02-02): Cloudflare's Pingora 0.7 ships connection-level filtering, extensible TLS context, and the security fixes we were carrying in a fork. Zentinel now runs on upstream Pingora with zero patches — here's what changed and what it unlocks.
- [Zentinel 26.02: Every Binary Signed, Every Dependency Listed](https://zentinelproxy.io/blog/release-26-02/) (2026-01-29): Release 26.02 adds supply chain security to every Zentinel release — cosign signatures, SLSA provenance, and SBOMs in CycloneDX and SPDX formats. Here's what we built, why it matters, and how to verify your deployment in 30 seconds.
- [Benchmarking Zentinel Against the Established Proxies](https://zentinelproxy.io/blog/matching-the-competition/) (2026-01-28): We put Zentinel head-to-head with Envoy, HAProxy, nginx, and Caddy — then used the results to find and fix the per-request allocations that were costing us CPU. Three rounds of optimization later, Zentinel matches or beats every proxy we tested on tail latency.

## Optional

- [All site writing in full](https://zentinelproxy.io/llms-full.txt): this summary, the Markdown pages and every blog post in one file
- [Agent registry](https://registry.zentinelproxy.io/)
- [Source code](https://github.com/zentinelproxy/zentinel)
- [Releases](https://github.com/zentinelproxy/zentinel/releases)
- [Atom feed](https://zentinelproxy.io/atom.xml)