Revision as of 17:43, 10 June 2014

Tuning and managing modsecurity Rules

Disabling Rules

Global

Disabling Mod_Security Globally

If you are using ASL, just change this setting:

https://www.atomicorp.com/wiki/index.php/ASL_WAF#MODSEC_ENABLED

If you are not using ASL, you will need to do this manually:

Step 1) Disable config file

mv /etc/httpd/conf.d/00_mod_security.conf /etc/httpd/conf.d/00_mod_security.conf.disabled

Step 2) Restart Apache

service httpd restart

Disable Mod_security on a global URL

Step 1) Create a global exclude file

vim /etc/httpd/modsecurity.d/00_custom_exclude.conf

Step 2) Add the LocationMatch for the url to exclude. Example: /server.php

<LocationMatch /server.php>
  <IfModule mod_security2.c>
    SecRuleEngine Off 
  </IfModule>
</LocationMatch>

Step 3) Restart apache

service httpd restart

Per domain

Disabling Mod_security per domain

For Plesk and similar systems you can also disable modsecurity in the Apache configuration.

Step 1) Edit the vhost/vhost_ssl.conf for the domain

 vim /var/www/vhosts/<DOMAINNAME>/conf/vhost.conf

Step 2) Add the following

<IfModule mod_security2.c>
  SecRuleEngine Off
</IfModule>

Then restart apache, if you are using Plesk then you will also need follow steps 3 and 4.

Step 3) Add vhost.conf to domain config

Plesk 9:

/usr/local/psa/admin/bin/websrvmng -a

Plesk 10/11:

/usr/local/psa/admin/bin/httpdmng --reconfigure-domain <domain_name>

Step 4) Restart Apache

service httpd restart

Disabling Mod_security per domain for an IP address

For Plesk and similar systems you can also disable modsecurity in the Apache configuration.

Step 1) Edit the vhost/vhost_ssl.conf for the domain

 vim /var/www/vhosts/<DOMAINNAME>/conf/vhost.conf

Step 2) Add the following

<IfModule mod_security2.c>
 SecRule REMOTE_ADDR "^1.2.3.4$" "phase:1,t:none,nolog,allow,ctl:ruleEngine=Off,ctl:auditEngine=Off,id:9999"
</IfModule>

Note: You must change id: to a number that you have not used for any other custom rules. Customer generated rules should use the range 1-99999. Numbers about 99999 are reserved and will cause conflicts and are not supported.

Then restart apache, if you are using Plesk then you will also need follow steps 3 and 4.

Step 3) Add vhost.conf to domain config

Plesk 9:

/usr/local/psa/admin/bin/websrvmng -a

Plesk 10/11:

/usr/local/psa/admin/bin/httpdmng --reconfigure-domain <domain_name>

Step 4) Restart Apache

service httpd restart

Disable a rule for a single domain

If you have ASL installed:

Method 1:

Log into the ASL GUI, and click on the "ASL" tab. Then click "WAF & HIDS Rules", then click the "Rules" tab, then click the "WAF" tab. Type in the rule ID and the rule manager will pull up the rule. Click on the green down error which will pull up the options for this rule.

Type in the vhost name into the Text box on the left side of the options, then click "add".

Keep in mind this is literal, so if you have a vhost with the name "example.com" that serves content for "ftp.example.com" and "www.example.com" you will need to add those FQDNs as well.

Note: You can use regular expressions in this field, but each end of the expression is anchored.

Method 2: Run this command as root:

 asl -dr RULE_ID --vhost www.example.com

Replace RULE_ID with the ID of the rule you want to disable for the vhost. Keep in mind this is literal, so if you have a vhost with the name "example.com" that serves content for "ftp.example.com" and "www.example.com" you will need to add those as well. For example:

 asl -dr RULE_ID --vhost www.example.com

 asl -dr RULE_ID --vhost ftp.example.com

 asl -dr RULE_ID --vhost example.com

If you do not have ASL installed you will have to do this manually:

Step 1) Edit the vhost/vhost_ssl.conf for the domain

vim /var/www/vhosts/<DOMAINNAME>/conf/vhost.conf

Step 2) Add the LocationMatch for the rule to exclude. Example, ruleid 950005

<LocationMatch .*>
  <IfModule mod_security2.c>
    SecRuleRemoveById 950005
  </IfModule>
</LocationMatch>

If you want to disable multiple rules:

