From b67ea433c06423ee57ca75213ac0f5eef2a2086d Mon Sep 17 00:00:00 2001 From: cclohmar Date: Sun, 2 Aug 2026 07:21:57 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20fix=20terminology=20=E2=80=94=20WAF=20U?= =?UTF-8?q?RL=20is=20the=20firewall=20app,=20Return=20Port=20is=20traffic?= =?UTF-8?q?=20return=20to=20Zoraxy?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 58 +++++++++++++++++++------------------------------- web/index.html | 8 +++---- 2 files changed, 26 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 65b5789..eeeb377 100644 --- a/README.md +++ b/README.md @@ -27,64 +27,50 @@ Open the Firewall panel at `/plugin.ui/zoraxy-firewall/`: | Setting | Default | Description | |---------|---------|-------------| | **Enable** | Off | Toggle WAF inspection on/off | -| **WAF Inspection URL** | `http://127.0.0.1:8080` | Inspection endpoint — receives `POST /inspect` | -| **Return Port** | `8080` | Port for async WAF callbacks/alerts | -| **Health Interval** | `5s` | How often to ping the WAF | -| **Timeout** | `500ms` | Max wait time for a verdict | +| **WAF URL** | `http://127.0.0.1:8080` | The firewall application itself (e.g., Wallarm, ModSecurity, Coraza) | +| **Return Port** | `8080` | Port where inspected traffic returns to Zoraxy for routing | +| **Health Interval** | `5s` | How often to check if the WAF is reachable | +| **Timeout** | `500ms` | Max wait time for an inspection verdict | --- ## How It Works ``` -Client → Zoraxy - │ - ▼ - ┌──────────────────┐ - │ Firewall Plugin │──► POST http://waf:8080/inspect - │ (static capture) │ {method, url, headers, body_sample} - └────┬─────────────┘ - │ - ┌────┴────────────────────────────┐ - │ WAF returns 403 │ → 280 (BLOCK) → Request dropped - │ WAF returns 2xx │ → 284 (FORWARD) → Zoraxy routes to backend - │ WAF unreachable / breaker OPEN │ → 284 (FAIL-OPEN)→ Zoraxy routes to backend - └─────────────────────────────────┘ +Client → Zoraxy → Plugin → http://waf:8080 [Firewall App] → inspect + │ + ┌────┴──────────┐ + │ 403 → BLOCK │ + │ 2xx → RETURN │──→ Zoraxy (port 8080) → Backend + │ down → FAIL-OPEN│──→ Zoraxy routes directly + └───────────────┘ ``` +1. Zoraxy proxies traffic to the firewall application at the configured WAF URL +2. The firewall app inspects the request inline +3. If blocked (403), the plugin drops the request +4. If allowed (2xx), traffic returns to Zoraxy on the return port for routing to the final backend +5. If the firewall app is unreachable, the circuit breaker opens and traffic bypasses inspection (fail-open) + ### Circuit Breaker If the WAF fails 5 times within a 30-second window, the breaker opens. All traffic bypasses inspection (fail-open) for 10 seconds. After the cooldown, the next successful health check closes the breaker. ### Health Check -The plugin periodically sends a `HEAD` request to the WAF URL. If the WAF responds with < 500, the circuit breaker records success. If it fails or returns 5xx, it records a failure. +The plugin periodically sends a `HEAD` request to the WAF URL. If the firewall application responds, the circuit breaker records success. If unreachable, it records a failure. --- ## Inspection Protocol -The plugin sends this JSON payload to `{WAF_URL}/inspect`: +The plugin proxies the full HTTP request to the WAF URL. The firewall application inspects it inline and returns an HTTP status code: -```json -{ - "method": "GET", - "url": "/some/path", - "host": "example.com", - "remote_addr": "10.1.0.5:12345", - "content_type": "application/json", - "content_length": 256, - "headers": {...}, - "body_sample": "" -} -``` - -The WAF inspects and returns an HTTP status code: -- **200–299** → Request is clean, Zoraxy forwards to backend +- **200–299** → Traffic is clean, returned to Zoraxy for routing - **403** → Request is malicious, plugin blocks it -- **5xx / timeout** → Plugin fails open, records breaker failure +- **5xx / timeout** → Plugin fails open, breaker records failure -Any WAF that accepts a POST and returns the appropriate status code is compatible. No special Wallarm integration required. +Any firewall application that accepts proxied HTTP traffic and returns a status code is compatible. --- diff --git a/web/index.html b/web/index.html index 48443b7..dcff1bb 100644 --- a/web/index.html +++ b/web/index.html @@ -26,15 +26,15 @@
- + - The firewall service that inspects each request and returns a verdict. + The firewall application URL (e.g. Wallarm, ModSecurity, Coraza).
- + - WAF sends async verdicts/alerts to this port. + Traffic returns to Zoraxy on this port for routing to the backend.