shuaiZend/PingWAF
shuaiZend/PingWAF has 50 GitHub stars and 7 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 20:47 UTC. Last push 2026-11-12.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Distributed, centrally-controlled Web Application Firewall built on pingap & Cloudflare Pingora. Semantic attack detection, Cloudflare-style rules, CC & Bot defense, automatic TLS, embedded i18n dashboard.
Self-hostedREADME.md
Original🛡️ PingWAF
A distributed, centrally-controlled Web Application Firewall built on pingap and Cloudflare Pingora.
Semantic-grade attack detection · Cloudflare-style rules · CC & Bot defense · Automatic TLS · Embedded i18n dashboard
English | 简体中文 | Español | Français
Quick Start · Architecture · Features · Documentation · Contributing
📖 What is PingWAF?
PingWAF is a high-performance, open-source Web Application Firewall (WAF) that brings Cloudflare-class edge security to your own infrastructure. It is built on top of pingap — a production reverse proxy powered by Cloudflare's Pingora networking framework — and adds a distributed, centrally-controlled security layer over it.
A single control plane defines sites, rules and policies; one or many data-plane agents enforce them at the edge. Rules, logs and metrics flow between the two over persistent gRPC bidirectional streams, so a policy change made in the dashboard propagates to every agent in seconds — no reload, no downtime.
- 🎯 Semantic detection — SQLi / XSS / RCE / path traversal / command injection via
libinjection+ Aho-Corasick signature matching, anomaly scoring and Cloudflare-style expression rules. - 🕸️ Distributed by design — run everything in one process (
all-in-one), or scale the data plane out to many independent edge agents (server+agent). - 🧭 Batteries included, off by default — every protection feature ships disabled and is enabled per site, so you stay in full control of your traffic.
- ⚡ Rust all the way down — memory safety, async I/O and a single self-contained binary with the dashboard embedded.
PingWAF is an independent project. It is not affiliated with, nor endorsed by, Cloudflare or the
pingapmaintainers. See Acknowledgements.
🏗️ Architecture

The control plane and the data plane talk over the ControlPlane gRPC service (defined in control_plane.proto) with seven RPCs:
| RPC | Kind | Purpose |
|---|---|---|
RegisterAgent |
Unary | An agent joins the fleet and receives its ID + heartbeat interval |
Heartbeat |
Bidirectional stream | Liveness, stats and per-site certificate status upstream; live commands downstream |
SyncRules |
Server stream | Rule bundles pushed to agents whenever policy changes |
ShipLogs |
Client stream | Batched request/attack logs streamed to the control plane |
ShipCertEvents |
Client stream | ACME issuance events captured on the agent, streamed to the control plane |
ShipMetrics |
Client stream | Batched traffic metrics streamed to the control plane |
GetSiteConfig |
Unary | An agent pulls the full config for a single site |
Two deployment shapes, one binary:
- All-in-One — control plane + data plane in a single process. Ideal for a single node, small deployments and local evaluation.
- Distributed — one independent
server(control plane) plus manyagentprocesses at the edge. Ideal for fleets, multi-region rollouts and central management.
✨ Features
🛡️ Security Detection
- Semantic WAF engine covering SQL injection, XSS, RCE, path traversal and command injection — powered by
libinjectionheuristics plus Aho-Corasick multi-pattern signature matching. - Four-phase pipeline:
normalize(request normalization) →signatures(signature / libinjection) →expression(rule expressions) →anomaly score(weighted scoring). - Cloudflare-style expression rules — write conditions like
http.request.uri.path contains "/admin" and ip.src in {1.2.3.0/24}. - Anomaly scoring with four verdicts:
Pass,Monitor,Block,Challenge. - Managed rule sets — curated signatures you can toggle per site.
🤖 CC & Bot Defense
- CC protection / 5-second shield — JavaScript challenge, Proof-of-Work and interactive challenges, with HMAC-signed clearance cookies.
- Bot protection — verified-bot whitelist, known-browser pass-through and a configurable action for everything else; TLS fingerprinting and behavioral analysis are on the roadmap.
🚦 Access Control
- IP access rules —
block/allow/challenge/js_challenge, with CIDR ranges, CSV bulk import and named rules. - Global IP groups — subscription-backed CIDR lists (plain text, JSON or the Cloudflare IP ranges API) synced to every site on a schedule, with sync-error reporting.
- Geo restriction — allow or block by country and by autonomous system number (ASN), with an optional "block unknown countries" policy.
- Multi-dimensional rate limiting — by IP, host, path, ASN, country, or a request header, cookie or query parameter.
🌊 Traffic Management
- Origin pools & routes — group upstreams into pools with load balancing (round-robin, least connections, random or consistent hashing by IP/URL/path/header/cookie/query) and route requests by prefix, exact match or regex — optionally restricted to an IP group, so a path can be served differently to office or partner addresses.
- Edge caching with per-site disk quotas and LRU eviction, stale-while-revalidate and browser TTL control.
- Request / response rewriting — headers, paths, query strings, status codes and body search/replace.
- Custom error pages rendered with Tera templates — including edge-generated responses such as WAF blocks and paused sites.
- Pause a site from the console: every request gets a
503maintenance page while the certificate keeps serving and traffic stays logged.
🔐 TLS & Certificates
- Automatic ACME / Let's Encrypt issuance and renewal on the edge (HTTP-01 and DNS-01).
- Multiple DNS providers for DNS-01 (Aliyun, Cloudflare, Tencent Cloud DNSPod, Huawei Cloud, manual).
- Per-site certificate status (
valid/expiring soon/expired) reported to the control plane over heartbeats, with a searchable ACME event log. - HSTS and forced HTTPS applied at the edge, with a 180-day default
max-age. - Mutual TLS (mTLS) — generate or import a CA, issue client certificates from the console, and revoke a single certificate with immediate effect at the edge; a certificate is refused when it is revoked or was issued for another site.
- HTTPS origin certificate verification is an explicit switch — a deployment-wide default in Settings → Origin, overridable per origin pool. The default accepts any origin certificate so self-signed and internal-PKI origins keep working; turn it on where origins present a trusted certificate.
📊 Observability
- Full request logging to Elasticsearch with body truncation and a WAL buffer for reliability.
- Raw request and response capture — headers, body prefixes, real sizes and truncation flags in PostgreSQL, so a log entry can be replayed as a
curlcommand from the console. Headers are stored verbatim (cookies included) to make an attack reproducible. - Analytics dashboards for traffic and attack trends.
- Agent health, traffic stats and cache hit/eviction metrics reported to the control plane over heartbeats.
🎛️ Management Console
- JWT + bcrypt authentication and multi-tenant isolation.
- Passkey sign-in (WebAuthn) alongside passwords — bind a platform authenticator or security key from Settings and sign in without a password.
- Embedded i18n dashboard (English / 简体中文 / 日本語), compiled into the binary via
rust-embed. - Everything is off by default — enable protections explicitly, per site.
- Configuration versioning — the console lists every configuration snapshot with filters, diffs a version against its predecessor table by table, and rolls back behind a confirmation.
📊 Measured effectiveness

