ModSecurity 2.5: Prevent web application hacking with this easy to use guide

SecRule is the directive that is used to create ModSecurity rules. Its syntax is simple, but don't let that fool you. For almost any scenario you can imagine where you want to process a request in a certain way (whether by denying it, forwarding it or doing some more advanced processing), there is a way to use SecRule to solve the problem.

The basic syntax of SecRule is as follows:

SecRule Target Operator [Actions]

Target specifies what part of the request or response you want to examine. In the basic example given in the previous chapter, we used the variable named REQUEST_URI, which contains the requested URI on the server, to identify and block any attempts to access the location /secret.html. There are over 70 variables that can be used to create rules, meaning there is likely to be a way to match a rule in almost any circumstance where you need to create a rule.

There is also a special kind of variable called a collection that can hold several values. An example of...

Sometimes you want a match to trigger only if several conditions apply. Say for example that our web site owner from the previous example wanted to block the troublesome downloader, but this downloader was also used by other clients where it wasn't misbehaving by downloading the same file over and over. Also, for the sake of argument let's assume that it wouldn't be possible to just block the client's IP address as he was on DSL and frequently appeared with a new address.

What we'd want in this case is a rule that denies the request if the user-agent string contains "Red Bullet" and the IP address of the client belongs to the subnet range of a particular ISP.

Enter the chain action. Using this, we can create a chain of rules that only matches if all of the individual rules in the chain match. If you're familiar with programming, you can think of chained rules as rules with a logical and operator between them—if a single one of them doesn't match then the rule chain...

You can assign an ID number to each rule by using the id action:

SecRule ARGS "login" "deny,id:1000"

This allows the rule to be identified for use with:

The SecMarker directive should be mentioned here. Its purpose is to create a marker, which is essentially a rule with just an ID number, for use with the action skipAfter.

The following example checks to see if the ModSecurity version is at least 2.5, and skips over a set of rules in case an older version that may not support them is installed:

SecRule MODSEC_BUILD "@lt 020500000" "skipAfter:1024"
...
Rules requiring version >= 2.5
...
SecMarker 1024

Regular expressions are an important part of writing ModSecurity rules. That is why this section contains a short introduction to them and why the book also has an appendix that describes them in more detail.

Regular expressions are a very powerful tool when it comes to string matching. They are used to identify a string of interest, and are useful for many different tasks, such as searching through large text files for a given pattern, or, as used in ModSecurity, to define patterns which should trigger a rule match.

Programming languages such as Perl come with regular expression support built right into the syntax of the language (in fact, the PCRE library that was mentioned in the previous chapter that is used by Apache and ModSecurity is a re-implementation of the regular expression engine used in Perl). Even Java's String class has the matches() method which returns true if the string matches the given regular expression.

Regular expressions are so...

You may ask if there isn't a way to match a string that ends with a certain other sub-string, without having to bother with escaping dots and putting dollar signs at the ends of lines. There is actually an operator that does just that—it's called @endsWith. This operator returns true if the targeted value ends with the specified string. If, as in the example above, we wanted to block remote hosts from microsoft.com, we could do it by using @endsWith in the following manner:

SecRule REMOTE_HOST "@endsWith .microsoft.com" deny

If we wanted to negate the above rule, and instead block any domain that is not from Microsoft, we could have done it in the following way:

SecRule REMOTE_HOST "!@endsWith .microsoft.com" deny

It is good practice to use simple string matching whenever you don't need to utilize the power of regular expressions, as it is very much easier to get a regular expression wrong than it is to get unexpected results with simple string matching.

The following...

Both regular expressions and the simple string matching operators work on character strings. As we saw in a previous example, using a regex to match against numbers can be error-prone, and regular expressions can often be cumbersome when you want to match against numbers. ModSecurity solves this problem by providing us with operators that can be used to compare numbers when we know that the arguments we are examining are numeric.

The following are the numerical operators ModSecurity provides:

@eq?

SecRule RESPONSE_STATUS "@eq 200"

@ge?

SecRule RESPONSE_STATUS "@ge 400"

Let's look at some more things that can be done with collections, such as counting the number of items in a collection or filtering out collection variables using a regex.

SecRule &REQUEST_COOKIES "@eq 0"

SecRule &REQUEST_HEADER:User-Agent "@eq 0"

ModSecurity provides a number of transformation functions that you can apply to variables and collections. These transformations are done on a copy of the data being examined, meaning that the original HTTP request or response is never modified. The transformations are done before any rule matching is attempted against the data.

Transformation functions are useful for a variety of purposes. If you want to detect cross-site scripting attacks (see Chapter 6 for more on this), you would want to detect injected JavaScript code regardless of the case it was written in. To do this the transformation function lowercase can be applied and the comparison can then be done against a lowercase string.

To apply a transformation function, you specify t: followed by the name of the function and then put this in the action list for the rule. For example, to convert the request arguments to all-lowercase, you would use t:lowercase, like so:

SecRule ARGS "<script" "deny,t:lowercase...

Let's look at some additional operators that can be used to operate on data. We have already seen the regular expression, simple string comparison and numeral comparison operators earlier, and here we take a look at some additional ones that are available for use.

