Skip to content

Add custom WAF rules

In cPFence v4+, WAF whitelist rules in Edit Configuration Files holds your own WAF exceptions and rules. For the usual cases, such as one rule for one domain, WAF off for a domain, or Layer7, bot or CAPTCHA protection, use WAF rule and domain controls instead. They write the correct lines for you.

POST body inspection checks form data, not only the URL, query string, headers and cookies.

Web server POST body inspection
Nginx On by default. Nothing to do.
LiteSpeed Enterprise On by default. Nothing to do.
Apache Off by default. Turn it on with the line below.
OpenLiteSpeed Off by default. Turn it on with the line below.

On OpenLiteSpeed, JSON request bodies are not checked, only form fields.

In the WebUI:

  1. Open Edit Configuration Files and choose the server in Server scope.
  2. Select WAF whitelist rules.
  3. Add SecRequestBodyAccess On on its own line and select Save changes. When WAF is on, it is applied at once.

Or over SSH, on each server:

Terminal window
echo 'SecRequestBodyAccess On' >> /etc/cpfcli/waf/overrides.conf

cPFence applies the file within five minutes. Repeat on each server where you want body inspection; it covers every site on that server.

While body inspection is on, Apache, OpenLiteSpeed and Nginx limit what they inspect, so large or crafted posts cannot tie up the web server:

  • Request bodies over 1 MB that are not file uploads (large forms, JSON or WebDAV requests) are refused with error 413.
  • In an upload form, the form fields other than the files are limited to 1 MB (error 413). File uploads up to 1 GB are still accepted.

Requests with 1,000 or more arguments (form fields and query string parameters together) are refused with error 403, even when body inspection is off.

LiteSpeed Enterprise inspects POST bodies with its own engine and its own limits.

Why it is off by default on Apache and OpenLiteSpeed

Section titled “Why it is off by default on Apache and OpenLiteSpeed”

Request body inspection works differently on each web server, and so does its cost. On Apache and OpenLiteSpeed, checking every POST body uses noticeably more memory and CPU, so cPFence leaves it off by default, as cPFence v3 did. Nginx and LiteSpeed Enterprise check POST bodies by default.

POST bodies also carry content that can look like an attack: page-builder and CMS editor saves, HTML in contact forms, code snippets or long text fields. These can be blocked by mistake (false positives). If you turn it on, test your important forms, admin areas and uploads. If a legitimate form is blocked, disable that rule for the domain, or remove the line to turn body inspection off again.

Other WAFs also make request body inspection opt-in:

  • ModSecurity lists SecRequestBodyAccess as Off by default in its v2 engine (ModSecurity reference manual).
  • cPanel/WHM ModSecurity does not enable SecRequestBodyAccess by default and notes that it increases Apache’s memory usage (cPanel guide).
  • Oracle Cloud Infrastructure WAF excludes request bodies from inspection by default and notes that enabling it can increase latency (Oracle documentation).

ModSecurity rules need unique IDs. Give every new rule you add an ID from 50000 to 99999 so it never collides with a rule cPFence creates. cPFence uses the other ranges:

Rule IDs Used by
1000–1999 cPFence managed rules, including the main control panel hostname exception
6001–6999 Earlier domain switches and the global Layer7, bot and CAPTCHA switches
10000–49999 Domain switches that cPFence creates
50000–99999 Your custom rules
Any other ID cPFence WAF rules or reserved

Rules already in the file keep their IDs, including rules brought over from v3, so you don’t need to renumber them. The editor refuses a new rule that reuses the ID of a cPFence WAF rule.

For example, this rule turns off WAF rule 941100 only for requests to /api/webhook:

SecRule REQUEST_URI "@beginsWith /api/webhook" "id:50001,phase:1,pass,nolog,ctl:ruleRemoveById=941100"

Like cPFence v3, your rules are applied as written and the web server decides whether it can load them.

  1. The editor accepts ModSecurity rules and rule exceptions. For safety it refuses features that run programs, change the web server’s environment, forward requests, read files or look up other hosts (exec:, setenv:, proxy:, @inspectFile, @pmf, @ipMatchF, the ...FromFile operators, @validateDTD, @validateSchema, @fuzzyHash, @rbl and @gsbLookup). The save names the refused line and nothing is changed.
  2. When WAF is on, the rules are applied to the web server at once.
  3. If the web server cannot start with your rules, the save is refused, the previous file is kept and the web server’s error is shown.

You can also edit /etc/cpfcli/waf/overrides.conf over SSH. cPFence applies it as written within five minutes. If the web server cannot start with your custom rules, cPFence keeps it running without them, and your domain and global WAF switches stay applied. cpfence --enable-cpf-waf and the WAF rule and domain commands then show a warning, and cPFence tries again only after you change the file. Don’t edit overrides-before.conf or overrides-after.conf: cPFence regenerates them from overrides.conf.

Any rule your web server’s ModSecurity supports can be used, apart from the features the editor refuses above. For example:

  • @ipMatch with IP addresses and CIDR ranges, for example SecRule REMOTE_ADDR "@ipMatch 192.0.2.10,198.51.100.0/24" "id:50002,phase:1,pass,nolog,ctl:ruleEngine=Off", including !@ipMatch inside a rule chain.

  • Numeric or named severities: severity:2 or severity:'CRITICAL'.

  • SecRuleUpdateActionById to change how one rule responds, for example a custom status for CrowdSec or fail2ban:

    SecRuleUpdateActionById 942160 "deny,status:418"

    On OpenLiteSpeed, a rule that sets its own status keeps that status.

The cPFence WAF never inspects response bodies (the pages your sites send back), so SecResponseBodyLimit has no effect. Request bodies are separate: see turn on request body (POST) inspection.

  1. Identify the rule ID from the failed request and confirm the correct server and domain (track a WAF rule).
  2. Check the domain’s disabled-rule exceptions in Manage domain.
  3. Change only the intended rule, save, and read any error the save reports.
  4. Repeat the request and check the web-server errors.

If the supported controls and a custom rule cannot express your requirement, contact support with the desired scope and the matching WAF event.