Measured on the public blazehttp corpus (33 877 raw HTTP requests: 658 malicious / 33 219 benign), replayed byte-for-byte against a release build. Interception counts the WAF verdict surface — the 403 block page and the 503 challenge page — and "benign affected" counts both, so a challenge is never hidden inside a "blocked" number.
On the requests a reverse-proxy WAF can actually decide, Strict + body
inspection intercepts 96.6 % (616/638), with 0.06 % (19/33 219) of benign
traffic affected and 99.82 % accuracy. Of the 658 malicious samples, 20
never reach a detection surface and are excluded from that figure: 19 are
POST/PUT requests without Content-Length or Transfer-Encoding (an empty
body under RFC 7230), and 1 hides its payload in a URL fragment that the HTTP
parser strips before the request line is built. Every reverse-proxy WAF passes
those 20 by construction — counting them as misses understates detection.
| Tier | Attack interception (full corpus) | Benign affected | p95 |
|---|---|---|---|
| Normal (default, no body inspection) | 60.2 % | 0.01 % | 1 ms |
| Normal + body inspection | 71.9 % | 0.04 % | 1 ms |
| Strict | 76.0 % | 0.01 % | 1 ms |
| Strict + body inspection | 93.8 % | 0.06 % | 2 ms |
The full-corpus figure (93.8 %, 617/658) is kept for direct comparison with other measurements; the effective figure is given above.
Cross-vendor comparison
| Product / mode | Malicious | Interception | Benign | False positives | Accuracy |
|---|---|---|---|---|---|
| PingWAF 0.32.4 · Strict + body | 658 | 93.8 % (617) | 33 219 | 0.06 % (19) | 99.82 % |
| PingWAF 0.32.4 · Normal | 658 | 60.2 % (396) | 33 219 | 0.01 % (4) | 99.21 % |
| SafeLine free · strict | 575 | 76.17 % (438) | 33 094 | 0.22 % (73) | 99.38 % |
| SafeLine free · balanced | 575 | 71.65 % (412) | 33 094 | 0.07 % (23) | 99.45 % |
| ModSecurity PL4 | 575 | 94.61 % (544) | 33 094 | 52.46 % (17 362) | 48.34 % |
| ModSecurity PL1 | 575 | 69.74 % (401) | 33 094 | 17.58 % (5 819) | 82.20 % |
| Cloudflare free | 570 | 10.70 % (61) | 32 780 | 0.07 % (23) | 98.40 % |
The PingWAF rows are this project's own replay (effective interception 96.6 %, see above); the other rows are quoted from the blazehttp project README and were not re-run here. The two datasets are close but not identical (33 877 vs 33 669; 658 vs 570–575 malicious samples), and third-party latency includes public-network round trips while PingWAF's p95 is a loopback verdict latency — compare detection and false positives, not milliseconds.
Every figure is reproducible: the suite definitions, the replay harness and the
raw metrics live in tools/waf-bench/. The
test plan documents the methodology and the
test report the conclusions, per-category
tables, the cross-vendor comparison with Cloudflare / SafeLine / ModSecurity
(quoted from the blazehttp benchmark) and known limits.
🧱 Tech Stack
| Layer | Technology |
|---|---|
| Data plane / proxy | Rust · Pingora · pingap |
| Control plane API | Axum (REST) · tonic (gRPC) |
| Persistence | SeaORM · PostgreSQL 14+ (16 recommended) |
| Log storage | Elasticsearch (optional) |
| Dashboard | React 19 · Vite · Tailwind CSS v4 (embedded with rust-embed) |
| WAF engine | libinjection · Aho-Corasick · expression evaluator |
Core crates:
| Crate | Responsibility |
|---|---|
pingwaf-proto |
Control-plane gRPC protocol definitions (single source: control_plane.proto) |
pingwaf-server |
Control plane: Axum REST + tonic gRPC + SeaORM/PostgreSQL + ES logs + embedded frontend + agent health monitoring |
pingwaf-agent |
Data-plane agent: connects to the control plane, caches rules with disk persistence, ships logs/metrics, receives commands |
pingwaf-waf |
Detection engine: normalize → signatures → expression → anomaly score |
pingwaf-challenge |
Dynamic challenges: JS 5-second shield, interactive challenge, PoW, fingerprinting, HMAC clearance cookies |
pingwaf-profiler / pingwaf-system (no README) |
In-process CPU/memory attribution and snapshots served at /api/v1/system/profile and /api/v1/system/metrics |
🚀 Quick Start
Two typical paths: Docker Compose (one command, all-in-one mode with PostgreSQL; prebuilt binaries are published for Linux amd64/arm64 only — see the releases page), or build from source (Rust 1.96+, Node.js 26.12.1+, protoc).
# Path A — Docker Compose (recommended; no clone, no root)
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash
# …or, after cloning this repository:
docker compose up -d
# Path B — build from source
git clone https://github.com/shuaiZend/PingWAF.git && cd PingWAF
cd web && npm ci && npm run build && cd ..
cargo build --release --bin pingwaf --features full
./target/release/pingwaf all-in-one --db-url "postgres://pingwaf:pingwaf@localhost:5432/pingwaf"
Then open the dashboard at https://localhost:9080 (HTTPS with a self-signed certificate generated on first boot) and sign in with [email protected] / pingwaf123 — change the default password and PINGWAF_JWT_SECRET before any production use.
👉 Full install wizard, the interactive installer and TLS / port options: https://www.pingwaf.com/install/ · step-by-step guide: https://www.pingwaf.com/quickstart/ · in-repo walkthrough (database setup, first site, distributed agents, systemd): docs/quick-start.md.
🧭 Run Modes
PingWAF is a single binary (pingwaf) that shares its entry point with pingap. It selects a mode from the CLI subcommand or the PINGWAF_MODE environment variable.
| Mode | Command | Role |
|---|---|---|
| Control plane | pingwaf server |
REST API + gRPC server + dashboard + PostgreSQL. Does not proxy traffic. |
| Data plane | pingwaf agent |
Connects to a remote control plane, enforces rules, proxies traffic on :80/:443. |
| All-in-One | pingwaf all-in-one |
Both of the above in one process (agent talks to the local server over loopback). |
# Equivalent to `pingwaf all-in-one`
PINGWAF_MODE=all-in-one ./pingwaf
⚙️ Configuration
PingWAF is configured through a TOML file, PINGWAF_* environment variables, and CLI flags, in that order of precedence (a later channel overrides an earlier one).
pingwaf all-in-one --config /etc/pingwaf/pingwaf.toml
PINGWAF_CONFIG=/etc/pingwaf/pingwaf.toml pingwaf all-in-one # equivalent
ℹ️ The
pingwaf.tomlin the repository root is a working example — pass it with--configand its[server]/[agent]tables are applied (the process logspingwaf: loaded N setting(s)). Keys are the flag names with underscores (admin_addr,max_body_log_size); unknown keys are reported and skipped.
Key environment variables
| Variable | Default | Description |
|---|---|---|
PINGWAF_CONFIG |
— | Path to the TOML configuration file |
PINGWAF_MODE |
— | server, agent or all-in-one |
PINGWAF_DB_URL |
postgres://pingwaf:pingwaf@localhost:5432/pingwaf |
PostgreSQL DSN |
PINGWAF_ADMIN_ADDR |
0.0.0.0:9080 |
REST API + dashboard listen address |
PINGWAF_GRPC_ADDR |
0.0.0.0:9090 |
gRPC control-plane listen address |
PINGWAF_JWT_SECRET |
change-me-in-production |
JWT signing secret (≥ 16 chars, change in production) |
PINGWAF_ADMIN_EMAIL |
[email protected] |
Seeded administrator email |
PINGWAF_ADMIN_PASSWORD |
pingwaf123 |
Seeded administrator password (change in production) |
PINGWAF_ALLOW_REGISTRATION |
true |
Whether POST /api/v1/auth/register accepts signups (docker-compose.yml sets this to false) |
PINGWAF_HEARTBEAT_INTERVAL |
15 |
Heartbeat interval the control plane hands to agents at registration (seconds). The agent-side --heartbeat-interval-secs flag reads the same variable but falls back to 30, and only applies when the control plane hands nothing down |
PINGWAF_TLS_ENABLED |
true |
Serve the REST API + dashboard over HTTPS (self-signed until replaced); false behind a TLS-terminating proxy |
PINGWAF_TLS_SANS |
hostname, localhost, 127.0.0.1 |
Comma-separated SANs of the generated self-signed certificate |
PINGWAF_SERVER_URL |
http://localhost:9090 |
(agent) control-plane gRPC URL |
PINGWAF_API_KEY |
(empty) | (agent) API key; empty = auto-register over loopback |
PINGWAF_CACHE_DIR |
./data/cache |
(agent) local rule cache directory |
PINGWAF_ES_ENABLED |
false |
Enable Elasticsearch log shipping |
PINGWAF_ES_URLS |
(empty) | Comma-separated Elasticsearch URLs |
Default ports
| Port | Purpose |
|---|---|
9080 |
REST API + embedded dashboard over HTTPS (health: GET /healthz, answered on HTTP too); restrict to admin/VPN sources |
9090 |
gRPC control plane (agents connect here) |
80 / 443 |
Proxied traffic (bound once the first site exists; 443 opens only after a certificate is issued or uploaded — until then only port 80 serves HTTP) |
👉 Full configuration reference: docs/deployment.md and docs/api.md.
📚 Documentation
| Document | What you'll find |
|---|---|
| docs/quick-start.md | From zero to your first protected site |
| docs/deployment.md | Docker, binary + systemd, distributed topologies |
| docs/cli.md | Administrator binary CLI — run modes, break-glass maintenance commands, incident runbooks |
| docs/user-guide.md | Dashboard walkthrough, sites, rules, policies |
| docs/http-lifecycle.md | Where every feature acts in the request pipeline (WAF check order, caching, error pages) and how to debug with it |
| docs/e2e-test-plan.md | Product E2E test plan — scenarios, environments, execution tiers, defect and regression flow, release gates (incl. UI/UE, accessibility) |
| docs/waf-test-plan.md | WAF test plan — layers, blazehttp suite selection, calibres and acceptance gates |
| docs/waf-test-report.md | Measured WAF effectiveness (0.32.4) — interception, false positives, attribution, limits |
| docs/waf-benchmark-report.md | Per-round benchmark appendix (P0 → P14 iteration history) |
| docs/api.md | REST API reference (https://<host>:9080/api/v1) |
| docs/README.md | Full documentation index |
| CONTRIBUTING.md | How to contribute |
| SECURITY.md | Vulnerability disclosure policy |
| CODE_OF_CONDUCT.md | Community guidelines |
🤝 Contributing
Contributions are welcome! Please read CONTRIBUTING.md before opening a pull request, and SECURITY.md for how to responsibly report a vulnerability.
🙏 Acknowledgements
PingWAF stands on the shoulders of excellent open-source projects:
- pingap by Tree Xie — the reverse-proxy foundation (routing, plugins, ACME, caching, hot reload) that PingWAF's data plane is built on.
- Pingora by Cloudflare — the async networking framework that powers
pingap. - libinjection — SQLi/XSS detection heuristics used by the WAF engine.
PingWAF is a derivative work that adds the WAF control plane, data-plane agents and detection engine. It is distributed under the same Apache License 2.0 as its upstream dependencies, and the original pingap/Pingora copyright notices are preserved. PingWAF is not affiliated with or endorsed by Cloudflare or the pingap project.
📄 License
PingWAF is released under the Apache License 2.0.