Difference between revisions of "Mod security"
m (→Changing a range of rules ot be detect only by ID) |
m (→For Plesk based systems) |
||
Line 176: | Line 176: | ||
==== Disabling Mod_security per domain for an IP address ==== | ==== Disabling Mod_security per domain for an IP address ==== | ||
+ | |||
+ | ===== For a list of IPs or CIDRs ===== | ||
+ | |||
+ | ====== Linux ====== | ||
+ | |||
+ | To disable a specific rule for a specific IP or network range follow this process: | ||
+ | |||
+ | Step 1. Create the file: | ||
+ | |||
+ | /etc/custom_ips | ||
+ | |||
+ | Step 2: Add IPs or CIDRs to the /etc/custom_ips file | ||
+ | |||
+ | The format is one IP or CIDR per line, for example: | ||
+ | |||
+ | 1.2.3.4 | ||
+ | 1.2.4.0/24 | ||
+ | |||
+ | Regular expressions are not supported. You must use either an IP address or a CIDR. | ||
+ | |||
+ | Step 3. Add the following custom rule to your custom rules file: | ||
+ | |||
+ | ''SecRule REMOTE_ADDR ""@ipMatchFromFile /etc/customips" "id:1234,phase:1,t:none,nolog,pass,noauditlog,ctl:ruleRemovebyID=350000"'' | ||
+ | |||
+ | Note: Change the variable in the example above from 350000 to the rule ID you want to disable for these IPs. | ||
+ | |||
+ | Step 4. Change the Rule ID. | ||
+ | |||
+ | This is absolutely required. No two rules can have the same ID. See this article for chosing a custom rule id: https://wiki.atomicorp.com/wiki/index.php/Mod_security#Rule_Ids_for_custom_rules | ||
+ | |||
+ | In the example above which is 1234, to a unique id that is not being used by your system. | ||
+ | |||
===== For Plesk based systems ===== | ===== For Plesk based systems ===== |
Revision as of 16:45, 17 November 2023
Installing modsecurity Rules
Please see this article:
Tuning and managing modsecurity Rules
Disabling Rules
Important Notes
phase:1 rules
Note: ASL/AWP/AEO users should disable rules from the rule manager. There is no need to create custom rules, apache configuration files or other customizations when using ASL/AWP/AEO, and ASL/AWP/AEO supports disabling any rule on both a global and per domain basis.
For non-ASL users, LocationMatch and Location do not work for phase:1 rules. Location and LocationMatch are not available in apache until phase:2. If you need to disable a phase:1 rule, use ASL/AWP/AEO which can disable phase:1 rules on a per domain and global basis.
If you are not using ASL/AWP/AEO, and need to disable a phase:1 rule, you will need to create a custom rule to do this. This following is an example of a custom rule to do this for rule 123456.
SecRule REQUEST_HEADERS:Host "example.com$" "phase:1,id:91001,t:none,t:lowercase,pass,nolog,noauditlog,ctl:ruleRemovebyID=123456"
In the example above, "example.com" is the domain to exclude this rule. This custom rule must be loaded before the rule you want to disable. This custom rule *must be loaded before the rule you wish to disable*.
If you do not know how to create this kind of custom rule, please contact support and we'll put a quote together to help develop these custom rules for you.
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
Step 3) Restart apache
service httpd restart
Set a URL to alert only
Step 1) Create a global exclude file
vim /etc/httpd/modsecurity.d/00000_custom_exclude.conf
Step 2) Add a custom rule
In this example the URL is: /foo/bar
Add this line to the file you created in Step 1:
SecRule REQUEST_URI "/foo/bar" "phase:1,id:1000000,t:none,t:lowercase,pass,nolog,noauditlog,ctl:ruleEngine=DetectionOnly"
Important Note: See the section customizing rules below to pick a unique id for your rule above. Duplicate rule ids will cause the rule to not load.
Step 3) Restart apache
service httpd restart
Per domain
Disabling Mod_security per domain
Note: If you only want to disable a specific rule for a domain, please see this article:
https://wiki.atomicorp.com/wiki/index.php/Mod_security#Per_application
For Plesk Based Systems
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
For Cpanel based systems with EasyApache 4
For full information about include file path expectations, see the official cPanel documentation at Modify Apache Virtual Hosts with Include Files
Step 1) Create the following paths, replacing <user> and <domain> with the correct values for your needs:
- mkdir -p /etc/apache2/conf.d/userdata/ssl/2_4/<user>/<domain>
- mkdir -p /etc/apache2/conf.d/userdata/std/2_4/<user>/<domain>
Step 2) In each of the above paths, create a file named 'vhost.conf'
Step 3) Add in the lines below to this file:
<IfModule mod_security2.c> SecRuleEngine Off </IfModule>
Step 4) After any addition, modification or removal of userdata files, cPanel requires both of the following scripts to be run:
- /usr/local/cpanel/scripts/rebuildhttpdconf
- /usr/local/cpanel/scripts/restartsrv_httpd
For Cpanel based systems with EasyApache 3
Step 1) Create the custom modsecurity configuration directory for the domain
For example, if the domain is example.com, you would need to create this directory:
mkdir /usr/local/apache/conf/userdata/std/2/username/example.com
Step 2) Create the file vhost.conf in this directory
cd /usr/local/apache/conf/userdata/std/2/username/example.com
touch vhost.conf
Step 3) Add in the lines below to this file:
<IfModule mod_security2.c> SecRuleEngine Off </IfModule>
Step 4) Run the vhost includes script, for example if the domains username is "example":
/scripts/ensure_vhost_includes --user=example
Disabling Mod_security per domain for an IP address
For a list of IPs or CIDRs
Linux
To disable a specific rule for a specific IP or network range follow this process:
Step 1. Create the file:
/etc/custom_ips
Step 2: Add IPs or CIDRs to the /etc/custom_ips file
The format is one IP or CIDR per line, for example:
1.2.3.4 1.2.4.0/24
Regular expressions are not supported. You must use either an IP address or a CIDR.
Step 3. Add the following custom rule to your custom rules file:
SecRule REMOTE_ADDR ""@ipMatchFromFile /etc/customips" "id:1234,phase:1,t:none,nolog,pass,noauditlog,ctl:ruleRemovebyID=350000"
Note: Change the variable in the example above from 350000 to the rule ID you want to disable for these IPs.
Step 4. Change the Rule ID.
This is absolutely required. No two rules can have the same ID. See this article for chosing a custom rule id: https://wiki.atomicorp.com/wiki/index.php/Mod_security#Rule_Ids_for_custom_rules
In the example above which is 1234, to a unique id that is not being used by your system.
For Plesk based systems
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
For cpanel based systems
Step 1) Create the custom modsecurity configuration directory for the domain
For example, if the domain is example.com, you would need to create this directory:
mkdir /usr/local/apache/conf/userdata/std/2/username/example.com
Step 2) Create the file vhost.conf in this directory
cd /usr/local/apache/conf/userdata/std/2/username/example.com
touch vhost.conf
Step 3) Add in the lines below to this file:
<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.
Step 4) Run the vhost includes script, for example if the domains username is "example":
/scripts/ensure_vhost_includes –user=example
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 hostname into the Text box on the left side of the options you want to exclude the rule for, 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, or a regular expression *.example.com.
Note: You can use regular expressions in this field, but each end of the expression is anchored.
Method 2: Run this command as root:
In ASL v3.x:
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
In ASL v4:
asl -drv RULE_ID[,RULE_ID...] VHOST[,VHOST...] or asl --disable-rule-vhost RULE_ID[,RULE_ID...] VHOST[,VHOST...] All supplied rules will be disabled on all supplied vhosts.
asl -drv 111111,222222,333333 www.example.com,ftp.example.com,example.com
If you do not have ASL installed you will have to do this manually:
Step 1) Edit your domains vhost.conf file (the location of this file will vary based on your control panel, contact your control panel vendor for assistance)
vim 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>
Non Control Panel systems
For nginx, or phase:1 rules rules can be disabled for a domain/FQDN by adding a custom rule before the rule you wish to disable is loaded. For example, if you wanted to disable rule 123456 for domain example.com, you would add this rule to your custom rules:
SecRule REQUEST_HEADERS:Host "example.com$" "phase:1,id:91001,t:none,t:lowercase,pass,nolog,noauditlog,ctl:ruleRemovebyID=123456"
This method can also be used for Apache.
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 modsecurity for a specific web application
Note: this is not recommended
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 modsecurity for the application /foo/bar.cgi you would add a custom rule like this:
<LocationMatch /foo/bar.cgi> SecRuleEngine Off </LocationMatch>
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 single domain or FQDN
For non control panel systems
If you are using any of our GUI products, just click on the rule event, and type in the domain or hostname you want to exclude for this rule.
For DIY users, you will need to create custom rules that load *before* the rule that you wish to exclude. This means you will need to add a custom rule file that loads before the rules we supply.
Once you have set this up for your DIY modsecurity configuration, you will add a rule that inspects the Host: header sent by the client, which will the disable the rule(s) you wish to disable when that field is populated by that value. Keep in mind this field is completely controlled by the client, not the server. In the example below, the entire domain "example.com" is excluded for rule 123456:
SecRule REQUEST_HEADERS:Host ".example.com$" "phase:1,id:91010,t:none,t:lowercase,pass,nolog,noauditlog,ctl:ruleRemovebyID=123456"
Then restart the web server to apply this custom exclusion.
For Plesk systems
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.
Disable rule for a specific argument for a specific application
You can also tell modsecurity to change a rule, in some cases, without editing or forking the rule. For example, if you want to configure modsecurity to ignore a specific argument (in the argument below the argument is "foo"), for a specific application (in the example the application name is /example/application), for a specific rule (in the example below the rule if is 12345), you would create a custom rule like this:
SecRule REQUEST_URI "^/example/application" \ "id:9999,phase:1,t:none,t:lowercase,nolog,pass,ctl:ruleRemoveTargetByID=12345;ARGS:foo"
As with all custom rules, this rule also needs a unique id as explained in the article above. And this type of custom rule must be loaded before the rule it modifies.
Note: This does not support regular expressions for the excluded argument. At this time, they must be explicitly defined.
Disable rule for a specific argument
As is the example above, a rule can also be changed to exclude a specific argument, but for all applications. For example, if you want to configure modsecurity to ignore a specific argument (in the argument below the argument is "foo"), for a specific rule (in the example below the rule if is 12345), you would create a custom rule like this:
SecAction "phase:1,id:9999,t:none,auditlog,nolog,pass,ctl:ruleRemoveTargetById=12345;ARGS:foo"
As with all custom rules, this rule also needs a unique id as explained in the article above. And this type of custom rule must be loaded before the rule it modifies.
Note: This does not support regular expressions for the excluded argument. At this time, they must be explicitly defined.
Disable modsecurity for a specific argument
As is the example above, modsecurity can also be configured to exclude a specific argument for all rules. For example, if you want to configure modsecurity to ignore a specific argument (in the argument below the argument is "foo"),you would create a custom rule like this:
SecAction "phase:1,id:9999,t:none,auditlog,nolog,pass,ctl:ruleRemoveTargetById=1-1000000;ARGS:foo"
When 1-100000 is the rule IDs you want to exclude. As with all custom rules, this rule also needs a unique id as explained in the article above.
Note: This does not support regular expressions for the excluded argument. At this time, they must be explicitly defined.
Changing the action for a rule
You can also change the default action for a rule by using the SecRuleActionById directive.
Changing a rule to be detect only by ID
To change a rule to only detect, but not block attacks, simply change the action for the rule with the above directive. For example, to change the action for rule 12345, simply add this rule directive to your custom rules.
SecRuleUpdateActionById 12345 "pass,status:200"
Note 1: this directive must be added after the rule it is modifying has been loaded.
Note 2: This does not work if you are using the redirect action.
Changing a range of rules to be detect only by ID
This is similar to the method above, however you can define a range of rule IDs. For example, if you want to disable rules 1000-2000:
SecRuleUpdateActionById 1000-2000 "pass,status:200"
Note 1: this directive must be added after the rule it is modifying has been loaded.
Note 2: This does not work if you are using the redirect action.
Disabling POST inspection for a specific URL
Should you want to disable inspection of a POST for a specific URL, use the format below.
Assuming the URL you wanted to skip POST inspection was "upload", your exclusion rule would look like this:
SecRule REQUEST_URI "^/upload" \
"phase:1,id:1234567,t:none,t:lowercase,pass,nolog,ctl:requestBodyAccess=off"
Install this rule before any of your other rules. For example, in the file /etc/httpd/modsecurity.d/00_custom_exclude.conf.
Enabling rules for only specific domains
If you wish to disable all the rules, except for specific domains, you need to copy in the two files from the subdirectory "special" where you have the rules installed. Then create this file:
/etc/asl/custom_include_domains
Include the domains and/or FQDNs you want the rules to apply to. Anything not on that list will cause those rules to skip all of our rules.
- File must contain exactly one domain or FQDN per line. End of line markers (both LF and CRLF) will be stripped from each phrase and any whitespace trimmed from both the beginning and the end. Empty lines and comment lines (those beginning with the # character) will be ignored.
- This file does not support metacharacters. (For example, * is not supported)
Example:
www.example.com .foo.com
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 and/or this option has not been enabled.
Warning: Enabling this capability will allow users to disable rules, including on compromised accounts which may cause the system to become compromised. This capability was specifically disabled by default in modsecurity to prevent this from occurring. Use this option with extreme caution!
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.
Changing the argument separator
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
Linux
Apache
Step 1) Create your custom rules directory:
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:
And add 01_modsecurity.conf 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.
Windows
IIS
Step 1) Modify your modsecurity configuration file on windows and add this line to the end of your configuration. For example:
Include 99_zzz_custom.conf
Step 2) Edit the file 99_zzz_custom.conf and save it in the same directory as your modsecurity config file
Step 3)Restart IIS
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.
Modifying a rule
If you want to modify the internal logic of a rule, you will want to "fork" or copy that rule into a custom rule. Do not modify the actual rules provided by us, your modifications will be overwritten with the next update.
Step 1: Copy the rule you want to modify into your custom rules file.
Copy the rule in its entirety into your custom rule file. For example, if you wanted to modify rule 390707, you would copy the entire rule into your custom rules file. For example:
# Restrict the maximum number of arguments in a request SecRule &ARGS "@gt 1000" \ "chain,phase:2,t:none,log,auditlog,deny,status:403,msg:'Atomicorp.com WAF Rules: Too many arguments in request (max set to 1000, increase as necessary for your system)',id:'390707',severity:'4',rev:'8'" SecRule REQUEST_URI "!((?:^/(?:imaclean|massdelete)/)|^/cgi-bin/dada/mail\.cgi$|^/index\.php/mageworx/customoptions_options|^/za/|^/back-?office/|^/moderate\.php|^/backend/configdomains\.php|\.do$|^/admin[a-z0-9]+?/index\.php\?controller=adminmodules)" "t:none,t:lowercase"
Step 2: Change the rule id.
This is absolutely required. No two rules can have the same ID. See this article for chosing a custom rule id: https://wiki.atomicorp.com/wiki/index.php/Mod_security#Rule_Ids_for_custom_rules
For example:
# Restrict the maximum number of arguments in a request SecRule &ARGS "@gt 1000" \ "chain,phase:2,t:none,log,auditlog,deny,status:403,msg:'Atomicorp.com WAF Rules: Too many arguments in request (max set to 1000, increase as necessary for your system)',id:'12345678',severity:'4',rev:'8'" SecRule REQUEST_URI "!((?:^/(?:imaclean|massdelete)/)|^/cgi-bin/dada/mail\.cgi$|^/index\.php/mageworx/customoptions_options|^/za/|^/back-?office/|^/moderate\.php|^/backend/configdomains\.php|\.do$|^/admin[a-z0-9]+?/index\.php\?controller=adminmodules)" "t:none,t:lowercase"
Step 3: Disable the original rule
If you want your custom rule to be global, that is your modification applies to the entire system, then you will want to disable the original rule per this article:
https://wiki.atomicorp.com/wiki/index.php/Mod_security#Disable_a_rule_for_all_domains
If you want to disable the rule for a single application, see this article:
https://wiki.atomicorp.com/wiki/index.php/Mod_security#Disable_a_rule_for_a_specific_web_application
If you want to disable the rule for a specific IP or network:
https://wiki.atomicorp.com/wiki/index.php/Mod_security#Disable_a_rule_by_IP_or_network
If you want to disable the rule for a single domain:
https://wiki.atomicorp.com/wiki/index.php/Mod_security#Disable_a_rule_for_a_single_domain
Step 4: Set the scope of the rule.
If you havent disabled the original rule globally, or for one or more domains, then you will need to set the scope of your custom rule. To limit your modification to a specific application, place your custom rule inside <LocationMatch> tags. For example:
<LocationMatch /url/to/your/custom/application> # Restrict the maximum number of arguments in a request SecRule &ARGS "@gt 2048" \ "chain,phase:2,t:none,log,auditlog,deny,status:403,msg:'Atomicorp.com WAF Rules: Too many arguments in request (max set to 1000, increase as necessary for your system)',id:'12345678',severity:'4',rev:'8'" SecRule REQUEST_URI "!((?:^/(?:imaclean|massdelete)/)|^/cgi-bin/dada/mail\.cgi$|^/index\.php/mageworx/customoptions_options|^/za/|^/back-?office/|^/moderate\.php|^/backend/configdomains\.php|\.do$|^/admin[a-z0-9]+?/index\.php\?controller=adminmodules)" "t:none,t:lowercase" </LocationMatch>
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.