Skip to content
Projects

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.

How these counts are measured

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-hosted

README.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

License Rust CI Docker

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 pingap maintainers. See Acknowledgements.


🏗️ Architecture

PingWAF architecture: clients reach edge agents over HTTP/HTTPS; each agent streams rules and telemetry with the control plane over a gRPC bidirectional stream; only clean traffic continues to the origin

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 many agent processes 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 libinjection heuristics 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 503 maintenance 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 curl command 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

Interception on the blazehttp corpus: PingWAF 93.8 % full-corpus (96.6 % effective, 0.06 % false positives) against ModSecurity PL4 94.61 %, SafeLine 76.17 %, ModSecurity PL1 69.74 % and Cloudflare 10.70 %

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.toml in the repository root is a working example — pass it with --config and its [server] / [agent] tables are applied (the process logs pingwaf: 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.