Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ModSecurity Integration

CSM detects ModSecurity (WAF) on Apache, Nginx, and LiteSpeed across cPanel and plain Linux hosts. Custom rule deployment, override writes, and reload management are currently cPanel-only; other platforms still receive status, staleness, and event detection.

Supported Web Servers

Web serverConfig candidatesStatus checkCustom rule deployment
Apache on cPanel EA4/usr/local/apache/conf/*, /etc/apache2/conf.d/modsec*, whmapi1 modsec_is_installedYesYes (via cPanel modsec user conf)
Apache on Debian/Ubuntu/etc/apache2/mods-enabled/security2.conf, /etc/apache2/conf-enabled/*, /etc/apache2/conf.d/modsec2.confYesNo
Apache on RHEL/Alma/Rocky/etc/httpd/conf.d/mod_security.conf, /etc/httpd/conf.modules.d/*YesNo
Nginx on any distro/etc/nginx/nginx.conf, /etc/nginx/modules-enabled/50-mod-http-modsecurity.conf, /etc/nginx/modsec/main.confYesNo
LiteSpeed/usr/local/lsws/conf/httpd_config.xml, /usr/local/lsws/conf/modsec2.confYescPanel only

When ModSecurity is not installed, the waf_status check emits a platform-specific install hint:

# On Ubuntu + Nginx:
Install: apt install libnginx-mod-http-modsecurity modsecurity-crs

# On Ubuntu + Apache:
Install: apt install libapache2-mod-security2 modsecurity-crs && a2enmod security2

# On AlmaLinux + Apache:
Install (requires EPEL): dnf install -y epel-release && dnf install -y mod_security

# On AlmaLinux + Nginx:
Install (requires EPEL): dnf install -y epel-release && dnf install -y nginx-mod-http-modsecurity

# On cPanel:
Install: WHM > Security Center > ModSecurity

Rule-staleness alerts scan both the flat CRS layout (/usr/share/modsecurity-crs/rules/*.conf) used by distro packages and cPanel vendor trees, including nested layouts such as modsec_vendor_configs/VENDOR/rules/*.conf. On cPanel, CSM maps WHM’s active configuration files to their vendor trees and checks the newest artifact in each loaded tree. This honors individual configuration overrides, keeps retired trees out of the result, and prevents a fresh unloaded vendor from hiding a stale loaded one. LiteSpeed also keeps the on-disk check as a backstop while cPanel rebuilds the active configuration list and rule tree. If WHM cannot provide the mapping, and on other platforms, the check keeps the conservative oldest-artifact behavior. Update instructions are platform-specific (apt update && apt upgrade modsecurity-crs, dnf upgrade modsecurity-crs, or WHM on cPanel).

Features

  • Custom CSM rules - IDs 900000-900999 in configs/csm_modsec_custom.conf (cPanel only today)
  • Rule override management - SecRuleRemoveById directives for false positive suppression
  • Escalation control - change rule severity or action per-rule
  • Live deny escalation - repeated ModSecurity deny events from one IP emit an escalation finding that feeds auto-response blocking. CSM-owned rules keep their existing per-rule escalation controls. CSM rules that match one specific exploit escalate on the first deny.
  • Disabled-scope detection - reports domains and accounts with the engine switched off, covering both the userdata flag and the per-account and per-domain config includes used by Apache and LiteSpeed in the std and ssl trees. A malware finding from a scheduled or account scan on such an account, or on a file served by such a domain, gets a context line naming the scope and the file that switches the engine off. It shows in alerts, the web UI, scan reports, webhooks and the audit log. Only the accounts and sites with malware findings are read for this. The line is not part of the finding’s identity: the finding keeps its severity, and turning the engine off or on neither re-alerts it nor undoes a dismissal
  • WAF event log parsing - correlates events by IP, URI, and rule ID
  • Hot-reload - apply changes without Apache restart (cPanel only)
  • Rule activation - ModSecurity reads rules only when the web server starts or reloads. When CSM’s installed rule sections change, for example after an upgrade or csm install, the daemon runs modsec.reload_command at startup or during its WAF check. Each rule change reloads once. Standalone csm check runs never reload. A failed reload raises a waf_status warning and is retried. Without a command, CSM only warns at startup and the rules wait for the next web server restart.

First-deny escalation requires a blocking action for an exact CSM rule ID. Request text cannot turn a warning into a deny. Disabling a rule’s firewall escalation excludes both new events and retained evidence from later blocking decisions. Existing firewall bans keep their configured expiry.

ModSecurity error-log detections take the client address only from the structured prefix before ModSecurity: or [MODSEC]. Fields later in the same record cannot supply a client address. Live monitoring, scheduled WAF checks, and the Web UI use the same parser. The module marker must follow the server’s structured header directly. Markers inside ordinary file errors, PHP errors, or other message text do not create WAF detections. Standard Apache, Nginx and LiteSpeed headers are accepted; custom headers outside those formats are ignored. Apache’s module-qualified error prefix, including [:error], identifies its unbracketed IPv6 connection port. Legacy Apache and libmodsecurity client fields keep the complete IPv6 address. Bracketed addresses with a port are also accepted. Custom Apache logs must retain the module field to distinguish unbracketed IPv6 addresses with ports from bare addresses. LiteSpeed IPv6 connection formats are unsupported: events keep an unknown client and cannot trigger an IP escalation. The Web UI uses the finding’s recorded source address, with a prefix-only raw-log fallback for older findings; it leaves the client unknown when neither is available. On Apache 2.4 a line must carry ModSecurity’s own module tag (security2 or security3). Lines that another module tags, such as PHP or CGI output, and LiteSpeed PHP stderr lines are never ModSecurity events, even when their text holds a ModSecurity message. A LiteSpeed line must have its standard header, with the connection field directly before [MODSEC].

Apache 2.2-style headers without a module tag remain accepted for compatibility. They cannot distinguish ModSecurity output from a hosted site’s message that starts with the same marker, so false alerts and visitor escalation remain possible with that format. Use module-tagged Apache logs to separate writers.

Header validation does not authenticate file-based records. Nginx can write literal line breaks from decoded filenames into its error log, allowing request text to create an entire apparent record on a new line. File-based real-time escalation and scheduled error-log scans remain exposed to that case. Native ModSecurity audit logs provide transaction framing for scheduled scans; fixing real-time ingestion requires a source that preserves authenticated record boundaries rather than splitting arbitrary log bytes into lines.

Scheduled audit scans read native serial logs and concurrent indexes from ModSecurity 2 and libmodsecurity 3, plus libmodsecurity 3 JSON logs. Counts use the recorded client address and denial action or response status. Request and response content cannot select another client or cancel another client’s counts. The existing web_server.modsec_audit_logs setting selects the candidate logs.

To scan error-log records instead, include the source in that candidate list and identify it with modsec_error_log or web_server.error_logs. Detected platform error logs are also recognized. These sources count only messages starting with Access denied with code after the module marker. Request text cannot switch their interpretation to an audit index or suppress a denial. Other audit candidates accept native audit records only. Custom error-log candidates must be identified this way when upgrading. Changing a source’s type restarts its scan so previous counts cannot carry across formats.

Only complete transactions within the recent line window contribute to these counts. The first scan and scans after log rotation read from the file’s start to establish transaction boundaries. Later scans resume from the saved position. Large existing logs can take longer on the first scan. Memory use stays bounded, and incomplete writes wait for the next scan.

CSM adds the default escalation exclusion for browser-marked upload progress requests once, including on upgrade, and keeps later operator changes. If the saved exclusions cannot be read, CSM keeps running and blocking requests but pauses ModSecurity firewall escalation, and the rules page reports the error instead of overwriting them. The next start retries the default update.

LiteSpeed logs every rule match as triggered!, whether or not the rule denied the request, so CSM looks up each rule’s action in the installed rule files. Apache logs say whether a request was denied and do not need the lookup. A rule whose action is block does what the SecDefaultAction for its phase says, and pass when there is none, as in ModSecurity. OWASP CRS in anomaly scoring mode sets pass, so its detection rules count as warnings, not denies. CSM does not follow Include order: a SecDefaultAction applies to the rules in its own directory and below, so a vendor pack’s setup file governs that pack and no other.

CSM reads rule IDs, phases and actions from the rule’s action argument. Text inside an operator, message or log data cannot override them. Explicit disruptive actions take precedence over inherited block actions. When setup files in the applicable directory cannot be read or parsed, inherited block actions remain blocking until CSM can resolve them. Explicit actions are still usable, and rules without a disruptive action remain unknown.

The directory walk follows symlinked packs and rule directories. Defaults follow the configured directory layout, including nested overrides. Directory cycles are reported as incomplete reads and prevent caching the result.

CSM checks the rule-action registry every five minutes and rebuilds it when rule or setup file contents change. Read failures leave the build uncached so the next check retries. Files that were read in full but exceeded the parser’s line limit are reported without forcing unchanged files to be parsed again. Rules appended after parsing reaches the end of a file are picked up on the next check.

The reload command runs inside CSM’s systemd sandbox. Use a service-manager command such as systemctl reload lsws for LiteSpeed, so the web server’s service performs the reload. Direct reload scripts inherit CSM’s filesystem restrictions and may fail. A LiteSpeed reload restarts workers and can briefly raise load.

The LiteSpeed Cache role-simulation filter covers privileged routes and writes, including WordPress REST method overrides, when requests carry simulation cookies with a weak hash. Ordinary public GET/HEAD crawling remains allowed. This is a request-scoped mitigation: public reads still run under the simulated identity, so upgrading the vulnerable plugin remains necessary.

The usual hash discriminator is 1-16 alphanumeric characters versus the fixed plugin’s 32-character hashes. Numeric equivalents are also filtered because the vulnerable plugin compares hashes loosely; padding or exponent notation must not turn a weak hash into an exempt one. These checks also keep public crawler reads allowed.

The WordPress user enumeration filter blocks anonymous requests for the REST users route, whether the route follows wp-json/ in the path or starts at wp/v2/users in the rest_route query parameter, in any letter case. Other page paths and REST namespaces are left alone. Query values are matched as already decoded by the query parser. Requests that carry an Authorization header or a WordPress logged-in cookie pass, so admin screens, the editor and Application Password clients keep working. Both are presence checks: the filter turns away anonymous scanners, and WordPress still decides who is signed in.

The filter runs in phase 1 and does not inspect request bodies. A route supplied only in a POST body, including with a REST method override, is outside its scope. Sites that need to restrict the public users endpoint must enforce that policy in WordPress. Disabling rule 900112 disables this filter for both route forms; its helper rules only set transaction-local flags and do not block requests.

The PHP session upload-progress filter denies requests whose form field names contain PHP’s default PHP_SESSION_UPLOAD_PROGRESS field name, matched case-insensitively so quoted spellings are covered. A custom session.upload_progress.name is outside this filter’s coverage. GET and HEAD pass. Other methods use the first-deny escalation rule when both Origin and Sec-Fetch-Site are absent; browser-marked requests use the separate rule whose escalation is off by default. Keep that exclusion to avoid browser-steered bans. A browser whose extension or proxy strips Origin on a plain-HTTP request can still reach the first-deny rule. PHP handles that field before any script runs, which leaves the web server as the only layer that can drop the request. See CVE Mitigations for the PHP-side setting that removes the handler.

For Apache ModSecurity v2 regression validation, run python3 scripts/test-litespeed-modsec.py in a disposable Debian Linux environment with apache2, libapache2-mod-security2, libapache2-mod-php, and python3 installed. The test loads the complete shipped configuration and exercises HTTP requests through the actual engine and PHP parser. It does not establish LiteSpeed runtime compatibility; verify changed rules on the supported LiteSpeed engine before deployment.

Web UI Pages

ModSecurity (/modsec) - WAF status overview, event log, active block list, filterable by time range, minimum severity, and source country

ModSec Rules (/modsec/rules) - per-rule management:

  • View the CSM rules with descriptions and hits in the last 24 hours
  • Enable or disable individual rules; changes are staged and applied with one reload
  • Turn firewall escalation off for a rule: the rule still denies the request, but CSM does not block the IP in the firewall
  • Escalation exclusions are listed and edited here even when rule management (modsec.rules_file, modsec.overrides_file, modsec.reload_command) is not configured, since the daemon applies them either way

API Endpoints

GET  /api/v1/modsec/stats            WAF statistics
GET  /api/v1/modsec/blocks           Blocked request log
GET  /api/v1/modsec/events           WAF event details
GET  /api/v1/modsec/rules            Loaded rules list
POST /api/v1/modsec/rules/apply      Apply the set of disabled rules and reload
GET  /api/v1/modsec/rules/escalation Rule IDs excluded from firewall escalation
POST /api/v1/modsec/rules/escalation Exclude one rule from escalation or turn it back on