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.

Choose a rule ID from 50000 to 99999

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"

What happens when you save

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.

Rule features

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.

SecResponseBodyLimit is not needed: the cPFence WAF does not inspect response bodies.

Leave generated lines to their controls

Lines that start with SecRule REQUEST_HEADERS:Host "@streq and SecAction lines are written by the domain and global WAF controls. Change them with those controls, not by hand.

Troubleshooting a custom rule

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.