mod_antibot

Overview

mod_antibot is a powerful and flexible solution to protect against various brute force and HTTP level DDOS attacks, SPAM bots, password guessing bots, etc. It works by analyzing frequency of actions and uses flexible rule syntax similar to time proven mod_rewrite.

Different requests have different cost to the server. Average server can handle from 5 000 to 50 000 requests for small static file per second. But only 5 requests per second to a blog post or search page, that utilizes database heavily, will be enough to put most database servers on knees. Such application level attacks are harder to identify as 5 requests per second usually does not attract much attention of various DDOS protection utilities. With mod_antibot you can apply different policy to different URLs, so you can protect most critical and expensive resources with more strict rules.

Problems you can usually solve with mod_antibot:

Protect your login forms from guessing passwords with brute force.
Protect your forum from SPAM bots or users that post too frequently.
Repel HTTP-level DDOS attacks, especially on critical sections of your site, like resource and time expensive scripts.
Limit users on how often they can trigger any action on your site, like login, create post, download file, etc.
Configure stop-words and honey pots to ban malicious users and bots immediately when triggered.

Quick start

# Antibot engine have to be turned on before usage:
AntibotEngine On

# PHPBB forum is taken as example below
# This rule limits new forum user registration attempts
# from one IP to 4 per 10 minutes
AntibotCond %{REQUEST_URI} ^/community/ucp.php [NC]
AntibotCond %{ARGS_GET:mode} ^register [NC]
AntibotCond %{ARGS_POST:username} .
AntibotRule 1:reg:%{REMOTE_ADDR} 4 per 10 minutes [ban=1 hour]

# Limit to 4 login attempts per 10 minutes
AntibotCond %{REQUEST_URI} ^/community/ucp.php
AntibotCond %{ARGS_GET:mode} ^login
AntibotRule 2:login:%{REMOTE_ADDR} 4 per 10 minutes [ban=1 hour]

# Limit to 3 admin panel login attempts per 30 minutes
AntibotCond %{REQUEST_URI} ^/community/adm/index.php [NC]
AntibotCond %{ARGS_POST:username} .
AntibotRule 3:adm:%{REMOTE_ADDR} 3 per 30 minutes [ban=1 hour]

# Limit to 4 search requests per 1 minute
AntibotCond %{REQUEST_URI} ^/search.php [NC]
AntibotRule 4:search:%{REMOTE_ADDR} 4 per 1 minute [ban=10 minutes]

Directives

Name	Context	Description
AntibotCond	S V D .h	imposes condition on the subsequent AntibotRule directive
AntibotDebug	S V D .h	enables or disables debugging info in response headers
AntibotEngine	S V D .h	enables or disables mod_antibot engine in current context
AntibotLog	S V D .h	sets the name and path to mod_antibot log file or directory
AntibotRule	S V D .h	defines Antibot rule

AntibotCond

AntibotCond directive defines a single condition for the following AntibotRule directive.
Multiple conditions for the same rule are possible. When one or several conditions precede a rule, the rule only apply when ALL of these conditions are matched (AND logic).

Syntax

AntibotCond TestString CondPattern

Description

TestString additionally to plain text may include one or more of following constructs:
- Back references to preceding RewriteCond patterns using %N syntax
- Environment variable using %{ENV:variable_name} syntax
- HTTP header value with %{HTTP:header_name} syntax
- Post argument reference: %{ARGS_POST:argument_name}
- Get argument reference: %{ARGS_GET:argument_name}
- Cookie reference: %{REQUEST_COOKIES:cookie_name}
- Complete POST body reference: %{REQUEST_BODY}
- Server variable using %{NAME_OF_VARIABLE} syntax.
Here is the list of supported server variables:
CondPattern specifies a regular expression that will be searched in the instance of TestString .

Flags

NoCase or NC — makes the CondPattern case-insensitive
O — normalizes string before processing (removes URL-encoding, illegal characters, etc; also, IIS normalization implies removal of query string from the URL)

Example

# The rule applies only to GET requests
AntibotCond %{REQUEST_METHOD} (GET)
AntibotRule 1:%1:a=%{ARGS_GET:a}:b=%{ARGS_GET:b} 2 per 1 second [ban=1 minute]

AntibotDebug

AntibotDebug directive enables or disables feature when mod_antibot adds HTTP headers to server response with information about what rules has been fired. It is sometimes useful to understand how rules chain work. Another option would be using mod_developer.

Syntax

AntibotDebug On|Off

AntibotEngine

AntibotEngine directive enables or disables antibot runtime for the context it's used in. Use AntibotEngine off instead of commenting out rules if you need to disable mod_antibot module or specific .htaccess file.

Syntax

RewriteEngine On|Off

Note! Default value is Off, so you need to put AntibotEngine On into every .htaccess you plan to use mod_antibot directives in.

AntibotLog

AntibotLog directive sets the name and path to the log file or directory where mod_antibot will log its actions. If no log is specified no log files will be created.

Syntax

AntibotLog file-path

Example

AntibotLog "C:\local\path\dir"

AntibotRule

AntibotRule directive defines antibot policy rule. It works by adding key strings to a hash table each time rule is executed. Antibot engine then counts number of identical keys and limit how many times same key string can be added to a table within defined period of time.

Syntax

AntibotRule Key_String Frequency [actions]

Description

For example consider following rule:

AntibotRule 1:sample:%{REMOTE_ADDR} 100 per 1 minute [ban=1 hour]

The key string generated when user makes a request would look like: "1:sample:255.255.255.255". It is common to include %{REMOTE_ADDR} in the key to generate unique key for each IP (either IPv4 or IPv6). The "1:sample:" part is just a static string. Because mod_antibot uses one global hash table per web site, these static symbols will act as a salt when generating key string hash to separate one rule from another. When identical keys added to the table they increase counter. When counter reaches limit, the rule action is fired. This also means two different rules may result in identical key strings and their counters will sum up. The rule from example above without conditions will limit number of requests made from same IP address to 100 per 1 minute and ban IP for 1 hour if triggered.

Key_String — A string key that will be added to a hash table each time rule applies. This string has same syntax as TestString parameter form AntibotCond directive. You can use any variables and back references to preceding AntibotCond directives here. It is common to include client IP %{REMOTE_ADDR} to this string, to generate unique key for each IP.
Frequency — defines expiration period of key strings, or in simple words how many times same key string may be added to the table within certain period of time before rule's action is executed. Syntax is simple words, like:
```
5 per 10 minutes
30 per 1 hour
50 per 3 days
```
possible time specifiers: second(s), minute(s), hour(s), day(s)
actions — defines comma separated list actions that will be executed if counter reaches the limit. Possible values:
- ban=time specifier — block all further requests with same key string for a period of time. Syntax examples:
```
ban=1 hour
ban=10 minutes 23 seconds
ban=1 day
```
- exec=command — a command that will be executed. This could be used to add firewall rule to block remote user.
- L or Last — stop executing and don't apply further rules.