[bihius]

Closes #312
Closes #316

Stacked on fix/321-hardening. This branch already contains the #321 merge commit, so the diff below is only #312/#316. Retarget the base to main once #321 merges; no rebase should be needed.

What changed

#312 — a tag-only upgrade is now loud instead of silently wrong

The release kit bind-mounts haproxy/coraza.cfg into HAProxy and the backend. Bumping only GUARD_PROXY_IMAGE_TAG therefore runs a new image against a pre-beta.5 file that sends app=str(default): every request is inspected by the default Coraza application instead of its vhost's policy_<id>, with no error anywhere (verified in the issue with real stacks).

• All four shipped configs (configs/haproxy/, release/haproxy/, both files) carry # guard-proxy-config-version: 1. The generated haproxy.cfg template emits the same stamp from EXPECTED_CONFIG_VERSION, so the seed file still equals the rendered reference modulo whitespace.
• check_seed_config() reads the mounted coraza.cfg at settings.seed_coraza_config_path (default /usr/local/etc/haproxy/coraza.cfg) and compares the stamp. A missing file is skipped, so local runs and pytest are unaffected; a stale one is a failure.
• Check surfaces:
  • startup — one ERROR log naming the file;
  • GET /health — 200 with status: degraded and the stale path in detail;
  • GET /ready — the seed_config check fails, so the release kit's backend healthcheck fails; the body stays generic per Lower-severity hardening: write-time validation, log isolation, CORS, /ready detail #321's rule and the path goes to the server log;
  • POST /config/apply — 409 naming the file, before anything is written or reloaded;
  • GET /runtime/status — active_config.degraded plus warning naming the file (rendered by the existing admin-UI alert).

#316 — the CRS version comes from one place

• app/constants/versions.py holds CRS_VERSION; crs-setup.conf.j2 takes ver:'OWASP_CRS/{{ crs_version }}' and the derived tx.crs_setup_version instead of hardcoded 4.25.0 / 4250. A test asserts the constant matches the configs/coraza/crs submodule's crs-setup.conf.example header, so bumping the submodule alone now fails a test. configs/coraza/crs-setup.conf stays the checked reference — the existing baseline test keeps it in sync.
• GET /runtime/status gains version_agreement: app_version, configured_image_tag (from GUARD_PROXY_IMAGE_TAG, mapped v0.1.0-beta.10 → 0.1.0b10), crs_version, and a warning when the tag and the backend's own version disagree.
• APP_VERSION moved to app/version.py (the status service needs it; importing it from app.main would be circular).

Fail-closed consequence

A stale stamp makes /ready fail, so frontend, haproxy, coraza and log-shipper (all depends_on: backend: service_healthy) do not start until the haproxy/ files from the same release are in place. That is the intended "refuses to report healthy" behaviour from #312; the backend log names the file, and the admin UI surfaces it on an already-running stack. Documented in release/README.md ("Upgrading", "A tag-only upgrade is refused") and docs/architecture.md.

Tests

cd src/backend && uv run ruff check app/ tests/ && uv run mypy app/ && uv run pytest -q

• ruff: pass
• mypy: pass (77 files)
• pytest: 933 passed, 6 skipped, 4 deselected

New coverage: stale/older/newer/missing-stamp detection and all four shipped configs passing; /health degraded vs healthy; /ready 503 with a generic body, no path in the body, path in caplog; /config/apply 409 and 200; /runtime/status version_agreement and stale-seed warning; tag→PEP 440 mapping and skew warning; rendered CRS metadata using CRS_VERSION and matching the submodule.

Skipped

• Synthetic post-apply probe per active vhost (optional item in Detect a half-done upgrade: stale coraza.cfg/haproxy.cfg with a new image tag #312).
• Coraza base-image pin, explicitly out of scope in Version agreement is never checked (CRS version hardcoded, image tag vs pyproject vs /health) #316.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.