ModSecurity/rules/README

==============================
ModSecurity Core Rule Set
==============================

(c) 2006-2009 Breach Secuiry Inc.

The ModSecurity Core Rule Set is provided to you under the terms and 
conditions of GPL version 2

This directory contains the files for Core ModSecurity Rule Set
The rules are compatible with ModSecurity 2.5 (as of version 1.4.3)



Overview
========

Using ModSecurity requires rules. In order to enable users to take full
advantage of ModSecurity immediately, Breach Security Inc. is providing a free 
Core rule set. Unlike intrusion detection and prevention systems which 
rely on signature specific to known vulnerabilities, the Core Rule Set 
provides generic protection from unknown vulnerabilities often found in web 
application that are in most cases custom coded. 

Keep in mind that a predefined rule set is only part of the work required to 
protect your web site. We strongly urge you to consult Ivan Ristic's book, 
"Apache Security" in order to harden your Apache web server. You may also 
consider writing custom rules for providing a positive security envelope to 
your application or critical parts of it. Breach Security can provide you with 
training and professional services to assist you in doing that. The Core 
Rule Set is heavily commented to allow it to be used as a step-by-step 
deployment guide for ModSecurity.

For more information refer to the Core Rule Set page at
http://www.owasp.org/index.php/Category:OWASP_ModSecurity_Core_Rule_Set_Project

Core Rules Mail-list - 
Suscribe here: https://lists.owasp.org/mailman/listinfo/owasp-modsecurity-core-rule-set
Archive: https://lists.owasp.org/pipermail/owasp-modsecurity-core-rule-set/
  
Core Rule Set Structure & Usage
====================================

To activate the rules for your web server installation:

  1) You may want to edit and customize modsecurity_crs_10_config.conf. 
     Additionally you may want to edit modsecurity_crs_30_http_policy.conf
     which enforces an application specific HTTP protocol usage.

     Should also update the appropriate anomaly scoring level in the
     modsecurity_crs_49_enforcement.conf and modsecurity_crs_60_correlation.conf
     files.  This will determine when you log and block events.

  2) Add the following line to your httpd.conf (assuming
     you've placed the rule files into conf/modsecurity/):

     Include conf/modsecurity/*.conf
     Include conf/modsecurity/base_rules/*conf

  3) Restart web server.

  4) Make sure your web sites are still running fine.

  5) Simulate an attack against the web server. Then check
     the attack was correctly logged in the Apache error log,
     ModSecurity debug log (if you enabled it) and ModSecurity
     audit log (if you enabled it).

  6) If you configured your audit log entries to be transported
     to ModSecurity Console in real time, check the alert was
     correctly recorded there too.


Known Issues
===============

Apache requests rejection and phase 2 rules
-------------------------------------------

Since now all inspection rules are executed in phase 2, several protocol
validation is done by Apache prior to ModSecurity. This is by no means a
security issue as Apache would block the requests, but the alert would appear
in the ModSecurity audit log as a generic event "Invalid Request (960913)"

Here's a list of the events that modsecurity might not log due to this issue:
- Validate encoding - 950107
    When invalid encoding is found in the URI
- Validate utf-8 encoding - 950801
    When invalid encoding is found in the URI
- Method not allowed by policy - 960032
    When the request uses a method that Apache doesn't know such as: CONNECT, SUBSCRIBE, etc.


Google Analytics
----------------

For Google Analytics account activation, you will need to disable
the Core Rules temporarily, then enable them after your Google account is
activated. More info can be found in the mod-security-mailing-list:
http://sourceforge.net/mailarchive/message.php?msg_name=1179692394.26994.10.camel%40localhost


About Regular Expressions
============================

One of the advantages of the Core Rule Set, being a set of text files is your 
ability to modify it. However you will find that the regular expressions used 
are very complex.

Since regular expressions are much more efficient if assembled into a single 
expression and optimized, a generation script takes a list of patterns that 
are required for a rule and optimize them into a most efficient regular 
expression.

We plan to release the optimization script shortly to allow much easier editing 
of regular expressions.


Core Rule Set Content
=========================

In order to provide generic web applications protection, the Core Rule Set 
uses the following techniques:

1. HTTP protection - detecting violations of the HTTP protocol and a locally 
defined usage policy.

2. Common Web Attacks Protection - detecting common web application security 
attack.

3. Automation detection - Detecting bots, crawlers, scanners and other surface 
malicious activity.

4. Trojan Protection - Detecting access to Trojans horses.

5. Errors Hiding - Disguising error messages sent by the server

In addition the rule set also hints at the power of ModSecurity beyond 
providing security by reporting access from the major search engines to your 
site.


HTTP Protection - This first line of protection ensures that all abnormal HTTP 
requests are detected. This line of defense eliminates a large number of 
automated and non targeted attacks as well as protects the web server itself. 
Common Web Attacks Protection Rules on the second level address the common web 
application security attack methods. These are the issues that can appear in 
any web application. Some of the issues addressed are:

- SQL Injection 
- Cross-Site Scripting (XSS) 
- OS Command execution 
- Remote code inclusion 
- LDAP Injection 
- SSI Injection 
- Information leak 
- Buffer overflows 
- File disclosure 

Automation Detection - Automated clients are both a security risk and a 
commercial risk. Automated crawlers collect information from your site, consume 
bandwidth and might also search for vulnerabilities on the web site. Automation 
detection is especially useful for generic detection of comments spam.


Trojan Protection - ModSecurity Core Rule Set detects access to back doors 
installed on a web server. This feature is very important in a hosting 
environment when some of this backdoors may be uploaded in a legitimate way and 
used maliciously. In addition the Core Rule Set includes a hook for adding 
an Anti-Virus program such as ClamAV for checking file uploads.

Errors Hiding - If all fails, the Core Rule Set will detect errors sent by 
the web server. Detecting and blocking errors prevents attackers from 
collecting reconnaissance information about the web application and also server 
as a last line of defense in case an attack was not detected eariler.


Few Word of Caution
-------------------

As with every new technology, using the ModSecurity Core Rule Set requires some caution:

- Every Rule Set can have false positive in new environments and any new 
installation should initially use the log only Rule Set version or if no such 
version is available, set ModSecurity to Detection only using the SecRuleEngine 
DetectionOnly command.

After running ModSecurity in a detection only mode for a while review the evens 
generated and decide if any modification to the rule set should be made before 
moving to protection mode.

- Freely available wide spread signatures have their down side as attackers may 
examine them and find ways to bypass them. Especially note that the automation 
detection signatures are relatively easy to evade and should not be viewed as a 
security mechanism but only as a "nuisance reduction" mechanism. 


Road Map
-------- 

This rule set is both young and old. Breach Security has a long experience with 
rules and signatures for application security protection and the Core Rule 
Set is based on this experience. On the other hand, this is a first cut of a 
ModSecurity rule set so your feedback and remarks, either directly or through 
the ModSecurity mailing list would be greatly appreciated.

Going forward we plan to: 

- Utilize ModSecurity 2.0 support for events correlation to detect denial of 
service attacks, brute force attacks and attack reconnaissance

- Add a framework for validating SOAP requests.

- Add signatures for key known vulnerabilities.

Anything else you would want?