Debugging Rulesets

Introduction

The ModSecurity module is a filter-plugin for the well-known Apache webserver. It enhances the Apache server with the possibility to define a complex set of rules for filtering bad requests made to the server. There are two major public efforts for creating rulesets which protect web applications against a wide range of attacks.
The first one to note is the core-rules ruleset which is maintained by Breach Security and distributed with the ModSecurity module. This ruleset is highly optimized with a lot of generic attacks being compressed within only a few rules which drastically improves performance (see [1] for some thoughts on ruleset performance).
The other big set of rules is maintained by the gotroot-project. These rules incorporated a lot of attack patterns from the Snort IDS project. (IIRC the bootstrap of those rules were a conversion script from Snort to ModSecurity 1.x rules). The gotroot-rules have a very precise detection rate as they list known attacks one by one and set aside pattern generalization. This results in a huge amount of rules being checked for each request.

Problem Statement

As the rulesets constitute a generic approach on protecting web-sites, there are cases in which rules introduce false alerts on a specific web application. To give an example here simply think of a JSP-wiki which is a wiki-clone written in Java/JSP. This application uses the "¦" character to allow for the user to create a table within a wiki-page. When employing a standard setup of ModSecurity with a generic ruleset, POST-requests with such a character will be alerted as attacks, as scanning for the "¦" is a result of looking for command injections (remember that the "¦" also denotes the pipe-symbol on most systems).
Tracking those kinds of errors can be quite annoying as you will have to check the logs while simultaneously re-send the request that was wronlgy alerted, edit your server configuration and recheck the new setup. For simple applications this can be done with a browser, but more sophisticated ones might require slightly more complex requests to be resent which might in turn require more work. Consider a more detailed POST-form that needs to be re-sent for example.
What I will introduce within the next section is a simple tool that allows for the relevant audit-log to be easily read into a local application (even from a remote server). This event can then precisely be re-sent to check after the you adjusted your configuration.

Reading Remote Audit-Log Data

The current version of the web-audit library [2] includes a small and simple server process that can be used as a continous "remote-tail" of an audit-log file. As a conterpart to this, the AuditViewer is able to connect to the server-process and display the remote logs to the local user. Additionally it allows for the exact reinjection of received events (i.e. requests) into the server. Thus while you steadily monitor your audit-log in a "live-view" manner you can edit your server/rule setup and easily check the new setup by simulating the exact request again. As a side-note here: You can also edit the request before re-injection to try out different contents for the payload, for example. The following picture shows the whole setup for debugging: As shown in the picture, the client-server connection is encrypted, though the system primarily addresses the use in local networks. Currently the AuditServer expects the logfile to be in serial log-format of ModSecurity 2.x. As there are parsers for concurrent audit-logs and ModSecurity 1.x files within the web-audit library these will be incorporated shortly.
I will subsequently go into a step-by-step guidance for showing how easy these thing can be set up.

Debugging Rulesets

The setup consists of two parts: Starting the AuditServer that provides the audit-log data to the AuditViewer and finally starting and connecting the AuditViewer with the server.

Running the Server

The AuditServer is included within the latest version of the web-audit library. For a simple yet sufficient start you can run it on the web-server by issuing

   java -cp org.jwall.web.audit-0.2.9.jar org.jwall.AuditServer /path/to/audit.log

This will start a simple server process that accepts an SSL connection on port 10001. The server expects the client to authenticate itself using the default login "admin" and the password "secret". This can of course be adjusted (see [3] for details).

AuditViewer Client

The counterpart for the server is the AuditViewer application. This Java application can simply be started by double-clicking the provided Jar-Archive on most operating systems (Windows, most Java-Systems, MacOS X). If double-clicking does not work, it can be started by issuing

   java -jar AuditViewer.jar

After the AuditViewer has been started, it allows you to connect to the AuditServer process by pressing . This will ask for username and password and start to connect to the server. Once the connection is established, all events that are appended to the logfile monitored by the server process will be sent to the client and displayed within the "Remote View".