Architecture & Working Principles
Understand the division of labor between the Data Plane and asynchronous ALAP review, the out-of-band analysis model, and single-binary packaging.
CheeseWAF
Commercial-grade self-hosted Web Application Firewall. Complete documentation for deployment, security policies, configuration, and operations.
CheeseWAF is a commercial-grade self-hosted Web Application Firewall (WAF) distributed as a single Go core binary. The system utilizes a decoupled dual-plane architecture with an embedded lightweight persistent store for management state and supports external PostgreSQL as an asynchronous access-log sink.
Architecturally, CheeseWAF separates the Data Plane request forwarding path from the Management Plane and the asynchronous ALAP review pipeline. The cheesewaf process orchestrates both planes concurrently: the Data Plane executes bounded, low-latency synchronous inspection and reverse proxying, while the Management Plane hosts the management API, Web console, and background review workers—ensuring synchronous HTTP request paths are never blocked by remote LLM inference.
Official releases are available on GitHub Releases. The project is open-source under the Apache License 2.0.
Why CheeseWAF
Modern Web security solutions usually force teams into painful tradeoffs:
- Traditional Regex WAFs (e.g., ModSecurity / CRS): Maintaining thousands of regular expressions is tedious. Attackers bypass signatures using character case variations, malformed encodings, or SQL comments. False positives are frequent, forcing operators to constantly tune exception lists.
- Synchronous LLM WAFs: Routing every HTTP request to an LLM adds 500 ms to 2 s of latency to each response, burns API token budgets, and risks full outages whenever external endpoints experience latency spikes.
- Heavy Container Stacks (e.g., SafeLine / 雷池): Requiring 5 to 10 Docker containers (Tengine, Postgres, Redis, management daemons) consuming 1 to 2 GB+ of RAM, which quickly overburdens budget cloud instances and small VPSs.
- Commercial Cloud WAFs (e.g., Cloudflare / Cloud Provider WAFs): All traffic must route through third-party infrastructure, raising privacy, data residency, and compliance concerns. Bandwidth billing is unpredictable, and air-gapped operation is impossible.
CheeseWAF takes a balanced approach: an in-process AST semantic parser provides sub-millisecond inline blocking, while an out-of-band LLM auto-pilot (ALAP) reviews ambiguous samples in the background and synthesizes persistent custom rules without adding latency to live requests.
Comparison Overview
| Dimension | Regex WAF (e.g., ModSecurity) | Synchronous LLM WAF | Heavy Container Stack | Commercial Cloud WAF | CheeseWAF |
|---|---|---|---|---|---|
| Detection Engine | Regex pattern matching | Synchronous LLM per request | Regex + statistical analysis | Signature sets + threat feed | AST syntax analysis + Async LLM Auto-Pilot (ALAP) |
| Inline Latency Added | 1–10 ms | 500–2000 ms (high) | 2–15 ms | Dependent on CDN routing | < 1 ms (sub-millisecond, zero model wait) |
| API / Token Cost | None | Extremely high (all traffic) | None | Bandwidth & tier billing | Low (reviews only ambiguous samples out-of-band) |
| Evasion & False Positives | Easily bypassed by encodings | Prone to hallucinations | Complex rule maintenance | Vendor-dependent updates | Parses syntax trees; immune to obfuscation; FPR < 0.8% |
| Footprint & Deployment | Requires custom Nginx build | External API dependency | 5–10 containers, 1–2 GB+ RAM | Cloud-only | Single binary / single container, embedded SQLite, tens of MB RAM |
| Architectural Disruption | Bound to web server | Modifies primary traffic path | Replaces primary gateway | DNS / reverse proxy takeover | Runs as standalone reverse proxy or sidecar via adapterd |
| Data Privacy & Compliance | Local | Full traffic sent to external API | Local | Traffic traverses public cloud | 100% on-premises; optional private self-hosted LLM |
| Air-gapped Environments | Supported | Not supported (requires cloud API) | Partially supported | Not supported | Fully supported with offline Ed25519 CRP verification |
Core Mechanisms
- High-Performance Data Plane Inspection: Incoming requests undergo multi-layer recursive decoding before entering the Abstract Syntax Tree (AST) semantic engine. Identified SQL injection, Cross-Site Scripting (XSS), Remote Code Execution (RCE), and malicious payloads are blocked in sub-millisecond to microsecond timeframes.
- Asynchronous ALAP Threat Review: After the client receives its response, ambiguous samples or payloads embedded in large text blocks are enqueued into a background review pipeline. Configured LLMs (compatible with the OpenAI Response / Chat Completions APIs and Anthropic Messages API) perform in-depth semantic reasoning.
- Closed-Loop Rule Synthesis: Samples evaluated as high (
high) or critical (critical) threats can be approved manually or via auto-agreement. Site-level auto-agreement persists a site-scoped custom payload rule; global IP denylists and client soft-fingerprint actions remain explicit operator decisions.
Default Network Listeners
CheeseWAF exposes services on the following default listener endpoints:
| Plane / Service | Default Address | Description |
|---|---|---|
| Data Plane | http://127.0.0.1:8080 | Ingests business traffic, performs synchronous security inspection, and proxies upstream |
| Management Plane | https://PUBLIC_IP:9443/setup → https://PUBLIC_IP:9443/SECURITY_ENTRY | Initialization uses fixed /setup with a one-time token; after setup, the symbol-free security entry signs a Cookie and redirects to login |
| Cluster Plane | https://127.0.0.1:9444 | Optional TLS/mTLS interconnect when cluster.enabled: true; it handles node identity, health/heartbeat, topology, and orchestration hooks but is not a general site/policy replication channel |
| Local Controller | http://127.0.0.1:17943 | Local loopback auxiliary controller port for Windows and macOS desktop environments |
Documentation Roadmap
Deployment & Installation
Comprehensive deployment guides and installation options for CheeseWAF across Linux, Docker, Windows, and macOS.
Quick Start Guide
Three steps to complete initial system setup, onboard your first reverse proxy site, and configure asynchronous LLM threat review.
Core Concepts
In-depth exploration of the request processing lifecycle, paranoia level evaluation, payload isolation mechanisms, and unified access control.
Site Management & Reverse Proxy
Configure host domains, upstream load balancing algorithms (round_robin/weighted/ip_hash/least_conn), active health checks, and per-site protection policies.
Gateway Adapters
Go-first self-hosted gateway adapters for NGINX, Envoy, and Kubernetes, decoupling protocol translation from the core detection engine.
Security Protection Policies
Complete guide to the AST semantic engine, custom regex rules, IP/GeoIP filtering, bot challenges, sharded sliding-window counter rate limits, ACLs, and block pages.
API Security & Governance
Automated API asset discovery, request schema structure validation, JWT/JWKS authentication, route-level rate limiting, and RBAC policies.
Edge Optimization: Headers, Caching & Compression
Edge HTTP header rewriting, static resource proxy caching, and Brotli/Gzip response payload compression.
TLS & Certificate Management
Management plane TLS encryption, business site HTTPS certificate configuration, ACME automated issuance, HTTP/3, and HSTS policies.
ALAP Asynchronous Review & Self-Learning
Asynchronous LLM threat review queue, automated rule adoption with fail-closed guarantees, AI assistant tool approvals, and self-learning analytics.
Plugins & CRP Specification
CheeseSec plugin distribution model, CRP v1 offline resource package format, Ed25519 signature verification, staging lifecycle, and extension boundaries.
Observability, Logging & Threat Attack Map
Access log rotation, Prometheus metrics and Remote Write protobuf streaming, alerts, and 100% offline air-gapped threat attack maps.
High Availability & Cluster Federation
Node join tokens, mutual TLS (mTLS) health and heartbeat interconnects, external consensus coordination, Ansible orchestration, and CLI cluster management.
Commercial Platform Architecture
CheeseWAF control plane, data plane, plugins, CRP, offline mode, diagnostics, and recovery boundaries.
Storage & Scheduler Architecture
Embedded SQLite management storage, optional external log sinks, encrypted diagnostics, and scheduler maintenance.
Web Management Console
Modern React-based single-page management console navigation, module routing matrix, and security mechanisms.
Standalone Control Runtime
Command-line boundary, startup checks, local status endpoints, and current limits of the standalone cheesewaf-control process.
Command-Line Interface & Interactive TUI
Unified single-binary CLI distribution for cheesewaf and waf-cli, global flags, subcommand reference, and terminal UI operations.
RESTful Management API Reference
Management API authentication mechanics, public and bootstrap endpoint inventory, granular RBAC permission matrix, and standard error formats.
Configuration File Reference
Complete structure navigation for cheesewaf.yaml, top-level key index, timeout controls, and hot-reload scopes.
Operations & Security Hardening
User administration, TOTP two-factor authentication (2FA), NTP time synchronization, update capability status, and supply chain signature verification.
Building from Source & Developer Guide
Go and Node.js toolchain requirements, compiling frontend and backend assets, running automated test suites, and regression testing with attack corpora.
Open-Source License & Ecosystem Repositories
Apache License 2.0 open-source licensing terms, trademark usage notice, and ecosystem repository directory.
Feedback & Security Reporting
Communication channels and procedures for issue reporting, feature suggestions, and critical security disclosures.
Words from the Developer
Design motivations, engineering philosophy, and personal reflections from the creator and core developer of CheeseWAF.