# Firewall

**Zoraxy plugin** — Inline WAF inspection proxy with health checks, circuit breaker, and fail-open bypass. Works with Wallarm, ModSecurity, Coraza, or any inspection service that returns HTTP status codes.

---

## Quick Install

The plugin is built into Zoraxy — just enable it from the Plugins panel. If you need to build from source:

```bash
git clone https://git.lohmar.co.uk/cclohmar/zoraxy-waf.git /opt/zoraxy/plugins/zoraxy-waf
cd /opt/zoraxy/plugins/zoraxy-waf
go build -buildvcs=false -o zoraxy-waf .
chown -R zoraxy:zoraxy /opt/zoraxy/plugins/zoraxy-waf
systemctl restart zoraxy
```

Then enable **Firewall** in Zoraxy → Plugins.

---

## Configuration

Open the Firewall panel at `/plugin.ui/zoraxy-firewall/`:

| Setting | Default | Description |
|---------|---------|-------------|
| **Enable** | Off | Toggle WAF inspection on/off |
| **WAF URL** | `http://127.0.0.1:8080` | The firewall application itself (e.g., Wallarm, ModSecurity, Coraza) |
| **Return Port** | `8081` | Port where inspected traffic returns to Zoraxy for routing |
| **Health Interval** | `5s` | How often to check if the WAF is reachable |
| **Timeout** | `10000ms` | Max wait time for an inspection verdict |

---

## How It Works

```
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. Any HTTP response (regardless of status code) means the WAF is reachable — the circuit breaker records success. Only connection errors (timeout, connection refused) trigger failures.

---

## Inspection Protocol

The plugin proxies the full HTTP request to the WAF URL. The firewall application inspects it inline and returns an HTTP status code:

- **200–299** → Traffic is clean, returned to Zoraxy for routing
- **403** → Request is malicious, plugin blocks it
- **302** → Redirects are preserved (e.g. login session cookies) — the plugin does not follow redirects
- **5xx / timeout** → Plugin fails open, breaker records failure

All HTTP response headers and status codes are passed through transparently. Redirects and `Set-Cookie` headers are preserved end-to-end.

---

## Zoraxy Integration

To activate the plugin for specific proxy rules:

1. Zoraxy → Plugins → enable **Firewall**
2. Create a plugin group (e.g., "waf") → add the Firewall plugin
3. Edit proxy rules → add the "waf" tag

The plugin uses Zoraxy's **static capture** to intercept all requests matched by tagged proxy rules.

---

## API Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/ui/api/config` | Get current configuration |
| `POST` | `/ui/api/config/save` | Save configuration |
| `GET` | `/ui/api/stats` | Metrics (total/allowed/blocked/bypassed) + circuit state + enabled flag |
| `POST` | `/inspect` | Static capture — Zoraxy sends traffic here |
| `POST` | `/verdict` | Return port — WAF sends async callbacks here |

---

## Architecture

```
/opt/zoraxy/plugins/zoraxy-waf/
├── zoraxy-waf              # Compiled plugin binary
├── waf_config.json          # Runtime configuration (auto-created)
├── config.go                # Config load/save (thread-safe)
├── main.go                  # Plugin entry, UI router, return listener
├── middleware.go             # Inspection handler, WAF proxy, metrics
├── hosts.go                 # Backend resolution from Zoraxy proxy configs
├── circuit_breaker.go       # Fail-open state machine
├── health.go                # Background health check goroutine
├── web/                     # Config panel UI — WAF status indicator
│   ├── index.html
│   ├── style.css
│   └── app.js
└── zoraxy_plugin/           # Vendored Zoraxy plugin SDK (LGPL)
```

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| *none* | — | All config is managed through the UI and persisted to `waf_config.json` |

---

## License

Zoraxy plugin SDK is LGPL. This plugin is open source.

---

## Credits

- [Zoraxy](https://github.com/tobychui/zoraxy) — Reverse proxy and plugin system
- Compatible with any WAF that returns HTTP verdicts (Wallarm, ModSecurity, Coraza, custom)