ModSecurity is a popular open-source Web Application Firewall (WAF) engine supported by cPanel/WHM. It inspects incoming HTTP requests in real-time, blocking common attack vectors like SQL injection, cross-site scripting (XSS), and local file inclusion (LFI). However, because ModSecurity rules (such as the OWASP Core Rule Set) are designed to be strict, they can sometimes flag legitimate user activities as malicious, resulting in 403 Forbidden errors or blocked requests (known as false positives).
For example, a user updating a WordPress page builder or saving complex theme settings can trigger a false positive because the payload contains HTML tags or code snippets that look like an XSS attempt. In this guide, we will explore how ModSecurity rules are evaluated, how to find triggered rules in server logs, and how to whitelist false positives safely without disabling your firewall.
1. How ModSecurity Rules and False Positives Work
ModSecurity operates as an Apache or LiteSpeed module. It evaluates incoming requests against a configured rule set. Each rule matches specific patterns in request headers, cookies, POST parameters, or query strings. If a request triggers a rule, ModSecurity increments a threat score. If the score exceeds your configured threshold, the request is blocked, and the server returns a 403 Forbidden error.
When a false positive occurs, the legitimate request matches a rule pattern by accident. While disabling ModSecurity entirely will resolve the issue, it leaves your server exposed to attacks. A secure approach is to identify the specific rule ID causing the block and whitelist it only for the affected website or request parameter.
2. Step-by-Step Diagnostic Commands via SSH
To diagnose ModSecurity false positives, log into your server via SSH as the root user. Run these commands to search server logs and configure whitelisting rules.
Step 2.1: Locate the ModSecurity Audit Log
When ModSecurity blocks a request, it logs the event in the server's audit log. In cPanel/WHM, the log location depends on your web server engine:
- Apache Web Server:
/etc/apache2/logs/modsec_audit.log - LiteSpeed Enterprise:
/usr/local/apache/logs/modsec_audit.log
You can search the log file using the grep utility to find entries for the blocked IP address or domain name:
grep "192.168.1.100" /etc/apache2/logs/modsec_audit.logStep 2.2: Find the Triggered Rule ID (secRule)
Open the log entry for the blocked request. Look for the log segment containing the rule evaluation details, which will display the triggered rule ID, message, and target parameter:
[id "941100"] [msg "XSS Attack Detected via libxml2"] [data "Matched Data: <script> found"]Note the **Rule ID** (in this example, 941100). This is the identifier we will use to whitelist the rule.
Step 2.3: Whitelist the Rule in WHM
You can whitelist rules globally, per-domain, or per-user. WHM provides a graphical interface to manage this:
First, log into WHM and navigate to **Security Center > ModSecurity Tools**. Click on **Hits** to view recent blocked requests. Locate the blocked entry, click **View Details**, and select **Deactivate Rule** to disable that specific rule ID globally.
If you prefer to disable the rule only for the affected domain to maintain security, configure a per-domain override in your Apache configuration directory. Create a custom configuration file under the domain's user directory:
mkdir -p /etc/apache2/conf.d/userdata/ssl/2_4/username/domain.com/
nano /etc/apache2/conf.d/userdata/ssl/2_4/username/domain.com/modsec.confAdd the following configuration rule to disable the specific rule ID for that domain:
<IfModule mod_security2.c>
SecRuleRemoveById 941100
</IfModule>Save the file, run /usr/local/cpanel/scripts/rebuildhttpdconf to rebuild the Apache configuration, and restart the web server to apply the changes:
/usr/local/cpanel/scripts/rebuildhttpdconf
systemctl restart httpd3. ModSecurity Whitelisting Methods
| Whitelisting Method | Scope / Impact | Configuration Command / Action |
|---|---|---|
| Deactivate Rule in WHM | Global (all domains on server) | Disable via WHM ModSecurity Tools interface |
| Per-Domain Override | Single Domain only | Add SecRuleRemoveById [ID] in Apache userdata directory |
| ModSecurity Vendoring whitelist | Global third-party rules sets | Add rule ID to vendor whitelist file in /etc/apache2/conf.d/ |
Frequently Asked Questions (FAQ)
Why does saving my WordPress page trigger a ModSecurity 403 error?
WordPress page builders (like Elementor or Divi) send complex JSON layouts and HTML snippets in POST parameters when saving pages. ModSecurity rules can flag these payloads as cross-site scripting (XSS) or SQL injection attempts because they contain code strings, triggering a 403 block.
Is it safe to disable ModSecurity globally if one rule is blocked?
No. Disabling ModSecurity globally removes Web Application Firewall protection for all websites on your server, leaving them exposed to vulnerability scans. The recommended approach is to identify the specific rule ID causing the false positive and disable only that rule for the affected domain.
Where are ModSecurity hits logged?
ModSecurity logs blocks in '/etc/apache2/logs/modsec_audit.log' (on Apache setups) or '/usr/local/apache/logs/modsec_audit.log' (on LiteSpeed setups). You can also view recent logs graphically in WHM under Security Center > ModSecurity Tools.