ModSecurity® Reference Manual
Current as of v2.5.13 and v2.6
Copyright © 2004-2011 Trustwave Holdings, Inc.
Table of Contents
ModSecurity is a web application firewall (WAF). With over 70% of attacks now carried out over the web application level, organisations need all the help they can get in making their systems secure. WAFs are deployed to establish an increased external security layer to detect and/or prevent attacks before they reach web applications. ModSecurity provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring and real-time analysis with little or no changes to existing infrastructure.
HTTP Traffic Logging
Web servers are typically well-equipped to log traffic in a form useful for marketing analyses, but fall short logging traffic to web applications. In particular, most are not capable of logging the request bodies. Your adversaries know this, and that is why most attacks are now carried out via POST requests, rendering your systems blind. ModSecurity makes full HTTP transaction logging possible, allowing complete requests and responses to be logged. Its logging facilities also allow fine-grained decisions to be made about exactly what is logged and when, ensuring only the relevant data is recorded. As some of the request and/or response may contain sensitive data in certain fields, ModSecurity can be configured to mask these fields before they are written to the audit log.
Real-Time Monitoring and Attack Detection
In addition to providing logging facilities, ModSecurity can monitor the HTTP traffic in real time in order to detect attacks. In this case, ModSecurity operates as a web intrusion detection tool, allowing you to react to suspicious events that take place at your web systems.
Attack Prevention and Virtual Patching
ModSecurity can also act immediately to prevent attacks from reaching your web applications. There are three commonly used approaches:
- Negative security model. A negative security model monitors requests for anomalies, unusual behaviour, and common web application attacks. It keeps anomaly scores for each request, IP addresses, application sessions, and user accounts. Requests with high anomaly scores are either logged or rejected altogether.
- Positive security model. When a positive security model is deployed, only requests that are known to be valid are accepted, with everything else rejected. This model requires knownledge of the web applications you are protecting. Therefore a positive security model works best with applications that are heavily used but rarely updated so that maintenance of the model is minimized.
- Known weaknesses and vulnerabilities. Its rule language makes ModSecurity an ideal external patching tool. External patching (sometimes referred to as Virtual Patching) is about reducing the window of opportunity. Time needed to patch application vulnerabilities often runs to weeks in many organisations. With ModSecurity, applications can be patched from the outside, without touching the application source code (and even without any access to it), making your systems secure until a proper patch is applied to the application.
Flexible Rule Engine
A flexible rule engine sits in the heart of ModSecurity. It implements the ModSecurity Rule Language, which is a specialised programming language designed to work with HTTP transaction data. The ModSecurity Rule Language is designed to be easy to use, yet flexible: common operations are simple while complex operations are possible. Certified ModSecurity Rules, included with ModSecurity, contain a comprehensive set of rules that implement general-purpose hardening, protocol validation and detection of common web application security issues. Heavily commented, these rules can be used as a learning tool.
ModSecurity is an embeddable web application firewall, which means it can be deployed as part of your existing web server infrastructure provided your web servers are Apache-based. This deployment method has certain advantages:
- No changes to existing network. It only takes a few minutes to add ModSecurity to your existing web servers. And because it was designed to be completely passive by default, you are free to deploy it incrementally and only use the features you need. It is equally easy to remove or deactivate it if required.
- No single point of failure. Unlike with network-based deployments, you will not be introducing a new point of failure to your system.
- Implicit load balancing and scaling. Because it works embedded in web servers, ModSecurity will automatically take advantage of the additional load balancing and scalability features. You will not need to think of load balancing and scaling unless your existing system needs them.
- Minimal overhead. Because it works from inside the web server process there is no overhead for network communication and minimal overhead in parsing and data exchange.
- No problem with encrypted or compressed content. Many IDS systems have difficulties analysing SSL traffic. This is not a problem for ModSecurity because it is positioned to work when the traffic is decrypted and decompressed.
ModSecurity works equally well when deployed as part of an Apache-based reverse proxy server, and many of our customers choose to do so. In this scenario, one installation of ModSecurity can protect any number of web servers (even the non-Apache ones).
ModSecurity is known to work well on a wide range of operating systems. Our customers are successfully running it on Linux, Windows, Solaris, FreeBSD, OpenBSD, NetBSD, AIX, Mac OS X, and HP-UX.
ModSecurity is available under the Apache Software License v2 
- ModSecurity, mod_security, ModSecurity Pro, and ModSecurity Core Rules are trademarks or registered trademarks of Trustwave Holdings, Inc.
OWASP ModSecurity Core Rule Set (CRS) Project
ModSecurity is a web application firewall engine that provides very little protection on its own. In order to become useful, ModSecurity must be configured with rules. In order to enable users to take full advantage of ModSecurity out of the box, Trustwave's SpiderLabs created the OWASP ModSecurity Core Rule Set (CRS) Project. Unlike intrusion detection and prevention systems, which rely on signatures specific to known vulnerabilities, the CRS provide generic protection from unknown vulnerabilities often found in web applications, which are in most cases custom coded. The CRS is heavily commented to allow it to be used as a step-by-step deployment guide for ModSecurity. The latest rules packages can be found at the OWASP ModSecurity CRS Project Site.
Core Rules Content
In order to provide generic web applications protection, the CRS use some of the following example techniques:
- HTTP protection - detecting violations of the HTTP protocol and a locally defined usage policy.
- Common Web Attacks Protection - detecting common web application security attack.
- Automation detection - Detecting bots, crawlers, scanners and other surface malicious activity.
- Trojan Protection - Detecting access to Trojans horses.
- Error Hiding - Disguising error messages sent by the server.
ModSecurity 2.x works only with Apache 2.0.x or higher
Version 2.2.x is highly recommended.
Make sure you have
mod_unique_id installed. mod_unique_id is packaged with Apache httpd.
libapr and libapr-util
libapr and libapr-util - http://apr.apache.org/
This library is optional and only needed if you will be using the new Lua engine - http://www.lua.org/download.html
- that ModSecurity requires the dynamic libraries. These are not built by default in the source distribution, so the binary distribution is recommended.
libcurl v7.15.1 or higher
If you will be using the ModSecurity Log Collector (mlogc) to send audit logs to a central repository, then you will also need the curl library.
- Many have had issues with libcurl linked with the GnuTLS library for SSL/TLS support. It is recommended that the openssl library be used for SSL/TLS support in libcurl.
Before you begin with installation you will need to choose your preferred installation method. First you need to choose whether to install the latest version of ModSecurity directly from CVS (best features, but possibly unstable) or use the latest stable release (recommended). If you choose a stable release, it might be possible to install ModSecurity from binary. It is always possible to compile it from source code.
The following few pages will give you more information on benefits of choosing one method over another.
SVN Access(Download ModSecurity to get the above Documentation and Read More)
Or go here...
Live Wiki Documentation
The Wiki Documentation will always be the most up-to-date.
Availability of ModSecurity 2.6.3 Release
(December 27, 2011)
The ModSecurity Development Team is pleased to announce the availability of ModSecurity 2.6.3 Release. The stability of this release should be good and it includes some new features and bug fixes, specially came from SDBM garbage collection code. Please see the release notes included into CHANGES file.
For known problems and more information about bug fixes, please see the online
This one looks very interesting... and I found ModSecurity in my Fedora 14 Repo's too. So, I should be able to just install it from Package Manager and then add the latest ModSecurity Core Rule Set. See the info above "ModSecurity is a web application firewall engine that provides very little protection on its own. In order to become useful, ModSecurity must be configured with rules. In order to enable users to take full advantage of ModSecurity out of the box, Trustwave's SpiderLabs created the OWASP ModSecurity Core Rule Set (CRS) Project." The CRS is available from the Download links on the http://www.modsecurity.org/ Site. I think I will try this one out when I get a chance...
- ModSecurity is a web application firewall engine
- ModSecurity: Open Source Web Application Firewall
- ModSecurity Mitigations for ASP.NET HashTable DoS Vulnerability (CVE-2011-3414) - SpiderLabs Anterior
- ModSecurity - Browse /modsecurity-crs/0-CURRENT at SourceForge.net
- ModSecurity: Open Source Web Application Firewall - Documentation
- SourceForge.net: mod-security
- SourceForge.net: Reference Manual - mod-security