Latest revision as of 18:37, 7 February 2019

[edit] Step 1: Download ModSecurity

https://updates.atomicorp.com/channels/rules/binaries/

Please note that the rules are only supported with the version of modsecurity identified in this section of the wiki.

Note: Please contact us before using a third party or source build of modsecurity. Its critical modsecurity be built correctly to work with the rules.

[edit] Step 2: Install vcreinit

Before installing ModSecurity make sure you have Visual Studio 2013 Runtime (vcredist) installed. Vcredist can be downloaded here: http://www.visualstudio.com/downloads/download-visual-studio-vs (note that, there are two different versions 32 and 64b).

[edit] Step 3: Install modsecurity

Any installation errors or warning messages are logged in the application event log under 'ModSecurityIIS Installer' source.

[edit] Step 4: Set up and configure the modsecurity module in IIS

After the installation the module will be running in all websites by default. To remove it from a website add to web.config:

<modules>
    <remove name="ModSecurityIIS" />
</modules>

To configure module in a website add to web.config:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <ModSecurity enabled="true" configFile="c:\inetpub\wwwroot\modsecurity.conf" />
    </system.webserver>
</configuration>

Where configFile is standard ModSecurity config file.

[edit] Step 5: Configure modsecurity main config file

Create this file in your modsecurity root directory:

modsecurity_iis.conf

This file should include these lines:

Include modsecurity.conf 
Include windows\*asl*.conf 

[edit] Step 6: Configure modsecurity

You then need to configure modsecurity. This is done via the a configuration file. In this example, we will create the file "modsecurity.conf". Here is an example file that works with our rules:

 SecRuleEngine On 
 SecRequestBodyAccess On
 SecRequestBodyLimit 13107200 
 SecRequestBodyNoFilesLimit 131072 
 SecRequestBodyInMemoryLimit 131072 
 SecRequestBodyLimitAction Reject 
 SecPcreMatchLimit 150000 
 SecPcreMatchLimitRecursion 150000 
 SecResponseBodyMimeType text/plain text/html text/xml 
 SecResponseBodyLimit 524288 
 SecResponseBodyLimitAction ProcessPartial 
 SecTmpDir c:\inetpub\temp\ 
 SecDataDir c:\inetpub\temp\ 
 SecAuditEngine RelevantOnly 
 SecAuditLogRelevantStatus "^(?:5|4(?!04))" 
 SecAuditLogParts ABIJDEFHZ 
 SecArgumentSeparator & 
 SecCookieFormat 0 
 SecStatusEngine On 

You will want to install this file in your windows modsecurity directory.

[edit] Step 7: Download the ModSecurity Rules

See the Downloading Rules page.

[edit] Step 8: Create the whitelist file

Create this file in your rules directory

whitelist.txt

This file contains a list of IPs you want to exclude from ALL rules. That means those IPs can do anything to your system - so be very very careful about what IPs you add to this list. This is a dangerous thing to do. The format of the file is a single IP, per line.

Note: On some Windows platforms the @ipmatch system does not work correctly. Some IIS versions will report the remote systems IP in this format:

ip:port

Instead of

ip

On those systems, IP based rules will not work until this bug is fixed by Microsoft.

[edit] Step 9: Install the rules

[edit] Remove any previous installations of rules

If you have installed our delayed rules, you will need to make sure you have deleted them. You will not want to have any older versions of the rules installed.

Also, if you have installed any third party modsecurity rules, you will want to make sure they are using rule id's that are assigned to them. The modsecurity project assigns ranges to the rule id's modsecurity uses. Modsecurity requires a unique id for each rule, otherwise you will get an error like this:

ModSecurity: Found another rule with the same id

This means either that someone else is using the same rule id's assigned to our ruleset by the modsecurity project (our official range is 300000-399999), or you have loaded our rules twice.

[edit] Recommend minimum rulesets

The recommended minimum ruleset to load is:

