Atomic ModSecurity Rules
From Atomicorp Wiki
Atomic Secured Linux includes the GotRoot.com/Atomicorp Modsecurity Rules.
If you are a full ASL subscriber, you do not need this subscription. ASL will manage all of this for you.
These docs are targeted at users that need to configure the rules for non-ASL environments.
[edit] About the rules
The gotroot.com rules are written by us - we are the gotroot guys. Same great rules, same team. gotroot.com is our Information Assurance lab and Atomicorp is the product arm of Prometheus Global (the parent company for both). So when you get the gotroot.com rules from atomicorp.com or gotroot.com - you're getting the same rules from the same people that created, write and maintain them. In the future we will be merging the gotroot.com, atomicrocketturtle and atomicorp websites into the atomicorp.com website.
Installation of the rules assumes a certain level of comfort with configuring apache. If you are not comfortable with configuring apache, you should contact someone that is, or use our [Atomic Secured Linux] product which does this for you, and does not require you to configure apache.
[edit] Real Time Rule Support
If you have a subscription to the real time rules, you can request email support by sending an email to:
support@atomicorp.com
The Customer Support Forums are located here (you can post here, but these forums are for the labs and free rules, if you post the customer forums the support team monitors those forums regularly):
And the Custom Support Portal is located here (you can submit bug reports and open cases through the portal):
You will need to request a portal account the first time you access the portal. Support accounts are issued manually by checking the status of a customers account and the process may take some time if the office is closed. In the future, the process will be completely automated when a new sign up occurs.
[edit] ModSecurity 2.5 download
If you are running ASL - do not manually install modsecurity. Use the modsecurity rpms we include with ASL.
You can also build modsecurity from source. We do not support source installs of modsecurity. To download the source for modsecurity please visit this website:
http://sourceforge.net/projects/mod-security/
[edit] ModSecurity Rules download
If you have not already setup a subscription for the RealTime feed, you can do so here (its only $79.95 a year):
Once your account is setup, you can download the Real Time rules from here:
For other users, you can download the Free Delayed/Unsupported feed below. Keep in mind the Delayed feed is released 30 days after the realtime feed (that includes any fixes).
Delayed/Unsupported Feed Download
If you want to try out Atomic Secured Linux (ASL) or the RealTime feed on a trial basis, please send an email to sales@atomicorp.com and we'll set you up an account!
[edit] The differences between the Real Time and Delayed Feeds
The Real Time feed is available via subscription, it includes the latest updates we produce on a daily basis and any fixes. The Real Time feed comes with support to help you with any issues you may experience with the rules, including fixing false positives. When false positives are reported to us we generally get an update out the same day. So no more hassles working with modsecurity if you use the Real Time feed!
The Real Time feed also comes with an unsupported rules updater. It works for most systems, but because every system differs we can't know for sure if it will work with your modsecurity setup. If you need support for a rules updater then you are encouraged to upgrade to the full Atomic Secured Linux package which includes a fully intergrated automatic rules updater, rules management tools, SIM, web based GUI, real time malware prevention, the strongest kernel security on the market, FTP and web malware protection, built in vulnerability scanner/auto-fix system and more!
The Delayed Feed is a free version of the Real Time feed and is released on a delayed schedule of at least 30 days. It does not include any support.
Note: Atomic Secured Linux includes the Real Time feed.
[edit] Licenses
The Real Time Atomic ModSecurity Rules are licensed by the server. For each license you can also run the rules on one Development and one QA server.
If you require additional licenses please log into the AtomiCorp License Manager. You can add additional systems there, you can control your payment methods and you can also sign up to become an affiliate.
You can run the Free/Delayed rules on as many systems as you like.
[edit] Setting up modsecurity 2.5.x
Assuming you have modsecurity 2.5.x installed (if you do not have 2.5.11 or higher installed, these rules will probably not work for you and you are encouraged to install 2.5.11 or higher), you will want to create these directories as root:
mkdir /etc/httpd/modsecurity.d mkdir /var/asl mkdir /var/asl/tmp mkdir /var/asl/data mkdir /var/asl/data/msa mkdir /var/asl/data/audit mkdir /var/asl/data/suspicious
Then set the following permissions on these directories as follows below. In this example these directories are set to be owned by "apache" and the group "apache", which is standard on a normal Centos or RHEL system. However some control panels configure apache to run as a different user, such as nobody, or http. Check your system to see what user your system uses. You can use this command to find the user:
ps auxwww | grep httpd
The output will look similiar to this:
(RHEL/Centos example with or without Plesk)
root 26755 0.0 4.3 430752 86432 ? Ss 04:30 0:01 /usr/sbin/httpd apache 26908 0.0 3.7 300564 75076 ? S 04:30 0:00 /usr/sbin/httpd apache 26909 0.1 5.5 495812 112084 ? S 04:30 0:37 /usr/sbin/httpd apache 26910 0.0 5.3 495424 106672 ? S 04:30 0:23 /usr/sbin/httpd apache 26911 0.1 5.7 495892 114368 ? S 04:30 0:57 /usr/sbin/httpd apache 26912 0.1 5.7 496056 114440 ? S 04:30 0:52 /usr/sbin/httpd apache 26913 0.1 5.5 496604 110692 ? S 04:30 0:57 /usr/sbin/httpd apache 26914 0.0 5.7 499324 116236 ? S 04:30 0:16 /usr/sbin/httpd apache 26915 0.2 5.5 493600 112192 ? S 04:30 1:09 /usr/sbin/httpd apache 26916 0.1 6.4 513760 129992 ? S 04:30 0:30 /usr/sbin/httpd
In this example the user in bold is "apache". This is the user you will want to set the directory permissions to (as in the example below):
chown apache.apache /var/asl/data/msa chown apache.apache /var/asl/data/audit chown apache.apache /var/asl/data/suspicious chmod o-rx -R /var/asl/data/* chmod ug+rwx -R /var/asl/data/*
(RHEL/Centos example with Cpanel)
root 20594 86.8 3.1 255148 181232 ? Ss 11:39 0:04 /usr/local/apache/bin/httpd -k restart root 20611 0.0 3.1 255060 179596 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20612 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20613 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20614 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20615 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20616 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart
In this example from a Centos system running Cpanel the user is "nobody", so you would want to use these commands:
chown nobody.nobody /var/asl/data/msa chown nobody.nobody /var/asl/data/audit chown nobody.nobody /var/asl/data/suspicious chmod o-rx -R /var/asl/data/* chmod ug+rwx -R /var/asl/data/*
These directories must as be created if you use optional rules updater. Create these directories as root and they only need to be accessed by root:
mkdir /var/asl/updates mkdir /var/asl/rules/ mkdir /var/asl/rules/clamav
Create this file:
touch /etc/asl/whitelist
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.
Cpanel users should skip to the notes at the bottom of this page for special additional actions for cpanel systems. All other users should continue with these instructions.
You then need to tell apache to load modsecurity. Depending on your apache configuration, apache should be configured to include configuration files. If you have a setting like this in your apache config:
Include conf.d/*.conf
Then you are setup to load external configuration files. If you do not have this setup, its highly recommend you do this. This installation guide is written for this type of configuration. Loading mod_security occurs by including a modsecurity.conf file in that directory. We recommend you name the name 00_modsecurity.conf to ensure it runs first. Its vitally important that modsecurity load before other modules, otherwise attacks can occur before modsecurity scans them and some attacks can be missed.
An example 00_modsecurity file that works with our files is included here:
LoadModule security2_module modules/mod_security2.so LoadModule unique_id_module modules/mod_unique_id.so <IfModule mod_security2.c> Include modsecurity.d/modsecurity_crs_10_config.conf Include modsecurity.d/*asl*.conf </IfModule>
Install this file in your conf.d directory. On a standard RHEL or Centos system that directory is located here:
/etc/httpd/conf.d/
You then need to create your modsecurity_crs_10_config.conf. Here is an example file that also works with our rules:
SecRuleEngine On SecRequestBodyAccess On SecResponseBodyAccess On SecResponseBodyMimeType (null) text/html text/plain text/xml SecResponseBodyLimit 2621440 SecServerSignature Apache SecComponentSignature 200911012341 SecUploadDir /var/asl/data/suspicious SecUploadKeepFiles Off SecAuditEngine RelevantOnly SecAuditLogRelevantStatus "^(?:5|4(?!04))" SecAuditLogType Concurrent SecAuditLog logs/audit_log SecAuditLogParts ABIFHZ SecArgumentSeparator "&" SecCookieFormat 0 SecRequestBodyInMemoryLimit 131072 SecDataDir /var/asl/data/msa SecTmpDir /tmp SecAuditLogStorageDir /var/asl/data/audit SecResponseBodyLimitAction ProcessPartial
You will want to install this file in your modsecurity.d directory, which is located here if you follow the instructions above:
/etc/httpd/modsecurity.d
You are now ready to install the rules.
[edit] Installing the rules
If you configure the rules updater, this process should be taken care of for you. If you choose to do this manually, follow the instructions below.
Download the rules to a temporary directory using your favorite download tool. Extract the rules:
tar zxvf /var/asl/updates/modsec-200911012341.tar.gz
Then copy the ASL rules into /etc/httpd/modsecurity.d:
cp modsec/* /etc/httpd/modsecurity.d/
Finally, load the rules. Make sure you have this line in your
Then make sure you have this line are the bottom of 00_modsecurity.conf, if you want to load all the rules:
Include /full/path/to/your/rules/modsecurity.d/*asl*.conf
Or if you want to load some of the rules, make sure you specify only those rule files. For example:
Include /full/path/to/your/rules/modsecurity.d/10_asl_rules.conf Include /full/path/to/your/rules/modsecurity.d/99_asl_jitp.conf
NOTE: If you use this file:
05_asl_scanner.conf
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. You will also to setup the scanner script, written in PERL, which you can download here:
Setup of this tool is not supported in the rules subscription. You will need to install it on your system and ensure that it is working with your apache setup.
Real time malware upload protection is supported in ASL. So if you need realtime malware upload protection (for web, FTP, or even realtime), then upgrade to ASL which highspeed malware upload protection, full support, automatic and hassle free installation, and also protects against HTTP, SSH and FTP uploads and includes our real-time malware detection and prevention system amongst the many features of ASL.
[edit] Testing
Before restarting apache we recommend you test your configuration by running apache with the "configtest" command. On a standard system you can do this by calling your apache init file like this:
/etc/init.d/httpd configtest
If you get errors, check to see that you don't have some extraneous files installed. You should only have these rule files:
05_asl_exclude.conf 05_asl_user_exclude.conf 10_asl_antimalware.conf 10_asl_rules.conf 20_asl_useragents.conf 30_asl_antispam.conf 40_asl_apache2-rules.conf 50_asl_rootkits.conf 60_asl_recons.conf 99_asl_jitp.conf blacklist.txt domain-blacklist.txt domain-spam-whitelist.conf malware-blacklist.txt referer_spam.txt sql.txt trusted-domains.conf whitelist.txt
[edit] Rule Updater
ASL users: DO NOT USE THIS. YOU DO NOT NEED IT. ASL DOES THIS FOR YOU.
The following stand alone rule updater is unsupported and provided as-is. If you require a supported rule update system, then please upgrade to Atomic Secured Linux.
To install the rule updater you need to download the two links above and save them on your server. We recommend you install the rule-updater.sh file in /usr/local/bin and the config file in /etc/asl/. You can use the following commands to do all of this for you.
Log into your server and run these commands:
su - wget http://www.atomicorp.com/installers/rule-updater.sh wget http://www.atomicorp.com/installers/asl-updater.conf cp rule-updater.sh /usr/local/bin chmod u+x /usr/local/bin/rule-updater.sh mkdir /etc/asl cp asl-updater.conf /etc/asl mkdir /var/asl/updates mkdir /var/asl/rules/ mkdir /var/asl/rules/clamav
The you will need to configure the updater with your login credentials for the RealTime feed. You can do that by editing the following file:
/etc/asl/asl-updater.conf
Change the following lines and replace with your username and password (at a minimum):
USERNAME="USERNAME" PASSWORD="PASSWORD"
Remember to leave the quotes.
For some systems, you have to change additional settings (cpanel for example) to get the updater to work with your system. The following are the additional settings, and what they are used for
ASLHOME=/var/asl/
The path for the various log files and database files used by modsecurity.
UPDATEPATH=www.atomicorp.com/channels/rules/subscription
The URL for the rules subscription
U_LOG=$ASLHOME/data/updates-data
The directory to store the updates and to pull them from
WGET=/usr/bin/wget
Path to wget, which is used to download the rules.
MODSEC_RULES_DIR=/etc/httpd/modsecurity.d/
Path to install the rules. Some users may need to change this for there systems. For example, cpanel users may need to change this: /usr/local/apache/conf/modsec_rules/
MODSEC_CONFIG=$MODSEC_RULES_DIR/modsecurity_crs_10_config.conf
The actual modsecurity configuration file. An example file is included above, but your file may be different for your system. You need to make sure this correct as the updater will make changes to this to indicate the version of the rules installed. Careful observers will notice that a VERSION file is downloaded along with the rules, this file is used to configure modsecurity to display the version of the rules installed on the system in modsecurity log messages. This is very helpful to both you, and to us when debugging issues or when false positives are reported. Make sure you have this set correctly.
APACHECTL=/usr/sbin/apachectl
The binary that is used to control apache. The rule updater will download the rules and will reload the rules into apache. modsecurity needs to restart apache to do this (HUPs for example do not load/reload rules)
APACHE_INIT=/etc/init.d/httpd
Path to the apache init script.
RESTART_APACHE=yes # This can be yes, no, or graceful
Method to restart apache. Options are:
Yes - Restart apache, and load the new rules. graceful - Causes the parent process of apache to advise the children to exit after their current request (or to exit immediately if they're not serving anything). The parent re-reads its configuration files (and loads the new rules) and re-opens its log files. As each child dies off the parent replaces it with a child from the new generation of the configuration, which begins serving new requests immediately. no - dont restart apache, and therefore dont load any new rules. Just download them and don't load them.
CLAMAV_DIR=/var/clamav
Where to install the CLAMAV rules.
Once the installer is configured, you can run it with the following command:
/usr/local/bin/rule-updater.sh -u
Last you will want to add in a cronjob to set the updater to run nightly:
crontab -e
Pick a time for your update to run and change MINUTE and HOUR below to that time and paste this into your crontab
MINUTE HOUR * * * /usr/local/bin/rule-updater.sh -u
We update our rules daily, so you do not need to need run the updater more often than once a day. Keep in mind that when the rules change apache will need to restart as modsecurity only loads the rules on restart of apache and does not dynamic load rules while apache is running.
Please report any issues with the rule-updater to support@atomicorp.com.
ASL users: DO NOT USE THIS. YOU DO NOT NEED IT AND WILL BREAK YOUR SETUP.
[edit] Tuning the Rules/Disabling Rules
See the mod_security page for details.
[edit] Troubleshoot the Rules
See the Atomicorp WAF Rules Troubleshooting page for details.
[edit] Reporting False Positives
See the Reporting False Positives page for details.
[edit] Special notes for CPANEL users not using ASL
Cpanel also includes a very minimal configuration for modsecurity and does not include all of the required and optimal settings documented here. Therefore its critical that if you use mod_security with Cpanel you most add these additional settings to experience the full feature set of mod_security.
If you are using our module and configuration files with cpanel - or you are using ASL with cpanel - then you do not need to follow any of these notes.
These installation notes are reguired for users that choose to use cpanels modsecurity module and configuration files with our rules.
Cpanel includes its own modsecurity configuration files and its own modsecurity module. These should be able to work just with our rules if they are configured correctly according to this page, and if you are using at least version 2.5.11 of modsecurity.
Make sure you have all of the settings on this page to use modsecurity with cpanel correctly, failing to do that will make it impossible for us to support you and modsecurity will not work correctly exposing your system to attack.
A typical cpanel configuration file looks like this:
LoadFile /opt/xml2/lib/libxml2.so LoadFile /opt/lua/lib/liblua.so LoadModule security2_module modules/mod_security2.so <IfModule mod_security2.c> SecRuleEngine On # See http://www.modsecurity.org/documentation/ModSecurity-Migration-Matrix.pdf # "Add the rules that will do exactly the same as the directives" # SecFilterCheckURLEncoding On # SecFilterForceByteRange 0 255 SecAuditEngine RelevantOnly SecAuditLog logs/modsec_audit.log SecDebugLog logs/modsec_debug_log SecDebugLogLevel 0 SecDefaultAction "phase:2,deny,log,status:406" SecRule REMOTE_ADDR "^127.0.0.1$" nolog,allow Include "/usr/local/apache/conf/modsec2.user.conf" </IfModule>
This configuration is missing several important and key directives, so you will need to change it to this:
LoadFile /opt/xml2/lib/libxml2.so LoadFile /opt/lua/lib/liblua.so LoadModule security2_module modules/mod_security2.so <IfModule mod_security2.c> SecRuleEngine On # See http://www.modsecurity.org/documentation/ModSecurity-Migration-Matrix.pdf # "Add the rules that will do exactly the same as the directives" # SecFilterCheckURLEncoding On # SecFilterForceByteRange 0 255 SecRequestBodyAccess On SecResponseBodyAccess On SecResponseBodyMimeType (null) text/html text/plain text/xml SecResponseBodyLimit 2621440 SecServerSignature Apache SecComponentSignature 201001051959 SecUploadDir /var/asl/data/suspicious SecUploadKeepFiles Off SecAuditEngine RelevantOnly SecAuditLogRelevantStatus "^(?:5|4(?!04))" SecAuditLogType Concurrent SecAuditLog logs/modsec_audit.log SecAuditLogParts ABIFHZ SecArgumentSeparator "&" SecCookieFormat 0 SecRequestBodyInMemoryLimit 131072 SecDataDir /var/asl/data/msa SecTmpDir /tmp SecAuditLogStorageDir /var/asl/data/audit SecResponseBodyLimitAction ProcessPartial SecDataDir /var/asl/data/msa SecDefaultAction "phase:2,deny,log,status:406" SecRule REMOTE_ADDR "^127.0.0.1$" nolog,allow Include "/usr/local/apache/conf/modsec2.user.conf" </IfModule>
We've highlighted the changes in italics. Cpanel users will need to manually verify that the mod_unique_id module is loaded by cpanel's apache.
Loading rules occurs through this file:
/usr/local/apache/conf/modsec2.user.conf
For example, if you want to load all the ASL rules, add this line to the bottom of modsec2.user.conf:
Include /full/path/to/your/rules/modsecurity.d/*asl*.conf
If you want to load just some of the rules, make sure you specify only those rule files. For example:
Include /full/path/to/your/rules/modsecurity.d/10_asl_rules.conf Include /full/path/to/your/rules/modsecurity.d/99_asl_jitp.conf
NOTE: If you use this file:
05_asl_scanner.conf
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 forces 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.
You will have to adjust the path to the specific location you choose for your system. Another option is to use symlinks to create the same directories in different locations. This is a typical cpanel path, but check your system to make sure it is correct:
/usr/local/apache/conf/modsec2.user.conf
Cpanel users will also want to change this variable in /etc/asl/asl-updater.conf:
From:
MODSEC_CONFIG=$MODSEC_RULES_DIR/modsecurity_crs_10_config.conf
To:
MODSEC_CONFIG=/usr/local/apache/conf/modsec2.conf
Check to make sure this is the correct location of this file for your system.
Cpanel also does not run apache as a standard user (such as apache) but as the older non-priviliged user "nobody". You will need to ensure then that the work directories that mod_security uses are owned by the user that Cpanel runs apache as. To find this out you can run this command as root:
ps auxwww | grep httpd
root 20594 86.8 3.1 255148 181232 ? Ss 11:39 0:04 /usr/local/apache/bin/httpd -k restart root 20611 0.0 3.1 255060 179596 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20612 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20613 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20614 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20615 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart nobody 20616 0.0 3.1 255148 180224 ? S 11:39 0:00 /usr/local/apache/bin/httpd -k restart
In this example from a Centos system running Cpanel the user is "nobody", so you would want to use these commands:
chown nobody.nobody /var/asl/data/msa chown nobody.nobody /var/asl/data/audit chown nobody.nobody /var/asl/data/suspicious chmod o-rx -R /var/asl/data/* chmod ug+rwx -R /var/asl/data/*
