ModSecurity Configuration Guide
Official Statement
ModSecurity is delivered together with nevisProxy as is. Projects and customers are free to use commercial or free rule sets according to their needs. However, Nevis only provides support for the following use cases:
- The integration of ModSecurity in nevisProxy via the ModSecurityFilter.
- The configuration of the ModSecurityFilter, the installation of the OWASP Core Rule Set and the enabling of Paranoia Level 1.
- The exclusion of level 1 rules (if valid requests are blocked).
We keep track of known vulnerabilities of ModSecurity and/or the OWASP ModSecurity Core Rule Set.
- In case of a critical fix of a vulnerability in ModSecurity, we deliver a new nevisProxy release that includes the fixed ModSecurity version.
- In case of known issues with the OWASP ModSecurity Core Rule Set, we will inform our customers. Additionally, we might do further analysis and come up with recommendations for workarounds, but we do not guarantee this.
The nevisProxy product group does NOT provide consulting support for the customization of rule sets in relation to customer specific application environments.
Writing custom rules, or analyzing issues with existing rules (including use cases/attack vectors not being stopped by OWASP CRS PL1), is not being taken care of by the Nevis team.
Configuring ModSecurity for nevisProxy
Configuring the ModSecurityFilter in nevisProxy is a two step process. The first step involves the configuration of the ModSecurity engine that comes with the ModSecurityFilter. The second step is to install and configure an appropriate rule set that gives the ModSecurity engine its detection capabilities. The officially supported rule set for the ModSecurityFilter is the OWASP CRS v3. This configuration guide outlines the required steps to achieve the default installation.
Configuration files
- For the configuration of the ModSecurity engine, you create the modsecurity.conf file.
- For the configuration of the CRS (Core Rule Set), you create the modsec_includes.conf file. This last file includes the modsecurity.conf file and is used as the configuration file for the ModSecurityFilter in nevisProxy.
nevisProxy only supports the default configuration of ModSecurity and the default installation of the OWASP CRS v3. Simple support on how to identify and disable offending rules is also provided. For further customization of the filters and configuration of ModSecurity, consult your Nevis contact person.
ModSecurity configuration
- Create the modsec configuration directory, if it does not already exist:
/var/opt/nevisproxy/modsec. - Download the default modsecurity.conf-recommended file
- Rename the downloaded modsecurity.conf-recommended file to modsecurity.conf. Place this modsecurity.conf file inside the modsec folder that you created in the first step.
- In the modsecurity.conf file, change the value of the SecRuleEngine directive as follows:
#SecRuleEngine DetectionOnly
SecRuleEngine On
The original recommendation is to use ModSecurity for detection only, not to block requests. Use the blocking mode now, it is needed for the examples and tests later.
Core Rule Set installation
- First, you need to download the Core Rule Set from the Spider Labs website. There are two options:
Download the rule set directly, or
Get the rule set via the git command below:
git clone https://github.com/coreruleset/coreruleset.git owasp-modsecurity-crs
- Clone or unpack the rule set directly into the modsec configuration directory. At the end you should have an owasp-modsecurity-crs directory inside
/var/opt/nevisproxy/modsec. - Now follow the instructions in the file
/var/opt/nevisproxy/modsec/owasp-modsecurity-crs/INSTALL, starting from step 5 in the section "Installing on Nginx". The integration of nevisProxy with ModSecurity is similar to Nginx, so this section is also usable for nevisProxy. Exactly follow the instructions in step 5 and step 6. In step 7, skip the "ModSecurityConfig" parts but carry out the "Include lines" part. You can skip step 8 and higher, as you will verify the configuration later.
ModSecurityFilter configuration
- Configure the ModSecurityFilter in your web.xml file. The code snippet below shows a sample configuration:
<filter>
<filter-name>ModSecurityFilter</filter-name>
<filter-class>ch::nevis::nevisproxy::filter::modsecurity::ModsecurityFilter</filter-class>
<filter-lib>libModsecurityFilter.so.1</filter-lib>
<init-param>
<param-name>ConfigFile</param-name>
<param-value>/var/opt/nevisproxy/myproxyinstance/conf/modsec_includes.conf</param-value>
</init-param>
</filter>
- Map the filter to the root to protect every request:
<filter-mapping>
<filter-name>ModSecurityFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Verifying the configuration
To verify your ModSecurity configuration, restart the proxy. If everything is fine, the navajo.log file should include no errors or warnings related to ModSecurity.
If you see an error message similar to the one in the following code block, then just comment out the SecUnicodeMapFile directive in the modsecurity.conf file.
Failed to locate the unicode map file from: unicode.mapping Looking at: 'unicode.mapping', 'unicode.mapping', '/var/opt/nevisproxy/modsec/unicode.mapping', '/var/opt/nevisproxy/modsec/unicode.mapping'. [NVCT-0056]
Testing the configuration
To test the default configuration of the ModSecurityFilter with the OWASP CRS v3 rule set, issue the following request towards your nevisProxy host (assuming it is hosted on localhost, port 8080):
http://localhost:8080/?param="><script>alert(1);</script>"
You can also test it from the command line, without a browser, with the curl command:
curl -v http://localhost:8080/?param="><script>alert(1);</script>"
If everything is fine, the ModSecurityFilter should block this request. A message should be traced in the nevisProxy logs, and you should receive a 403 HTTP status code.
Log examples
In the log example below, ModSecurity logs the exact rule the request was matched against and where it is located:
proxy | 2019 08 29 14:03:59.750 isi3web IW4ModsecF
00664.140036547622656.ac120001-0298-12ac0300-16cddb0af84-00000005 3-ERROR : Modsecurity: [client
172.18.0.1] ModSecurity: Warning. Pattern match "(?i)<[^\\w<>]*(?:[^<>\"'\\s]*:)?[^\\w<>]*(?:\\W*?s\\W*?c\
\W*?r\\W*?i\\W*?p\\W*?t|\\W*?f\\W*?o\\W*?r\\W*?m|\\W*?s\\W*?t\\W*?y\\W*?l\\W*?e|\\W*?s\\W*?v\\W*?g|\\W*?m\
\W*?a\\W*?r\\W*?q\\W*?u\\W*?e\\W*?e|(?:\\W*?l\\W*?i\\W*?n\\W*?k|\\W*?o\\W*?b\\W*?j\\W*?e\ ..." at
ARGS:param. [file "/var/opt/nevisproxy/proxy/modsec/owasp-modsecurity-crs/rules/REQUEST-941-APPLICATIONATTACK-XSS.conf [line "236 [id "941160 [rev "2 [msg "NoScript XSS InjectionChecker: HTML
Injection [data "Matched Data: <script found within ARGS:param: \x22><script>alert(1);</script>
[severity "CRITICAL [ver "OWASP_CRS/3.0.0 [maturity "1 [accuracy "8 [tag "application-multi [tag
"language-multi [tag "platform-multi [tag "attack-xss [tag "OWASP_CRS/WEB_ATTACK/XSS [tag "WASCTC/
WASC-8 [tag "WASCTC/WASC-22 [tag "OWASP_TOP_10/A3 [tag "OWASP_AppSensor/IE1 [tag "CAPEC-242
[hostname "standalone [uri "/ [unique_id "ac120001-0298-12ac0300-16cddb0af84-00000005 [MODS-0001]
In this case the matched rule is in the file /var/opt/nevisproxy/proxy/modsec/owasp-modsecurity-crs/rules/REQUEST-941-APPLICATION-ATTACK-XSS.conf, on line "236" with the rule ID "941160".
The next log example shows the final score assessment when operating in anomaly scoring mode. The final score assessment is just another rule (rule ID: "949110") that checks the overall anomaly score.
proxy | 2019 08 29 14:03:59.751 isi3web IW4ModsecF
00664.140036547622656.ac120001-0298-12ac0300-16cddb0af84-00000005 3-ERROR : Modsecurity: [client
172.18.0.1] ModSecurity: Access denied with code 403 (phase 2). Operator GE matched 5 at TX:anomaly_score.
[file "/var/opt/nevisproxy/proxy/modsec/owasp-modsecurity-crs/rules/REQUEST-949-BLOCKING-EVALUATION.conf
[line "57 [id "949110 [msg "Inbound Anomaly Score Exceeded (Total Score: 15) [severity "CRITICAL
[tag "application-multi [tag "language-multi [tag "platform-multi [tag "attack-generic [hostname
"standalone [uri "/ [unique_id "ac120001-0298-12ac0300-16cddb0af84-00000005 [MODS-0001]
nevisProxy logs the relevant events and error codes in case a request is blocked - see the log example below. This is useful as it allows you to easily extract and parse nevisProxy logs for blocking events. You can use this to troubleshoot false positives.
proxy | 2019 08 29 14:03:59.751 isi3web IW4ModsecF
00664.140036547622656.ac120001-0298-12ac0300-16cddb0af84-00000005 3-ERROR (MS02): Modsecurity: Block
request-body in phase:2, send status 403 to client [MODS-0003]