Step 2) Add the LocationMatch for the rule to exclude. Example, ruleids 950005 and 950006

<LocationMatch .*>
  <IfModule mod_security2.c>
    SecRuleRemoveById 950005
    SecRuleRemoveById 950006
  </IfModule>
</LocationMatch>

Disable a rule for all domains

Method 1:

Log into the ASL GUI, and click on the "Configuration" tab. Then click "Rule Management", then click the "Rules" tab, then click the "WAF" tab. Type in the rule ID and the rule manager will pull up the rule. Click on the green down error which will pull up the options for this rule.

Set "disabled" to yes and click update.

Method 2:

Use ASL utility to disable rule by ID. Example: 950005

asl --disable-rule 950005

Note: This requires that Atomic Secured Linux be installed. If you do not have Atomic Secured Linux installed you can disable a rule globally manually by adding a rule to your own custom rules files that contains a line similar to this:

<LocationMatch .*>
  <IfModule mod_security2.c>
    SecRuleRemoveById 340000
  </IfModule>
</LocationMatch>

Custom rules should be loaded after atomicorp rules. A good place to add this, again only if you do not have ASL installed, is in the 999_user_exclude.conf file. If you don't have this file, just create it. Then make sure your modsecurity configuration is setup to load this file.

Per IP or network

Disable Mod_security for an IP address

In ASL, just click the "Whitelist" button.

If you are not using ASL, simply add your IP address to the file:

/etc/asl/whitelist

And restart Apache.

Note: For this rule to work, in ASL you must have the MODSEC_00_WHITELIST ruleset enabled.

If you are not using ASL, then you must have the 00_asl_whitelist.conf ruleset loaded.

Whitelist an IP

See above, "Disable Mod_security for an IP address"

Disable a rule by IP or network

You will need to create a custom rule, loaded after all your other rules. Lets say you wanted to exclude rule id 330039 for the network 1.2.0.0/16. You would construct a custom rule like this:

SecRule REMOTE_HOST "@ipmatch 1.2.0.0/16" \
"id:12345,phase:2,t:none,pass,nolog,noauditlog,ctl:ruleRemovebyID=330039"

Note: ipmatch can also use a list, with a combination of IPs and network for example:

@ipmatch 1.2.0.0/16,5.6.7.8,127.0.0.0/8

Warning: If the CIDR is invalid, this may cause a segfault of the mod_security module. Check to make sure your CIDR is valid before use.

Per application

Disable a rule for a specific web application

Add a custom rule (see the section below on creating custom rules) after all your rules have been loaded. For example, if you wanted to disable rule 950005, you would add a custom rule like this:

 <LocationMatch /URL/path/to/application.php>
     SecRuleRemoveById 950005

 </LocationMatch>

Disable a rule for a specific application in a single domain

Step 1) Edit the virtual servers configuration for the domain for the domain

Example:

vim /var/www/vhosts/<DOMAINNAME>/conf/vhost.conf

Step 2) Add the LocationMatch for the rule to exclude. Example, ruleid 950005

 <LocationMatch /URL/path/to/application.php>

     SecRuleRemoveById 950005
   </IfModule>

Disable Mod_security rules globally for a specific application

Add this to either you vhost.conf file, or if your want to make this global make sure this exclusion is loaded after your rules are loaded. A good place to add this in the 999_user_exclude.conf file. If you don't have this file, just create it. Then make sure your modsecurity configuration is setup to load this file.

<LocationMatch /url/to/your/application>
  <IfModule mod_security2.c>
    SecRuleRemoveById 1234567
    SecRuleRemoveById 9999999
  </IfModule>
</LocationMatch>

Whats important to remember is that the LocationMatch variable must match the URL, not the path on the system.

Disable Mod_security rules by domain, for a specific application, for a list of IPs

Step 1) Edit the vhost/vhost_ssl.conf for the domain

vim /var/www/vhosts/<DOMAINNAME>/conf/vhost.conf

Step 2) Add the LocationMatch for the rule to exclude.

<LocationMatch /foo/bar.php>
  <IfModule mod_security2.c>
    SecRule REMOTE_ADDR "@pmFromFile /etc/asl/whitelist" "nolog,phase:1,allow"
  </IfModule>
</LocationMatch>

Step 3) Add IP to /etc/asl/whitelist

echo "10.11.12.13" >> /etc/asl/whitelist

Or:

If you want to create a special whitelist for just that application:

Step 1) Edit the vhost/vhost_ssl.conf for the domain

