How to install ScallyWhack

Requirements

In order to make use of ScallyWhack the following requirements must be met:

• mod_security 2.x, which in return requires:
  • Apache 2.x
  • mod_unique_id
  • optional: libxml2

• optional: mod_include (only needed for custom error pages, see below)

Installation

In the following it is assumed that the Apache2 configuration directory is /etc/apache2, that the root directory of your webserver/vhost is in /var/www and that Apache runs as user www-data and group www-data.

Your mileage may vary, adjust the instructions where necessary.

1. Download ScallyWhack and unpack the archive if necessary.
2. Create the directory /etc/apache2/scallywhack and copy modsecurity_sw_*.conf there.
3. Carefully read /etc/apache2/scallywhack/modsecurity_sw_10_config.conf and adjust it where necessary.
4. Add the following line to your Apache2 configuration (either in the main configuration or that of the virtual host you want to enable ScallyWhack for):
   Include /etc/apache2/scallywhack/*.conf
5. Reload Apache. Make sure your websites still work as they used before you've enables ScallyWhack.
6. Try to mimic spam submissions and see whether ScallyWhack blocks them as it should. Make sure you restart your webbrowser before you begin to test (otherwise Trac might still recognize you as legitimate user). Remember that you should NOT log in to Trac, as most rules don't apply to users with login.
7. If your tests went positive: congrats, your Trac site is now protected by ScallyWhack. Don't forget to check for updated rules from time to time.

Optional: Extended Audit Logs

To enable extended audit logs, read the file modsecurity_sw_21_extended_audit.conf, then edit it to uncomment the last lines as explained in the comments found in that file.

Optional: Custom Error Pages

ScallyWhack rules might also affect legitimate users - some by design, some by error. Therefore it's a good idea to show error messages that give details to your users what happened, why they have been blocked, what they can do to work around the issue and how they could notify you about it.

Apache offers a way to use custom error pages, and in combination with mod_include these can pretty easily be used for the above mentioned purpose. ScallyWhack comes with a custom error page for error 403 which shows information about the particular rule that blocked a request.

To make use of this feature:

1. If not done yet, enable mod_include in your Apache2.

2. Copy the errorpages/ directory and all it's contents to /var/www.

3. Run the following two commands to adjust ownership and access rights:
   chown -R www-data:www-data /var/www/errorpages
   chmod ug+x /var/www/errorpages/error403.html

4. Edit /var/www/errorpages/contact-advertise.html - spam-related rules result in an explanation a la "we don't like spam, but we might be willing to accept payed advertisements, contact us at ...". The content of contact-advertise.html is included to show contact information for those interested in such an option.

5. Edit /var/www/errorpages/contact-webmaster.html - this is the contact e-mail of the webmaster. Legitimate users who are accidentally affected by ScallyWhack are asked to get in contact to report a possibly misbehaving rule.

6. Edit /etc/apache2/scallywhack/modsecurity_sw_10_config.conf and uncomment the relevant configuration directives (search for "ErrorDocument")

7. Restart Apache2. Trigger one of the rules and see if the server displays the custom error page.