fix(waf): fail closed when Coraza inspection fails

Author: bihius

configs/haproxy/README.md

@@ -78,13 +78,24 @@ Coraza needs to run request-phase rules:
 Response-phase inspection is deliberately out of scope for M1
 (see ADR-007).
 
-## Failure behaviour
+## Degraded-mode behaviour
 
 `spoe-agent` is configured with `option set-on-error error`. If the
-SPOA is unreachable or returns an error, `txn.coraza.action` will not
-equal `"deny"` and the request is forwarded — i.e. the proxy
-fail-opens. Hardening this into an explicit degraded mode is tracked
-in #80; M1 only needs the happy path.
+SPOA is unreachable, times out, returns a malformed response, or
+returns an internal processing error, HAProxy sets
+`txn.coraza.error` to the SPOE/SPOP error code.
+
+The M1 reference configuration fails closed for protected traffic:
+when `txn.coraza.error` is present, HAProxy returns
+`503 Service Unavailable` before contacting `be_app`. The response
+includes `X-WAF-Degraded: true` and `X-WAF-Error: <code>` so operators
+can distinguish WAF degraded mode from an application outage. HAProxy
+also raises the request log level to `err` for these requests.
+
+This covers startup or unhealthy Coraza containers, connection
+failures, SPOE processing timeouts, malformed WAF responses, and
+transient runtime failures. Backend/dashboard status reporting is
+tracked separately in #69.
 
 ## Troubleshooting SPOE frames
 
@@ -128,9 +139,10 @@ mode uses `info` logging.
 5. If HAProxy returns `421`, the request failed the reference host ACL
    before routing. Retry with `Host: app.local`.
 
-6. If HAProxy returns an application response while Coraza is down,
-   this is the expected M1 fail-open behavior from `option
-   set-on-error error`; degraded-mode handling is tracked in #80.
+6. If HAProxy returns `503` with `X-WAF-Degraded: true`, Coraza/SPOA
+   inspection failed and the proxy failed closed before contacting the
+   backend. Use the `X-WAF-Error` value and HAProxy `err` log line to
+   identify the SPOE/SPOP failure class.
 
 For raw frame inspection in the Docker Compose setup, capture the SPOA
 traffic from inside the `haproxy` container while reproducing the

configs/haproxy/coraza.cfg

@@ -18,8 +18,8 @@ spoe-agent coraza-agent
     option              var-prefix  coraza
 
     # If the SPOA is unreachable or replies with an error, mark the
-    # transaction as errored. haproxy.cfg currently fail-opens in
-    # that case; failure handling is tracked separately in #80.
+    # transaction as errored. haproxy.cfg fails closed with 503 when
+    # txn.coraza.error is present.
     option              set-on-error  error
 
     # SPOE handshake / idle / per-request timeouts. Keep processing

configs/haproxy/haproxy.cfg

@@ -46,8 +46,13 @@ frontend fe_http
     acl host_app hdr(host) -i app.local app.local:80 app.local:8080 localhost localhost:8080 127.0.0.1 127.0.0.1:8080
     http-request deny deny_status 421 if !host_app
 
-    # Coraza populates txn.coraza.* via the SPOE response. If the
-    # engine returns action=deny we stop the transaction with 403.
+    # Coraza populates txn.coraza.* via the SPOE response. If SPOE
+    # inspection fails, fail closed before the backend is contacted.
+    http-request set-log-level err if { var(txn.coraza.error) -m found }
+    http-request return status 503 content-type text/plain string "WAF inspection unavailable" hdr X-WAF-Degraded true hdr X-WAF-Error %[var(txn.coraza.error)] if { var(txn.coraza.error) -m found }
+
+    # If the engine explicitly returns action=deny we stop the
+    # transaction with 403.
     http-request deny deny_status 403 if { var(txn.coraza.action) -m str deny }
 
     # Optional: log the WAF anomaly score on allowed requests so it

src/backend/tests/unit/test_waf_debug_reference_config.py

@@ -44,7 +44,10 @@ def test_debug_coraza_spoa_config_enables_debug_logging() -> None:
 def test_debug_compose_override_enables_haproxy_debug_flag() -> None:
     compose = (REPO_ROOT / "deploy/docker/docker-compose.debug.yml").read_text()
 
-    assert 'command: ["haproxy", "-d", "-f", "/usr/local/etc/haproxy/haproxy.cfg"]' in compose
+    assert (
+        'command: ["haproxy", "-d", "-f", "/usr/local/etc/haproxy/haproxy.cfg"]'
+        in compose
+    )
 
 
 def test_debug_compose_override_mounts_debug_coraza_config() -> None:
@@ -68,3 +71,27 @@ def test_haproxy_readme_documents_spoe_troubleshooting() -> None:
     assert "make dev" in readme
     assert "X-Request-ID: spoe-debug-1" in readme
     assert "tcpdump -i any -A -s 0 port 9000" in readme
+
+
+def test_reference_haproxy_config_fails_closed_on_spoe_errors() -> None:
+    config = (REPO_ROOT / "configs/haproxy/haproxy.cfg").read_text()
+
+    assert "var(txn.coraza.error) -m found" in config
+    assert (
+        "http-request set-log-level err if { var(txn.coraza.error) -m found }"
+        in config
+    )
+    assert "http-request return status 503" in config
+    assert "X-WAF-Degraded true" in config
+    assert "X-WAF-Error %[var(txn.coraza.error)]" in config
+
+
+def test_haproxy_readme_documents_fail_closed_degraded_mode() -> None:
+    readme = (REPO_ROOT / "configs/haproxy/README.md").read_text()
+
+    assert "## Degraded-mode behaviour" in readme
+    assert "fails closed" in readme
+    assert "503 Service Unavailable" in readme
+    assert "X-WAF-Degraded: true" in readme
+    assert "tracked separately in #69" in readme
+    assert "fail-open" not in readme