Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Integrations › ModSecurity

ModSecurity

ModSecurity observation

Status: SUPPORTED as observation + optional auto-block thresholds — not a bundled WAF engineAudience: hosting / security engineer

What it does

Manager accepts ModSecurity audit alerts over a signed webhook (POST /api/v1/modsecurity/webhook) and stores ModSecurityAlert rows. Operators can list alerts/stats and manage rule overrides. Hosting Agent source hosting.modsecurity.global.metadata.v1 collects global metadata only, not full audit payloads.

Edition

Webhook/API: SHARED handlers. Hosting collector: ENTERPRISE. HTTP group is present when the handler is non-nil.

Prerequisites

  • ModSecurity (or compatible) emitting JSON alerts to the webhook
  • Shared HMAC secret
  • Admin JWT for list/override APIs
  • security.modsecurity.enabled: true

Required permissions / credentials

  • security.modsecurity.webhook_secret (secret)
  • Network path from the web server to the Manager API
  • Optional Hosting ACL to read /var/log/modsec_audit.log

Configuration

security.modsecurity.*: enabled, webhook_secret, auto_block, deduplication_window, whitelist, notify_on_block, severity_thresholds (failure_threshold, time_window, block_duration, action = block/log/alert/ignore).

Hosting: source id hosting.modsecurity.global.metadata.v1.

Setup

  1. Set enabled: true and a webhook secret via systemd credentials.
  2. Restart Manager.
  3. Configure the HTTP front-end to POST alerts with header X-ModSecurity-Signature (or X-Hub-Signature-256) over HMAC of the raw body.
  4. Confirm GET /api/v1/security/modsecurity/stats as admin.

Verification

  • Webhook returns {"success":true,"message":"Alert received and processed"}
  • Invalid signature → 401 Invalid signature
  • Disabled service → 503 SERVICE_NOT_CONFIGURED (ModSecurity service is not enabled. Please enable it in manager.yml configuration.)
  • Alerts appear in GET /api/v1/security/modsecurity/alerts

Expected signals / results

Alert rows with rule_id, client_ip, severity, blocked. Overrides change Manager-side handling of a CRS rule id. Hosting events stay category-safe.

Failure modes

Scroll sideways to see the full table. Use the arrow keys when focused.

StatusMeaning
401bad HMAC
400body unreadable
500process alert failed
503not enabled

Troubleshooting

  • Compare clocks only if your sender adds timestamps (HMAC is body-based)
  • Confirm Content-Type JSON
  • Hosting: permission_blocked until log ACL exists

Security considerations

Webhook is unauthenticated except HMAC — treat the secret like an Agent token. Do not expose the path to the internet without additional edge controls. Hosting metadata must not include raw request bodies.

Limitations

  • Zwall does not ship ModSecurity rulesets
  • Not a reverse-proxy WAF product
  • Hosting collector is global metadata only