Why ModSecurity matters
ModSecurity is a web application firewall (WAF) that sits in front of your web server and inspects requests and responses to detect and block attacks such as SQL injection, cross-site scripting and bad bots. Installing ModSecurity gives you a layer of protection that complements secure code and network controls. This guide walks through practical, step-by-step configuration so you can install, enable, test, and tune ModSecurity with minimal disruption to production traffic.
Before you start
Make sure you have root or sudo access to the server and a backup of your web server configuration. Identify which web server you run (apache, nginx, or Microsoft IIS) and whether you will use ModSecurity v2 or ModSecurity v3 (libmodsecurity). Apache usually has an easy packaged module for v2 on many linux distributions; nginx typically uses ModSecurity v3 plus a connector module. Decide whether you will initially run in detection-only mode to observe false positives before blocking traffic.
Step 1 , Install ModSecurity
The installation method depends on the platform and the ModSecurity version you choose. For many Debian/ubuntu systems running Apache, a packaged module is available. For Nginx, you commonly build or install libmodsecurity (v3) and use the modsecurity-nginx connector. Below are the common approaches; adapt them to your distribution and version.
Apache (quick packaged install on Debian/Ubuntu)
sudo apt update
sudo apt install libapache2-mod-security2
sudo a2enmod security2
sudo systemctl restart apache2The package places a default configuration at /etc/modsecurity/modsecurity.conf (sometimes provided as modsecurity.conf-recommended). Copy or move the recommended file to enable a sane starting point.
Nginx (ModSecurity v3 general approach)
For Nginx you will likely install libmodsecurity (v3) and the modsecurity-nginx connector. This often requires building libmodsecurity from source and compiling Nginx with the connector module or using a distribution that packages the connector. Follow the official build instructions for libmodsecurity and then compile the connector into Nginx or use a bundled package from your OS vendor.
Step 2 , Basic configuration
Open the main ModSecurity configuration file (commonly /etc/modsecurity/modsecurity.conf) and start with conservative settings that let you monitor traffic. The most important directive is SecRuleEngine which controls whether ModSecurity is off, in detection-only mode, or actively blocking. Use detection-only while tuning rules and switch to blocking when you are confident.
# Basic recommended settings (example)
SecRuleEngine DetectionOnly
SecRequestBodyAccess On
SecResponseBodyAccess Off
SecRequestBodyLimit 13107200
SecRequestBodyNoFilesLimit 131072
SecAuditEngine RelevantOnly
SecAuditLog /var/log/modsec_audit.log
SecAuditLogParts ABIJDEFHZ
Save changes and restart the web server. DetectionOnly prevents outright blocking while still logging rule matches so you can measure false positives and tune rules before enabling blocking.
Step 3 , Install and enable OWASP Core Rule Set (CRS)
The OWASP Core Rule Set (CRS) provides a widely used, well-tested set of generic security rules that catch common web attacks. Installing CRS is the fastest way to get strong coverage without writing all your own rules. Download or install the CRS package and include its configuration from your ModSecurity main config.
Typical steps:
- Download CRS (git clone or package manager).
- Copy the example setup file (crs-setup.conf.example) to crs-setup.conf and edit runtime options like anomaly thresholds.
- Include the CRS rule files from your ModSecurity config, for example:
Include /usr/share/owasp-crs/crs-setup.conf
Include /usr/share/owasp-crs/rules/*.conf
After including the rules, restart the web server and check logs. Keep SecRuleEngine in DetectionOnly mode until you are satisfied with the noise level and have addressed critical false positives.
Step 4 , Quick test and validation
Validate that ModSecurity is running and processing requests with a simple test rule and a request that triggers it. Add a custom rule for a harmless test such as blocking a special User-Agent string so you can simulate a block without triggering real traffic.
# Example test rule (place in local rules file)
SecRule REQUEST_HEADERS:User-Agent "ModSecTestAgent" "id:1000001,phase:1,deny,log,msg:'Test block by custom rule'"
After reloading configuration, test with curl:
curl -A "ModSecTestAgent" -I If ModSecurity is in blocking mode you should see a 403 or another blocking response. For detection-only mode, check the audit log (commonly /var/log/modsec_audit.log) and the web server error log to see the matched rule ID and audit entry.
Step 5 , Tuning and whitelisting
False positives are the most common operational challenge. When a legitimate request is blocked, find the rule ID in the ModSecurity audit log and create a targeted exception rather than disabling entire rule sets. Use these approaches:
- Disable a rule globally: SecRuleRemoveById <id> (use sparingly).
- Exclude a specific url or parameter from a rule: use ctl: ruleRemoveById or SecRuleUpdateTargetById to change targets.
- Create an allow-list rule keyed to IP or path that runs before CRS rules (use careful scoping and low IDs in your local rules file).
Example: to remove CRS rule 942100 globally:
SecRuleRemoveById 942100A better pattern is to target only the false-positive condition with a RuleRemoveById inside a conditional SecRule that matches the URI or client IP, so you keep protection everywhere else.
Step 6 , Logging, rotation and performance considerations
Audit logging provides depth but can create large files and I/O load. Use SecAuditEngine RelevantOnly or specify SecAuditLogParts to record only needed parts of a transaction. Rotate logs regularly and forward them to a log collector or SIEM for analysis. Evaluate resource usage and tune request body limits to avoid excessive memory consumption for large uploads. If ModSecurity introduces latency, review which phases and rules are most active and test disabling high-cost rules or offloading heavy checks to a WAF appliance or cloud WAF.
Common pitfalls and how to avoid them
Administrators often enable full blocking too early, which results in business traffic disruption. Start in detection-only mode and analyze logs for several days under expected traffic patterns. Incorrect file permissions on the ModSecurity configuration and rule files can prevent rules from loading; ensure the web server user can read them. If your site sits behind a reverse proxy or load balancer, verify client IP preservation so access control and logs identify the real client, using X-Forwarded-For or a trusted proxy configuration.
Summary
Configuring ModSecurity is a balance between protection and availability. Install the correct ModSecurity version for your server, enable it in detection-only to observe effects, add the OWASP CRS for broad coverage, and test with targeted rules before switching to enforcement mode. Tuning and precise whitelisting reduce false positives, while careful logging and resource settings keep the system performant. With methodical testing and incremental changes you can operate ModSecurity reliably as a practical WAF layer.
frequently asked questions (FAQs)
1. Should I run ModSecurity in DetectionOnly or On?
Start in DetectionOnly to collect data on rule matches and false positives. Once you have tuned rules and addressed frequent false positives, switch SecRuleEngine to On to actively block malicious traffic. Keeping it in DetectionOnly indefinitely reduces protection, so plan a controlled switch to enforcement.
2. How do I handle false positives without disabling entire rule sets?
Identify the offending rule ID from the audit log, then apply a targeted exception: use SecRuleRemoveById for a specific ID, or create a conditional rule that removes that ID only for a particular URI, parameter, or client IP. This preserves protection everywhere else while resolving the false positive.
3. Where are ModSecurity logs stored?
Default locations vary by platform and package. Common places include /var/log/modsec_audit.log for audit logs and the web server error log (e.g., /var/log/apache2/error.log or /var/log/nginx/error.log) for alerts. Check the SecAuditLog directive in your modsecurity.conf to find or change the audit log path.
4. Can ModSecurity inspect https traffic?
Yes, ModSecurity inspects requests after tls termination. If your TLS is terminated at the web server running ModSecurity, it can inspect full HTTP requests. If TLS is terminated at a proxy or load balancer in front of the server, ensure traffic to your server is forwarded unencrypted or that the proxy forwards decrypted traffic, otherwise ModSecurity will not see the raw requests.
5. Does ModSecurity work with Nginx?
Yes. Nginx typically uses ModSecurity v3 (libmodsecurity) together with the modsecurity-nginx connector. Installation may require building libmodsecurity and compiling the connector into Nginx or using distribution packages that include the connector. Follow connector documentation for correct integration.
