docs: fix terminology — WAF URL is the firewall app, Return Port is traffic return to Zoraxy
This commit is contained in:
parent
3159f0ed84
commit
b67ea433c0
2 changed files with 26 additions and 40 deletions
58
README.md
58
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": "<first 4KB of request body>"
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -26,15 +26,15 @@
|
|||
</div>
|
||||
|
||||
<div class="field">
|
||||
<label for="waf-url">WAF Inspection URL</label>
|
||||
<label for="waf-url">WAF URL</label>
|
||||
<input type="text" id="waf-url" placeholder="http://127.0.0.1:8080">
|
||||
<small>The firewall service that inspects each request and returns a verdict.</small>
|
||||
<small>The firewall application URL (e.g. Wallarm, ModSecurity, Coraza).</small>
|
||||
</div>
|
||||
|
||||
<div class="field">
|
||||
<label for="return-port">Return Port (async callbacks)</label>
|
||||
<label for="return-port">Return Port</label>
|
||||
<input type="number" id="return-port" placeholder="8080" min="1" max="65535">
|
||||
<small>WAF sends async verdicts/alerts to this port.</small>
|
||||
<small>Traffic returns to Zoraxy on this port for routing to the backend.</small>
|
||||
</div>
|
||||
|
||||
<div class="field">
|
||||
|
|
|
|||
Loading…
Reference in a new issue