v1.0.37 — CRS version management and safe rollback

This release delivers phase 1 of issue #32: exact CRS release selection, LTS 4.25.x patch recommendations, signed immutable bundles, explicit validation and activation, and retained rollback. One CRS bundle applies to all sites. Changing tracks never activates updates automatically.

Settings → OWASP Core Rule Set now supports snapshotting existing rules, preparing an official release, reviewing rule differences, validating against current site policies, and deliberately activating or rolling back. Policy, engine or active-selection changes invalidate stale validation. Local snapshots preserve existing bytes but are not labelled official signed releases.

Configuration writers share an early lock. Confirmed boot state and a durable per-write identity protect recovery, including certificate changes that leave Caddy JSON unchanged. Pending/corrupt boot state or damaged referenced bundles start Caddy admin-only. Ambiguous operations remain blocked until an operator stops old executors, restarts Caddy admin-only and reconciles the committed database state.

Images

Production images target linux/amd64:

• ghcr.io/socfortress/waf-caddy:1.0.37
• ghcr.io/socfortress/waf-admin-api:1.0.37
• ghcr.io/socfortress/waf-admin-ui:1.0.37

Caddy remains 2.11.4, coraza-caddy 2.6.2, and Coraza 3.8.1.

Set these values in the public deployment's .env:

WAF_IMAGE_TAG=1.0.37
CRS_CADDY_DIGEST=sha256:a58595ee1b03e4060011b6110e48454e55ff308c450fe308433c22b42be111be

The public Compose file uses that digest to pin both production Caddy and its validator and supplies the matching API declarations. Update the tag and digest together on future releases: a digest pin takes precedence over a tag. Leaving the digest blank disables managed CRS activation while preserving ordinary WAF operation. These declarations are deployment assertions, not runtime attestation.

Upgrade

Updating only the image tags is insufficient. Update the public Compose file too. This release adds the sensitive config-state volume, enables the confirmed-boot launcher, and requires a matching sandbox for managed CRS updates. Preserve your project name, existing volumes, custom bind mounts and TCP/UDP port overrides. Any custom CRS bind mount must also be mounted read-only in the sandbox.

1. Schedule a maintenance window and stop configuration edits. Back up PostgreSQL, deployment settings, CRS files, custom configuration/TLS files and existing persistent volumes. Keep a consistent pre-upgrade backup for platform rollback.
2. Update deployment files with git pull --ff-only, preserving local overrides. Set the tag and digest above in .env. Review docker compose config to verify both Caddy image references match and config-state is mounted read/write in the API and read-only in production Caddy. Do not publish sandbox or Caddy admin ports.
3. Pull and replace services in this order so Caddy is reachable before the API performs startup synchronization:

docker compose pull
docker compose stop admin-ui admin-api caddy-waf waf-sandbox
docker compose up -d --wait postgres redis http-echo caddy-waf waf-sandbox
docker compose up -d --wait admin-api admin-ui
docker compose ps

1. The API applies migration 0040_crs_management, adding metadata without replacing the active rules. Confirm API startup synchronization succeeds and existing sites still work. In Settings, confirm runtime status before attempting a CRS change.
2. Choose Snapshot existing rules, validate, and explicitly activate that equivalent baseline before preparing an upgrade. Then select an exact official release, validate, review changes and activate. Rollback selects a retained bundle and validates it against current policies; it does not revert site edits.

Customized or unidentified legacy setup files and external file dependencies require manual migration before a managed upgrade. Keep the original installation until those settings have been mapped to supported controls. See the CRS management and recovery guide.

The old /api/v1/settings/crs/update endpoint now returns HTTP 410. Use the prepare/validate/activate flow.

Validation

• Independent implementation review completed; all five findings were fixed and re-reviewed with no remaining blocking findings.

• 546 backend tests and 94 frontend tests passed; the frontend production build passed with its existing bundle-size warning.

• Real Caddy/PostgreSQL integration covered signed official CRS verification, tampered archive rejection, adoption, validation, upgrade, retained rollback, idempotency, rejected activation, commit/publication failures, unchanged-JSON file recovery, concurrent writers and altered-bundle rejection.

• Retained-volume first boot, confirmed restart, pending/corrupt startup, and migration up/down/up checks passed.

• All three production images built and published successfully. Anonymous registry checks confirm version 1.0.37, merged source revision e8c799b91e68a9063a82d973cefabc50b3b7fd94, linux/amd64, and matching latest/1.0 aliases. Image digests and publication evidence.

• The published API, UI and Caddy images passed an isolated Compose smoke test: initial boot, shared-volume permissions across actual service users, signed CRS activation, benign/attack traffic and independent confirmed Caddy restart with the API stopped. Helpers used native database/cache images and a synthetic Python upstream to accommodate local emulation. This was not a lab deployment.

Recovery and rollback

For an interrupted configuration write, follow the operator recovery procedure in the guide. Stop all old API executors and Caddy, set CONFIG_RECOVERY_ONLY=true in .env and recreate Caddy, start a fresh API, and reconcile through /api/v1/settings/crs/recover only after confirming the previous executors have stopped. Remove the temporary override after successful recovery. Recovery can cause downtime; do not delete the pending marker or resume provisional autosave.

For a CRS-only rollback, use the retained-bundle workflow in Settings. For a platform rollback to v1.0.36, stop all platform writers and restore the consistent pre-upgrade database, CRS/custom/TLS volumes and deployment configuration. Restore all matching v1.0.36 images and startup behavior. Do not merely downgrade images against a database/configuration already managed by v1.0.37. Restoring a backup discards later changes, so retain a current backup for investigation first.

This phase supports single-host Compose. Plugins, per-site CRS selection and simultaneous production/shadow CRS evaluation remain deferred; issue #32 remains open for that broader scope. No lab or production deployment is performed by publishing this release.