vim /var/www/vhosts/<DOMAINNAME>/conf/vhost.conf

Step 2) Add the LocationMatch for the rule to exclude.

<LocationMatch /foo/bar.php>
  <IfModule mod_security2.c>
    SecRule REMOTE_ADDR "@pmFromFile /path/to/your/custom/whitelist_for_this_application" "nolog,phase:1,allow,id:9999"
  </IfModule>
</LocationMatch>

Note: You must change id: to a number that you have not used for any other custom rules. Customer generated rules should use the range 1-99999. Numbers about 99999 are reserved and will cause conflicts and are not supported.

Step 3) Create your custom whitelist and add IP to /etc/asl/whitelist

echo "10.11.12.13" >> /path/to/your/custom/whitelist_for_this_application

Keep in mind these custom lists are *not* managed by ASL, so if you want to add IPs to these lists you will need to do it from the command line.

Disabling rules using .htaccess

This is a new feature in modsecurity 2.7.3. This capability is available if you compile modsecurity using this option:

--enable-htaccess-config

From there, you will be able to disable rules using .htaccess files. The format to disable a rule via .htaccess is:

SecRuleRemoveById 12345

Where 12345 is the rule id.

Note: This capability is not enabled by default in modsecurity, and must be enabled specifically when modsecurity is compiled. If .htaccess directives do not work for you, then modsecurity is either not version 2.7.3 or higher, or this option has not been enabled.

Specific actions available in .htaccess

• SecAction
• SecRule
• SecRuleRemoveByMsg
• SecRuleRemoveByTag
• SecRuleRemoveById
• SecRuleUpdateActionById
• SecRuleUpdateTargetById
• SecRuleUpdateTargetByTag
• SecRuleUpdateTargetByMsg

Note: This capability is not enabled by default in modsecurity, and must be enabled specifically when modsecurity is compiled. If .htaccess directives do not work for you, then modsecurity is either not version 2.7.3 or higher, or this option has not been enabled.

Warning: Enabling this capability in modsecurity can allow an attacker to disable modsecurity rules that you may be using to protect the entire server. We do not recommend you enable this capability on a shared server.

Customizing a rule

If you need to customize a rule do not change the asl*conf files. These files will be overwritten by updates.

The use of "asl" in the filename is also reserved. Do not name custom file with "asl" in the filename, for example, 99_asl_custom.conf. This file may be overwritten or deleted by the rule management system. Do not create custom rules with "asl" in the filename.

If you need to change a rule because it is incorrectly blocking something we recommend you report it to use as a False Postive, using the Reporting_False_Positives procedure. If you simply want to modify a rule to perform different actions, then copy the entire rule into your own rule file, and make sure you tell mod_security not to enable the original ASL rule. You can do that by using the mod_security action SecRuleRemoveById. Here is a simple example:

If you had an original rule like this:

 SecRule REQUEST_URI "/foo" "t:normalisePath,id:9000,rev:1,severity:2,msg:'Atomicorp.com WAF Rules: Block /foo'"

And you want it to block "bar" instead of "foo", then you would copy the entire rule into your own custom rule file. If you are using our rules we recommend you use the filename 99_zzz_custom.conf and change the id: field to an unused ID. You will need to configure Apache to load this file. You should load this file after the *asl*conf rule files have been loaded.

 SecRuleRemoveById 9000000
 SecRule REQUEST_URI "/bar" "t:normalisePath,id:9999,rev:1,severity:2,msg:'Atomicorp.com WAF Rules: Block /foo'"

Note: You must change id: to a number that you have not used for any other custom rules. Customer generated rules should use the range 1-99999. Numbers about 99999 are reserved and will cause conflicts and are not supported.

These are the reserved ranges:

   *     1-99,999; reserved for local (internal) use. Use as you see fit but do not use this range for rules that are distributed to others.
   *     100,000-199,999; reserved for internal use of the engine, to assign to rules that do not have explicit IDs.
   *     200,000-299,999; reserved for rules published at modsecurity.org.
   *     300,000-399,999; reserved for rules published at gotroot.com.
   *     400,000-419,999; unused (available for reservation).
   *     420,000-429,999; reserved for ScallyWhack.
   *     430,000-699,999; unused (available for reservation).
   *     700,000-799,999; reserved for Ivan Ristic.
   *     900,000-999,999; reserved for the Core Rules project.
   *     1,000,000 and above; unused (available for reservation).

