---
title: Coraza WAF rules
description: Tune the Coraza web-application firewall rules running in front of your sites — toggle modes, mute false positives, audit blocks.
sidebar:
  order: 3
  badge:
    text: Draft
    variant: caution
---

import { Aside } from '@astrojs/starlight/components';
import SuperAdmin from '~/content/partials/super-admin-callout.mdx';
import Draft from '~/content/partials/draft-callout.mdx';
import SignIn from '~/content/partials/signing-in.mdx';
import Support from '~/content/partials/support-link.mdx';

<SuperAdmin />

<Draft />

[Coraza](https://coraza.io/) is an open-source web-application firewall (WAF). It runs as a sidecar in front of your sites and inspects incoming requests against rule families like OWASP Core Rule Set v4 (CRS). The admin WHP gives you a UI to manage the rules and audit what's been blocked.

## Three operating modes

The WAF runs in one of three modes, set per-site or server-wide:

- **Off.** No inspection. Requests pass through untouched.
- **Detect-only.** Inspect every request and log matches, but pass them through. Use this when rolling out the WAF for the first time or when validating a rule change.
- **Enforce.** Inspect every request and **block** any that match an enforcing rule. This is the production setting once you've validated detect-only.

The WAF is fail-open: if the Coraza sidecar itself is unhealthy, traffic still flows.

## Sign in to WHP

<SignIn />

## Where it lives

Sidebar → **Security → Coraza Rules**. The page lists rule families (CRS 901, 911, 913, 920–922, 930–934, 941–944, 949, 950–956, 959, 980) and per-rule controls.

## Common tasks

### Roll a new site onto the WAF

<Aside type="tip">
  Always start in **Detect-only** for a new site. Move to **Enforce** only after you've watched the logs and confirmed no legitimate traffic is being matched.
</Aside>

1. Open **Security → Coraza Rules**.
2. Find the site and set mode to **Detect-only**.
3. Drive normal traffic for at least 24 hours.
4. Open the **Audit log** and filter to that site. Confirm no legitimate request is matching an enforcing rule.
5. Switch the site to **Enforce**.

### Mute a noisy rule

When a rule is firing on legitimate traffic for one site:

1. Click the audit-log row to see the rule_id and the matched request.
2. From the **Coraza Rules** page, find the rule by ID.
3. Pick **Ignore for this site** (per-site mute) or **Ignore globally** (server-wide mute).
4. Save. The rule stops firing on the next request.

Per-site is almost always the right scope. Use global mute sparingly — it weakens the WAF for every site.

### Audit a block

Customer reports a request was wrongly blocked? The branded 403 page that visitors see includes an **X-Request-Reference** UUID. Cross-reference it:

1. In the **Audit log**, search for the UUID.
2. The audit row shows the matched rule_id, the source IP, the URL, and the offending parameter.
3. Decide whether to mute the rule (see above) or leave it — many "false positives" turn out to be real attempts.

## Things to know

- **Rule changes apply on the next request.** No service restart needed for tuning.
- **Adding or removing rules requires a full reload** of `coraza-spoa`, not just a SIGHUP. The panel handles this for you; if you edit rule files by hand, `docker restart coraza-spoa`.
- **Real source IPs are in the audit log.** Even though haproxy fronts the WAF, we propagate the real client IP through the SPOE messages.
- **`SecRuleRemoveById` plus a new rule needs a full restart**, not just a config reload. Again, the panel handles this when you change rules through the UI.

## Troubleshooting

**A rule shows enabled but doesn't fire.** Check that the site is in **Detect-only** or **Enforce** mode. A site in **Off** mode bypasses every rule, including enabled ones.

**The audit log is empty.** Confirm `coraza-spoa` is healthy on the **Services** page. If it's restarting in a loop, check the container logs — most often a malformed rule file or a missing include.

**Edits revert on restart.** Make sure you're editing through the panel; manual edits to files outside the panel-managed path are overwritten by config regeneration.

## Related

- [Server settings & services](/whp/admin/server-settings/)
- [Site Monitoring rules](/whp/admin/site-monitoring/)

## Still stuck?

<Support />