Include /full/path/to/your/rules/modsecurity.d/00_asl_zz_strict.conf
Include /full/path/to/your/rules/modsecurity.d/00_asl_0_global.conf
Include /full/path/to/your/rules/modsecurity.d/10_asl_antimalware.conf
Include /full/path/to/your/rules/modsecurity.d/10_asl_rules.conf
Include /full/path/to/your/rules/modsecurity.d/11_asl_adv_rules.conf
Include /full/path/to/your/rules/modsecurity.d/12_asl_adv_xss_rules.conf
Include /full/path/to/your/rules/modsecurity.d/20_asl_useragents.conf
Include /full/path/to/your/rules/modsecurity.d/30_asl_antispam.conf
Include /full/path/to/your/rules/modsecurity.d/50_asl_rootkits.conf
Include /full/path/to/your/rules/modsecurity.d/60_asl_recons.conf
Include /full/path/to/your/rules/modsecurity.d/61_asl_recons_dlp.conf
Include /full/path/to/your/rules/modsecurity.d/99_asl_jitp.conf

If you have modsecurity 2.9.0 and up installed, you should also load additional rule files and should use this ruleset:

Include /full/path/to/your/rules/modsecurity.d/00_asl_zz_strict.conf
Include /full/path/to/your/rules/modsecurity.d/00_asl_0_global.conf
Include /full/path/to/your/rules/modsecurity.d/00_asl_z_antievasion.conf
Include /full/path/to/your/rules/modsecurity.d/01_asl_content.conf
Include /full/path/to/your/rules/modsecurity.d/03_asl_dos.conf
Include /full/path/to/your/rules/modsecurity.d/09_asl_rules.conf
Include /full/path/to/your/rules/modsecurity.d/10_asl_antimalware.conf
Include /full/path/to/your/rules/modsecurity.d/10_asl_rules.conf
Include /full/path/to/your/rules/modsecurity.d/11_asl_adv_rules.conf
Include /full/path/to/your/rules/modsecurity.d/11_asl_data_loss.conf
Include /full/path/to/your/rules/modsecurity.d/12_asl_adv_xss_rules.conf
Include /full/path/to/your/rules/modsecurity.d/20_asl_useragents.conf
Include /full/path/to/your/rules/modsecurity.d/30_asl_antispam.conf
Include /full/path/to/your/rules/modsecurity.d/50_asl_rootkits.conf
Include /full/path/to/your/rules/modsecurity.d/51_asl_rootkits.conf
Include /full/path/to/your/rules/modsecurity.d/60_asl_recons.conf
Include /full/path/to/your/rules/modsecurity.d/61_asl_recons_dlp.conf
Include /full/path/to/your/rules/modsecurity.d/99_asl_jitp.conf

Include /full/path/to/your/rules/modsecurity.d/98_asl_adv_redactor.conf

If you have a Local DNS resolver setup and properly configured on your system, and you are using modsecurity 2.9.0 and up we also recommend these additional rulesets:

Include /full/path/to/your/rules/modsecurity.d/00_asl_z_searchengines.conf
Include /full/path/to/your/rules/modsecurity.d/00_asl_z_aa_threat_intelligence.conf
Include /full/path/to/your/rules/modsecurity.d/99_asl_zzzz_threat_intelligence.conf

Note: Some of these rulesets are designed to work with advanced security management systems such as ASL and may not work completely without an advanced management system.

[edit] Notes on Scanner ruleset

Microsoft windows does not support these rulesets:

 99_asl_scanner.conf

 99_asl_z_adv_scanner.conf

ASL includes malware upload scanning, rules subscriptions do not.

If you wish to use this ruleset, and you are not using ASL, then you will need to create a script to pass the files to clamd and read the result. Make sure you have clamd installed and configured correctly to list on a TCP port, or if you use a socket, make sure apache can read/write to this socket or as a last resort, run clamd as root. Using this file will force all web uploads on your system to go thru clamav to look for malware, viruses, etc. If you dont need that, then you can leave this config file out.

Real time malware upload protection is included in ASL and uses a faster method than the older style modsecurity scripting method above. So if you need realtime malware upload protection (for web, FTP, or even realtime), then upgrade to ASL which includes highspeed malware upload protection, full support, automatic and hassle free installation. ASL also protects against any form of upload of malware, including HTTP, HTTPS, SSH and FTP uploads and includes our real-time malware detection and prevention system which will detect and block any malicious software running on the system in realtime. This is just one of the many many features of ASL.

[edit] Step 10: Test your web server

Run iisreset.exe to ensure that IIS restarts. On some systems you may need to stop and restart IIS for your modsecurity configuration to load.