For a domain

Apache

If you just want to customize the rule, or add a supported configuration setting for a domain you will want to add your modifications within the VirtualHost definition for the domain.

If you have a web application that uses the uncommon ";" argument separator, as opposed to the widely used "&" you will want to change SecArgumentSeparator value for that application. You can do this in one of two ways:

1) Globally

If all your applications use the older delimiter, just change the SecArgumentSeparator in the tortix_waf.conf file. Do not change this if your applications use other delimiters.

SecArgumentSeparator ";"

2) Per Application

You can also configure this per application. For example, if your web applications URL is /foo/bar.php you can create a customer rule like this:

<LocationMatch /foo/bar.php>
SecArgumentSeparator ";"
</LocationMatch>

This will only work if modsecurity is loaded before your virtual host definitions. This is the case with most control panels, but some control panels are known to load modsecurity after vhosts are defined. In which case this will fail because Apache will not know how to process this directive (it will need modsecurity loaded to understand what this means). If you get a syntax error, that means your apache configuration is loaded modsecurity after your vhosts are defined. You will need to change your apache configuration to ensure this loading occurs before vhosts are defined.

ASL will automatically configure modsecurity to load first.

Creating custom rules

Discussion

If you need to create your own custom rules, do not change the asl*conf files. These files will be overwritten by updates.

The use of "asl" in the filename is also reserved. Do not name custom files with "asl" in the filename, for example, 99_asl_custom.conf. This file may be overwritten or deleted by the rule management system. Do not create custom rules with "asl" in the filename.

Rule Ids for custom rules

For custom rules, you must create your own rule ids which must be unique. The id: fields contain the rule ids. For custom rules you should use the local (internal) use range (see below for the reserved id ranges). Do not use assigned ranges.

These are the reserved ranges:

   *     1-99,999; reserved for local (internal) use. Use as you see fit but do not use this range for rules that are distributed to others.
   *     100,000-199,999; reserved for internal use of the engine, to assign to rules that do not have explicit IDs.  (deprecated, all rules require assigned ids in 2.7.x and up)
   *     200,000-299,999; reserved for rules published at modsecurity.org.
   *     300,000-399,999; reserved for rules published by atomicorp.com
   *     400,000-419,999; unused (available for reservation).
   *     420,000-429,999; reserved for ScallyWhack.
   *     430,000-699,999; unused (available for reservation).
   *     700,000-799,999; reserved for Ivan Ristic.
   *     900,000-999,999; reserved for the Core Rules project.
   *     1,000,000 and above; unused (available for reservation).

Installing custom rules

Step 1) Create your custom rules:

mkdir /etc/httpd/modsecurity.custom.d

Step 2) Create a configuration file for your custom rules in /etc/httpd/conf.d directory. For example:

Create the file 01_modsecurity.conf and add this line to it:

Include modsecurity.custom.d/99_zzz_custom.conf

You can download an example file from the URL below that will do this:

01_modsecurity.conf

And add it to this directory:

/etc/httpd/conf.d

If you have wget installed on your system, the following commands will do this automatically for you:

cd /etc/httpd/conf.d

wget https://www.atomicorp.com/examples/01_modsecurity.conf

Note: If you are using a control panel that does not follow the file system standards for Linux, such as cpanel, you will need to add these files to different locations on your system. Please contact your control panel vendor for assistance.

Step 3) Install your custom rules in the /etc/httpd/modsecurity.custom.d directory

cd /etc/httpd/modsecurity.custom.d

and edit the file 99_zzz_custom.conf and put in your custom rules.

You can also download an example custom rule file by running these commands:

cd /etc/httpd/modsecurity.custom.d

wget https://www.atomicorp.com/examples/99_zzz_custom.conf

Step 4) Test your apache configuration

service httpd configtest

If you have any errors, do not restart apache. You will need to correct these errors or apache will not start.

Step 5) If your test was successful, restart apache.

service httpd restart

Our professional services group would be happy to help you with your custom rules needs, including developing the rules for you. If your request is something that we can safely include in the rules for all our customers, we're generally able to develop these new rules for free. Please contact us to discuss your rules needs.

Configuring and Setting up mod_security

If you are running ASL you do not need to do this. ASL will setup and manage mod_security for you. The page linked to below is only for non-ASL customers that must setup mod_security manually.

To setup and configured modsecurity, please see the Atomic_ModSecurity_Rules wiki page.