SecRule ARGS "@pm red green blue" deny

It is important to understand in which order ModSecurity evaluates rules. This makes you more comfortable when creating your own rules and avoids situations where things are unexpectedly blocked or allowed even though you expect the opposite to happen.

We learned in Chapter 1 that the rule engine divides requests into five phases:

Rules are executed strictly in a phase-by-phase order. This means that ModSecurity first evaluates all rules in phase 1 ("request headers") for a match. It then proceeds with phases 2 through 5 (unless a rule match causes processing to stop).

Within phases, rules are processed in the order in which they appear in the configuration files. You can think of the ModSecurity engine as going through the configuration files five times; one time for each processing phase. During each pass, the engine considers only rules belonging...

When a rule matches you have several options: You can allow the request, you can deny it or you can opt to take no action at the moment but continue processing with the next rule. There are also several other things you can do like redirect or proxy requests. In this section you'll learn in more detail about the options that are available.

Using SecAction, you can execute any number of actions unconditionally. The syntax is:

SecAction Actions

As an example, the following SecAction logs a message to the HTTP error log file:

SecAction "pass,log,logdata:'Testing SecAction'"

It is important to specify pass in a SecAction directive, as the default action will be prepended to the action list just as with a normal SecRule. If the default action is to deny the request then the SecAction above would have denied all requests if pass was missing.

The ctl action allows for fine-grained control of the rule engine. Using this action you can configure the engine on a per-transaction basis. The following parameters are supported:

auditEngine

auditLogParts

debugLogLevel

ruleRemoveById

requestBodyAccess

requestBodyLimit

requestBodyProcessor

responseBodyAccess

responseBodyLimit

ruleEngine

You can include data from variables or collections in log messages or when you initialize other variables. This is called macro expansion, and is done by enclosing the variable or collection name in a percent sign and curly braces:

SecAction setenv:ADDR=%{REMOTE_ADDR}

It is important to note that when specifying a collection field in an action list you need to separate the collection name from the field name with a dot and not a colon:

SecRule "test" "log,msg:%{TX.0}"

Macro expansion is not currently supported in all circumstances (for example, the append and prepend actions currently don't support macro expansion).

Alright, now that we have had a look at the theory of writing rules, let's start doing some real work by writing rules for more real-life situations. In this section we will look at several examples of how to write rules and rule chains to accomplish a given task.

ModSecurity can execute an external shell script when a rule matches. This is done via the exec action. This is a very powerful technique that allows you to invoke the full power of your favorite scripting language to take further action when a rule match occurs. You can in fact also invoke a binary program file, though most of the time a shell script will be more convenient to execute.

The invoked file must be executable by the Apache process, so make sure that you set the permissions on the file correctly. One catch when invoking a script is that the script must write something to stdout. If your script doesn't do this, ModSecurity will assume the execution has failed, and you will get the error message Execution failed while reading output in the Apache error log file.

ModSecurity allows us to inject data into the response sent back to the client if the directive SecContentInjection is set to On. This is possible because the rule engine buffers the response body and gives us the opportunity to either put data in front of the response (prepending) or append it to the end of the response. The actions to use are appropriately named prepend and append.

Content injection allows us to do some really cool things. One trivial example just to show how the technique works would be to inject JavaScript code that displays the message "Stop trying to hack our site!" whenever we detected a condition that wasn't severe enough to block the request, be where we did want to issue a warning to any would-be hackers:

SecRule ARGS:username "%" 
"phase:1,allow,t:urlDecode,append: 
'<script type=text/javascript>alert(\"Stop trying 
to hack our site!\");</script>',log,msg:'Potential 
intrusion detected'"

The above detects when someone tries...

Another very useful ModSecurity feature is the ability to inspect files that have been uploaded via a POST request. So long as we have set RequestBodyBuffering to On we can then intercept the uploaded files and inspect them by using the @inspectFile operator.

To show how this works we will write a script that intercepts uploaded files and scans them with the virus scanner Clam AntiVirus. Clam AntiVirus is an open source virus scanner which you can obtain at http://www.clamav.net. Once you have installed it you can use the command clamscan <filename> to scan a file for viruses.

To intercept uploaded files we need to apply a few ModSecurity directives:

SecUploadDir /tmp/modsecurity
SecTmpDir /tmp/modsecurity

This specifies where ModSecurity stores the files it extracts from the request body. We need to make sure we create the temporary directory and that the Apache user has read and write access to it.

When using @inspectFile, ModSecurity treats the script output...

This chapter contained a lot of information, and you will no doubt want to refer back to it when writing rules. It will take a while to get used to the ModSecurity syntax if you haven't written rules before, so make sure you try out as many examples as possible and write rules of your own to get the hang of the process of creating new rules.

In this chapter we first looked at the basic SecRule syntax, and then learned how to match strings using either regular expressions or simple string comparison operators. We learned in which order the rule engine executes rules and why it's important to know about this to be able to write rules properly. We also learned about all the other things we need to know to successfully write rules such as transformation functions, macro expansion and the actions that can be taken when a rule matches.

In the second half of the chapter we looked at practical examples of using ModSecurity, including how to use a geographical database to locate visitors and...