Apache DoS Evasive Maneuvers Module
For Apache 1.3 and 2.0
Copyright (c) 2002 Network Dweebs Corporation
Version 1.7 [2003.0822.1700]

LICENSE

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

WHAT IS MOD_DOSEVASIVE ?

mod_dosevasive is an evasive maneuvers module for Apache to provide evasive
action in the event of an HTTP DoS or DDoS attack or brute force attack.  It 
is also designed to be a detection tool, and can be easily configured to talk 
to ipchains, firewalls, routers, and etcetera.  

Detection is performed by creating an internal dynamic hash table of IP 
Addresses and URIs, and denying any single IP address from any of the following:

- Requesting the same page more than a few times per second
- Making more than 50 concurrent requests on the same child per second
- Making any requests while temporarily blacklisted (on a blocking list)

This method has worked well in both single-server script attacks as well 
as distributed attacks, but just like other evasive tools, is only as 
useful to the point of bandwidth and processor consumption (e.g. the
amount of bandwidth and processor required to receive/process/respond
to invalid requests), which is why it's a good idea to integrate this
with your firewalls and routers.

This module instantiates for each listener individually, and therefore has
a built-in cleanup mechanism and scaling capabilities.  Because of this,
legitimate requests are never compromised but only scripted attacks.  Even
a user repeatedly clicking on 'reload' should not be affected unless they do
it maliciously.

Two different module sources have been provided:

Apache v1.3 API:	mod_dosevasive.c
Apache v2.0 API:	mod_dosevasive20.c

HOW IT WORKS

A web hit request comes in.  The following steps take place:

- The IP address of the requestor is looked up on the temporary blacklist
- The IP address of the requestor and the URI are both hashed into a "key".  
  A lookup is performed in the listener's internal hash table to determine 
  if the same host has requested this page more than once within the past 
  1 second.  
- The IP address of the requestor is hashed into a "key".
  A lookup is performed in the listerner's internal hash table to determine
  if the same host has requested more than 50 objects within the past
  second (from the same child).

If any of the above are true, a 403 response is sent.  This conserves
bandwidth and system resources in the event of a DoS attack.  Additionally,
a system command and/or an email notification can also be triggered to block
all the originating addresses of a DDoS attack. 

Once a single 403 incident occurs, mod_dosevasive now blocks the entire IP 
address for a period of 10 seconds (configurable).  If the host requests a 
page within this period, it is forced to wait even longer.  Since this is 
triggered from requesting the same URL multiple times per second, this 
again does not affect legitimate users.

The blacklist can/should be configured to talk to your network's firewalls 
and/or routers to push the attack out to the front lines, but this is not 
required.

mod_dosevasive also performs syslog reporting using daemon.alert.  Messages
will look like this:

Aug  6 17:41:49 elijah mod_dosevasive[23184]: [ID 801097 daemon.alert] Blacklisting address x.x.x.x: possible DoS attack.

WHAT IS THIS TOOL USEFUL FOR?

This tool is *excellent* at fending off small to medium-sized request-based
DoS attacks or script attacks and brute force attacks.  Its features will 
prevent you from wasting bandwidth or having a few thousand CGI scripts 
running as a result of an attack.  When used in conjunction with other
preventative measures such as router blackholing, this tool is very
effective against larger DDoS attacks as well.

If you do not have an infrastructure capable of fending off any other types
of DoS attacks, chances are this tool will only help you to the point of
your total bandwidth or server capacity for sending 403's.  Without a solid
infrastructure and DoS evasion plan in place, a heavy distributed DoS will most
likely still take you offline.  

HOW TO INSTALL

APACHE v1.3
-----------

1. Extract this archive into src/modules in the Apache source tree

2. Run ./configure --add-module=src/modules/dosevasive/mod_dosevasive.c

3. make, install

4. Restart your server


If you are using the Ensim control panel, or some other wrapper that makes it
difficult to do the above, you can compile and install the module simply
by doing:

apxs -iac mod_dosevasive.c

And restarting Apache

APACHE v2.0
-----------

1. Extract this archive

2. Run $APACHE_ROOT/bin/apxs -i -a -c mod_dosevasive20.c

3. The module will be built and installed into $APACHE_ROOT/modules, and loaded into your httpd.conf

4. Restart your server

