feat(debug): make HAProxy and Coraza SPOE troubleshooting more verbose

[bihius]

Summary

• Change HAProxy and Coraza SPOA logging to debug for the M1 WAF path.
• Run HAProxy in Docker Compose with the -d debug flag.
• Document SPOE troubleshooting and request correlation steps.
• Add regression tests for the WAF debug reference config.

Closes #12

Validation

• uv run pytest --cov=app
• uv run mypy app/
• uv run ruff check app/ tests/unit/test_waf_debug_reference_config.py
• pnpm run type-check
• pnpm run lint
• docker run --rm -v "$PWD/configs/haproxy:/usr/local/etc/haproxy:ro" haproxy:3.0-alpine haproxy -c -f /usr/local/etc/haproxy/haproxy.cfg

[Copilot]

Pull request overview

This PR makes the M1 reference WAF (HAProxy ↔ Coraza SPOA via SPOE) easier to troubleshoot by increasing verbosity, running HAProxy in debug mode in the Docker Compose stack, and documenting request correlation and frame inspection steps. It also adds a unit test to prevent accidental regressions in the “debug reference” configuration.

Changes:

• Switch HAProxy and Coraza SPOA logging to debug in the reference configs.
• Run HAProxy in Docker Compose with the -d debug flag.
• Document SPOE troubleshooting steps and add a regression test that asserts the debug-oriented reference config/docs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/backend/tests/unit/test_waf_debug_reference_config.py	Adds regression checks for debug logging/config and troubleshooting docs.
deploy/docker/docker-compose.yml	Forces HAProxy to run with -d in the compose stack.
configs/haproxy/haproxy.cfg	Raises HAProxy global log level from info → debug.
configs/haproxy/README.md	Adds a troubleshooting section with correlation + frame-capture guidance.
configs/coraza/coraza-spoa.yaml	Raises Coraza SPOA log level from info → debug.

[Copilot]

This section uses docker compose ... while later in the same README the validation steps use docker-compose .... Mixing both can confuse users and may fail on systems that only have one of them installed. Consider standardising on one form throughout the document (preferably docker compose) and updating the other occurrences to match.

[bihius]

@copilot apply changes based on this feedback
Let's go with docker-compose

[Copilot]

Done in 185711b. All docker compose occurrences in configs/haproxy/README.md are now standardised to docker-compose. Also fixed a bug where _find_repo_root was matching the pyproject.toml in src/backend instead of the repo root — it now uses only .git as the marker, which exists only at the repo root. The test assertions for docker-compose and tcpdump -i any were updated to match.

[Copilot]

Running HAProxy with the -d debug flag is very noisy and can have operational/security implications (high-volume logs and potentially sensitive request metadata ending up in container logs). Consider making debug mode opt-in (e.g. a docker-compose.debug.yml override or an env-var controlled command) rather than always enabled in the default Compose stack.

Suggested change

	command: ["haproxy", "-d", "-f", "/usr/local/etc/haproxy/haproxy.cfg"]
	command: ["haproxy", "-f", "/usr/local/etc/haproxy/haproxy.cfg"]

[bihius]

@copilot you are right, let's make this debug mode as optionable - maybe another make option? maybe let's make something like this: make run runs the project, make dev runs the project with haproxy with debug log mode.

[bihius]

@copilot and according to my previous comment - this also about coraza. coaraza debug mode should be also optionable.

[Copilot]

Done in 2c36eef. Debug mode is now opt-in:

• make run — starts the stack normally (info logging, no -d flag)
• make dev — starts the stack with deploy/docker/docker-compose.debug.yml overlaid, which adds -d to the HAProxy command and mounts configs/coraza/coraza-spoa.debug.yaml (both HAProxy and Coraza SPOA at debug level)

The default haproxy.cfg and coraza-spoa.yaml both revert to info level. A warning in configs/haproxy/README.md notes that debug mode should only be used for local troubleshooting.

[Copilot]

Switching the global log level to debug will greatly increase log volume and may capture sensitive request metadata depending on log configuration. Consider keeping info as the default reference config and documenting/providing a separate debug variant (or a toggle) for troubleshooting.

Suggested change

	log stdout format raw local0 debug
	log stdout format raw local0 info

[Copilot]

Setting Coraza SPOA log_level: debug by default can generate very verbose logs and may include sensitive request details, which is risky if this stack is run against real traffic. Consider making debug logging opt-in (separate compose override / config variant) or adding a prominent warning in the docs about using it only for local troubleshooting.

[bihius]

@copilot you are right, coraza dev should be also optionable

[Copilot]

Already done in 2c36eef. configs/coraza/coraza-spoa.yaml (default) uses log_level: info; configs/coraza/coraza-spoa.debug.yaml uses log_level: debug and is only mounted by deploy/docker/docker-compose.debug.yml, which is applied exclusively when running make dev.