[edit] Testing to see if the rules are loaded

Step 1) (for non ASL systems)

Make sure you have the rules installed exactly as described on this page. This test may not work if you have not followed these instructions. (If you have not installed any third party tools that configure, install or manage modsecurity then your rules are installed correctly and you do not need to review the instructions on this page. If you have manually altered your modsecurity configuration then you will need to review this entire article.)

Step 2) Make sure all rules are enabled

Ensure that you do not have any of our rules disabled. This test assumes you do not have any rules disabled, that you are not whitelisting the source of this test and that your have the Atomicorp rules loaded.

Step 3) Test from a non-whitelisted system

Make sure you do not have the system you are performing this from is whitelisted

For example, cpanels default modsecurity configuration will configure modsecurity to ignore everything from 127.0.0.1, or from the system itself. So if you perform the test above from the server itself, and you have not removed this cpanel whitelist, then this test will not work.

Step 4) Run the test

On a different system from where the rules are installed, and that is not whitelisted, access this url for your system:

http://your_systems_name_or_ip/foo.php?foo=http://www.example.com

If the rules are properly loaded, you should get a 403 error, if you do not get a 403 error, the rules are not loaded correctly and you need to check your configuration to ensure that you have followed the instructions above correctly.

[edit] What to do if you do not get a 403 error

If you get a different error, such as a 404 error or a 5xx series error check your configuration. The following are common causes of this:

1) You have rules disabled

Make sure you do not have any rules disabled.

2) Your IP is whitelisted

There is a rule whitelisting the system you are conducting this test from. Whitelisting tells the WAF to ignore everything from that source.

For example, cpanels default modsecurity configuration will configure modsecurity to ignore everything from 127.0.0.1, or from the system itself. So if you perform the test above from the server itself, and you have not removed this cpanel whitelist, then you will not get a 403 error. More than likely you will get a 404 error. The solution is to remove any whitelists from your system.

Note: Whitelisting the server itself can open a hole in your security. You should not whitelist localhost or the servers own IP address, particularly if you have multi users on the system. This is both unnecessary, and doing so will allow any users on the system to carry out attacks on other domains on the system unimpeded. Make sure you do not have any rules like that, this opens a very large hole in your system.

3) Local error message is different

You or someone else may have configured your system to use a different error message. Check your configuration, and make sure it exactly matches the ones on this wiki. IF you are using kind of plugin that does not return a 403 when a connection is rejected, and you must use this, then you will need to manually check your mod_security logs to see if your test is being rejected by modsecurity. If it is, then your rules are working correctly and you can ignore the error code.

4) Third party addons

You have third party rules or addons installed with your modsecurity configuration that are changing the responses. Remove all third party addons, and make sure your configuration exactly matches the instructions on this page

5) the system is not configured to load the rules

This is common with custom configurations. Check to make sure your webserver is configured to load the rules. Keep mind that modsecurity will still generate generic messages even though the rules are not loaded. For example, if all you see are events like this:

--70c19f31-A--
[01/Jan/2013:11:19:13 --0300] roiKIi6Ni3EKFZSKpSUs2iEb 1.2.3.4 34978 5.6.7.8 80
--70c19f31-B--
HEAD / HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) 

Accept: */*

--70c19f31-F--
HTTP/1.1 403 Forbidden
X-Powered-By: PHP/5.4.20
Expires: Thu, 19 Jan 2001 02:12:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache
Connection: close
Content-Type: text/html

--70c19f31-H--
Stopwatch: 1383338363503919 358184 (- - -)
Stopwatch2: 1383338363503919 358184; combined=2144, p1=37, p2=2053, p3=0, p4=0, p5=53, sr=0, sw=1, l=0, gc=0
Producer: ModSecurity for Apache/2.7.5 ( http://www.modsecurity.org/).
Server: Apache
Engine-Mode: "ENABLED"

--70c19f31-Z--

In this example, no rule is being triggered, but modsecurity is logging a basic 403 error. It will do this if the modsecurity configuration is loaded, but not the rules. So if you see this happening on your system, and you have ruled out all other issues in this list, it means your custom configuration isnt loading the rules.

ASL will automatically configure modsecurity correctly. So if you are having problems configuring modsecurity yourself, then we recommend you use ASL to setup modsecurity for you.