CONFIGURATION

mod_dosevasive has default options configured, but you may also add the
following block to your httpd.conf:

APACHE v1.3
-----------

<IfModule mod_dosevasive.c>
    DOSHashTableSize    3097
    DOSPageCount        2
    DOSSiteCount        50
    DOSPageInterval     1
    DOSSiteInterval     1
    DOSBlockingPeriod   10
</IfModule>

APACHE v2.0
-----------
<IfModule mod_dosevasive20.c>
    DOSHashTableSize    3097
    DOSPageCount        2
    DOSSiteCount        50
    DOSPageInterval     1
    DOSSiteInterval     1
    DOSBlockingPeriod   10
</IfModule>

Optionally you can also add the following directives:

    DOSEmailNotify	you@yourdomain.com
    DOSSystemCommand	"su - someuser -c '/sbin/... %s ...'"

You will also need to add this line if you are building with dynamic support:

APACHE v1.3
-----------

AddModule	mod_dosevasive.c

APACHE v2.0
-----------

LoadModule dosevasive20_module modules/mod_dosevasive20.so

(This line is already added to your configuration by apxs)

DOSHashTableSize
----------------

The hash table size defines the number of top-level nodes for each child's 
hash table.  Increasing this number will provide faster performance by 
decreasing the number of iterations required to get to the record, but 
consume more memory for table space.  You should increase this if you have
a busy web server.  The value you specify will automatically be tiered up to 
the next prime number in the primes list (see mod_dosevasive.c for a list 
of primes used).

DOSPageCount
------------

This is the threshhold for the number of requests for the same page (or URI)
per page interval.  Once the threshhold for that interval has been exceeded,
the IP address of the client will be added to the blocking list.
 
DOSSiteCount
------------

This is the threshhold for the total number of requests for any object by
the same client on the same listener per site interval.  Once the threshhold 
for that interval has been exceeded, the IP address of the client will be added
to the blocking list.

DOSPageInterval
---------------

The interval for the page count threshhold; defaults to 1 second intervals.

DOSSiteInterval
---------------

The interval for the site count threshhold; defaults to 1 second intervals.

DOSBlockingPeriod
-----------------

The blocking period is the amount of time (in seconds) that a client will be
blocked for if they are added to the blocking list.  During this time, all
subsequent requests from the client will result in a 403 (Forbidden) and
the timer being reset (e.g. another 10 seconds).  Since the timer is reset
for every subsequent request, it is not necessary to have a long blocking
period; in the event of a DoS attack, this timer will keep getting reset. 

DOSEmailNotify
--------------

If this value is set, an email will be sent to the address specified
whenever an IP address becomes blacklisted.  A locking mechanism using /tmp
prevents continuous emails from being sent.

NOTE: Be sure MAILER is set correctly in mod_dosevasive.c 
      (or mod_dosevasive20.c).  The default is "/bin/mail -t %s" where %s is 
      used to denote the destination email address set in the configuration.  
      If you are running on linux or some other operating system with a 
      different type of mailer, you'll need to change this.

DOSSystemCommand
----------------

If this value is set, the system command specified will be executed
whenever an IP address becomes blacklisted.  This is designed to enable
system calls to ip filter or other tools.  A locking mechanism using /tmp
prevents continuous system calls.  Use %s to denote the IP address of the
blacklisted IP.

TWEAKING APACHE

This brings us to another tweakable in Apache.  The keep-alive settings 
for your children should be reasonable enough to keep each child
up long enough to resist a DOS attack (or at least part of one).  For every
child that exits, another 5-10 copies of the page may get through before
putting the attacker back into '403 Land'.  With this said, you should have
a very high MaxRequestsPerChild (or unlimited).

You'll also want to have a MaxRequestsPerChild set to a non-zero value, as
DosEvasive cleans up its internal hashes only on exit.  The default
MaxRequestsPerChild is usually 10000.

TESTING

Want to make sure it's working? Run test.pl, and view the response codes.
If the target machine is not localhost, be sure to change it in the script 
first.  You should receive 403 responses after the first 25-50 requests,
depending on your server configuration.  Please don't use this script to
DoS others without their permission.

FEEDBACK 

Please email me with questions, constructive comments, or feedback:
  jonathan@nuclearelephant.com.

