"SfR Fresh" - the SfR Freeware/Shareware Archive 
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 Apache Evasive Maneuvers Module
2 For Apache 1.3 and 2.0
3 Copyright (c) Deep Logic, Inc.
4 Version 1.10 [2005.0117]
5
6 LICENSE
7
8 This program is free software; you can redistribute it and/or
9 modify it under the terms of the GNU General Public License
10 as published by the Free Software Foundation; version 2
11 of the License.
12
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
17
18 You should have received a copy of the GNU General Public License
19 along with this program; if not, write to the Free Software
20 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
21
22 WHAT IS MOD_EVASIVE ?
23
24 mod_evasive is an evasive maneuvers module for Apache to provide evasive
25 action in the event of an HTTP DoS or DDoS attack or brute force attack. It
26 is also designed to be a detection tool, and can be easily configured to talk
27 to ipchains, firewalls, routers, and etcetera.
28
29 Detection is performed by creating an internal dynamic hash table of IP
30 Addresses and URIs, and denying any single IP address from any of the following:
31
32 - Requesting the same page more than a few times per second
33 - Making more than 50 concurrent requests on the same child per second
34 - Making any requests while temporarily blacklisted (on a blocking list)
35
36 This method has worked well in both single-server script attacks as well
37 as distributed attacks, but just like other evasive tools, is only as
38 useful to the point of bandwidth and processor consumption (e.g. the
39 amount of bandwidth and processor required to receive/process/respond
40 to invalid requests), which is why it's a good idea to integrate this
41 with your firewalls and routers.
42
43 This module instantiates for each listener individually, and therefore has
44 a built-in cleanup mechanism and scaling capabilities. Because of this,
45 legitimate requests are rarely ever compromised, only legitimate attacks. Even
46 a user repeatedly clicking on 'reload' should not be affected unless they do
47 it maliciously.
48
49 Three different module sources have been provided:
50
51 Apache v1.3 API: mod_evasive.c
52 Apache v2.0 API: mod_evasive20.c
53 NSAPI (iPlanet): mod_evasiveNSAPI.c *
54
55 NOTE: mod_evasiveNSAPI is a port submitted by Reine Persson <reiper@rsv.se>
56 and is not officially supported as part of the mod_evasive project.
57
58 HOW IT WORKS
59
60 A web hit request comes in. The following steps take place:
61
62 - The IP address of the requestor is looked up on the temporary blacklist
63 - The IP address of the requestor and the URI are both hashed into a "key".
64 A lookup is performed in the listener's internal hash table to determine
65 if the same host has requested this page more than once within the past
66 1 second.
67 - The IP address of the requestor is hashed into a "key".
68 A lookup is performed in the listerner's internal hash table to determine
69 if the same host has requested more than 50 objects within the past
70 second (from the same child).
71
72 If any of the above are true, a 403 response is sent. This conserves
73 bandwidth and system resources in the event of a DoS attack. Additionally,
74 a system command and/or an email notification can also be triggered to block
75 all the originating addresses of a DDoS attack.
76
77 Once a single 403 incident occurs, mod_evasive now blocks the entire IP
78 address for a period of 10 seconds (configurable). If the host requests a
79 page within this period, it is forced to wait even longer. Since this is
80 triggered from requesting the same URL multiple times per second, this
81 again does not affect legitimate users.
82
83 The blacklist can/should be configured to talk to your network's firewalls
84 and/or routers to push the attack out to the front lines, but this is not
85 required.
86
87 mod_evasive also performs syslog reporting using daemon.alert. Messages
88 will look like this:
89
90 Aug 6 17:41:49 elijah mod_evasive[23184]: [ID 801097 daemon.alert] Blacklisting address x.x.x.x: possible attack.
91
92 WHAT IS THIS TOOL USEFUL FOR?
93
94 This tool is *excellent* at fending off request-based DoS attacks or scripted
95 attacks, and brute force attacks. When integrated with firewalls or IP filters,
96 mod_evasive can stand up to even large attacks. Its features will prevent you
97 from wasting bandwidth or having a few thousand CGI scripts running as a
98 result of an attack.
99
100 If you do not have an infrastructure capable of fending off any other types
101 of DoS attacks, chances are this tool will only help you to the point of
102 your total bandwidth or server capacity for sending 403's. Without a solid
103 infrastructure and address filtering tool in place, a heavy distributed DoS
104 will most likely still take you offline.
105
106 HOW TO INSTALL
107
108 APACHE v1.3
109 -----------
110
111 Without DSO Support:
112
113 1. Extract this archive into src/modules in the Apache source tree
114
115 2. Run ./configure --add-module=src/modules/evasive/mod_evasive.c
116
117 3. make, install
118
119 4. Restart Apache
120
121 With DSO Support, Ensim, or CPanel:
122
123 1. $APACHE_ROOT/bin/apxs -iac mod_evasive.c
124
125 2. Restart Apache
126
127 APACHE v2.0
128 -----------
129
130 1. Extract this archive
131
132 2. Run $APACHE_ROOT/bin/apxs -i -a -c mod_evasive20.c
133
134 3. The module will be built and installed into $APACHE_ROOT/modules, and loaded into your httpd.conf
135
136 4. Restart Apache
137
138 NSAPI
139 SunONE (iPlanet,netscape) Installation
140 --------------------------------------
141
142 Tested on:
143 iPlanet 4.1sp12
144 iPlanet 6.0sp5
145
146 Edit compile script for your environment and compile mod_evasiveNSAPI.c
147 to a shared library.
148
149 CONFIGURATION
150
151 mod_evasive has default options configured, but you may also add the
152 following block to your httpd.conf:
153
154 APACHE v1.3
155 -----------
156
157 <IfModule mod_evasive.c>
158 DOSHashTableSize 3097
159 DOSPageCount 2
160 DOSSiteCount 50
161 DOSPageInterval 1
162 DOSSiteInterval 1
163 DOSBlockingPeriod 10
164 </IfModule>
165
166 APACHE v2.0
167 -----------
168 <IfModule mod_evasive20.c>
169 DOSHashTableSize 3097
170 DOSPageCount 2
171 DOSSiteCount 50
172 DOSPageInterval 1
173 DOSSiteInterval 1
174 DOSBlockingPeriod 10
175 </IfModule>
176
177 Optionally you can also add the following directives:
178
179 DOSEmailNotify you@yourdomain.com
180 DOSSystemCommand "su - someuser -c '/sbin/... %s ...'"
181 DOSLogDir "/var/lock/mod_evasive"
182
183 You will also need to add this line if you are building with dynamic support:
184
185 APACHE v1.3
186 -----------
187
188 AddModule mod_evasive.c
189
190 APACHE v2.0
191 -----------
192
193 LoadModule evasive20_module modules/mod_evasive20.so
194
195 (This line is already added to your configuration by apxs)
196
197 NSAPI
198 SunONE (iPlanet,Netscape) Configuration
199 --------------------------------------
200
201 Configure iPlanet 4.1
202 ---------------------
203
204 Edit obj.conf:
205
206 Init fn="load-modules" funcs="mod_evasive_init,mod_evasive_check" shlib="/opt/ns-4.1/plugins/lib/mod_evasive.sl"
207
208 Init fn="mod_evasive_init" DOSPageCount=2 DOSSiteCount=50 DOSPageInterval=1 DOSSiteInterval=1 DOSBlockingPeriod=10 DOSWhitelist="10.60.0.7,10.65.0.10"
209
210 In the default object:
211 PathCheck fn=mod_evasive_check
212
213 Or an own object
214 <Object name="evasive" ppath="/DoSProtectedArea*">
215 NameTrans fn=mod_evasive_check
216 </Object>
217
218
219 Configure iPlanet 6.0
220 ---------------------
221
222 Edit magnus.conf:
223
224 Init fn="load-modules" funcs="mod_evasive_init,mod_evasive_check" shlib="/opt/iplanet-6.0/plugins/lib/mod_evasive.sl"
225
226 Init fn="mod_evasive_init" DOSWhitelist="10.60.0.7,10.65.0.10"
227
228 Edit obj.conf:
229 In the default object:
230 PathCheck fn=mod_evasive_check
231
232 Or an own object
233 <Object name="evasive" ppath="/DoSProtectedArea*">
234 NameTrans fn=mod_evasive_check
235 </Object>
236
237 DOSHashTableSize
238 ----------------
239
240 The hash table size defines the number of top-level nodes for each child's
241 hash table. Increasing this number will provide faster performance by
242 decreasing the number of iterations required to get to the record, but
243 consume more memory for table space. You should increase this if you have
244 a busy web server. The value you specify will automatically be tiered up to
245 the next prime number in the primes list (see mod_evasive.c for a list
246 of primes used).
247
248 DOSPageCount
249 ------------
250
251 This is the threshhold for the number of requests for the same page (or URI)
252 per page interval. Once the threshhold for that interval has been exceeded,
253 the IP address of the client will be added to the blocking list.
254
255 DOSSiteCount
256 ------------
257
258 This is the threshhold for the total number of requests for any object by
259 the same client on the same listener per site interval. Once the threshhold
260 for that interval has been exceeded, the IP address of the client will be added
261 to the blocking list.
262
263 DOSPageInterval
264 ---------------
265
266 The interval for the page count threshhold; defaults to 1 second intervals.
267
268 DOSSiteInterval
269 ---------------
270
271 The interval for the site count threshhold; defaults to 1 second intervals.
272
273 DOSBlockingPeriod
274 -----------------
275
276 The blocking period is the amount of time (in seconds) that a client will be
277 blocked for if they are added to the blocking list. During this time, all
278 subsequent requests from the client will result in a 403 (Forbidden) and
279 the timer being reset (e.g. another 10 seconds). Since the timer is reset
280 for every subsequent request, it is not necessary to have a long blocking
281 period; in the event of a DoS attack, this timer will keep getting reset.
282
283 DOSEmailNotify
284 --------------
285
286 If this value is set, an email will be sent to the address specified
287 whenever an IP address becomes blacklisted. A locking mechanism using /tmp
288 prevents continuous emails from being sent.
289
290 NOTE: Be sure MAILER is set correctly in mod_evasive.c
291 (or mod_evasive20.c). The default is "/bin/mail -t %s" where %s is
292 used to denote the destination email address set in the configuration.
293 If you are running on linux or some other operating system with a
294 different type of mailer, you'll need to change this.
295
296 DOSSystemCommand
297 ----------------
298
299 If this value is set, the system command specified will be executed
300 whenever an IP address becomes blacklisted. This is designed to enable
301 system calls to ip filter or other tools. A locking mechanism using /tmp
302 prevents continuous system calls. Use %s to denote the IP address of the
303 blacklisted IP.
304
305 DOSLogDir
306 ---------
307
308 Choose an alternative temp directory
309
310 By default "/tmp" will be used for locking mechanism, which opens some
311 security issues if your system is open to shell users.
312
313 http://security.lss.hr/index.php?page=details&ID=LSS-2005-01-01
314
315 In the event you have nonprivileged shell users, you'll want to create a
316 directory writable only to the user Apache is running as (usually root),
317 then set this in your httpd.conf.
318
319 WHITELISTING IP ADDRESSES
320
321 IP addresses of trusted clients can be whitelisted to insure they are never
322 denied. The purpose of whitelisting is to protect software, scripts, local
323 searchbots, or other automated tools from being denied for requesting large
324 amounts of data from the server. Whitelisting should *not* be used to add
325 customer lists or anything of the sort, as this will open the server to abuse.
326 This module is very difficult to trigger without performing some type of
327 malicious attack, and for that reason it is more appropriate to allow the
328 module to decide on its own whether or not an individual customer should be
329 blocked.
330
331 To whitelist an address (or range) add an entry to the Apache configuration
332 in the following fashion:
333
334 DOSWhitelist 127.0.0.1
335 DOSWhitelist 127.0.0.*
336
337 Wildcards can be used on up to the last 3 octets if necessary. Multiple
338 DOSWhitelist commands may be used in the configuration.
339
340 TWEAKING APACHE
341
342 The keep-alive settings for your children should be reasonable enough to
343 keep each child up long enough to resist a DOS attack (or at least part of
344 one). Remember, it is the child processes that maintain their own internal
345 IP address tables, and so when one exits, so does all of the IP information it
346 had. For every child that exits, another 5-10 copies of the page may get
347 through before putting the attacker back into '403 Land'. With this said,
348 you should have a very high MaxRequestsPerChild, but not unlimited as this
349 will prevent cleanup.
350
351 You'll want to have a MaxRequestsPerChild set to a non-zero value, as
352 DosEvasive cleans up its internal hashes only on exit. The default
353 MaxRequestsPerChild is usually 10000. This should suffice in only allowing
354 a few requests per 10000 per child through in the event of an attack (although
355 if you use DOSSystemCommand to firewall the IP address, a hole will no
356 longer be open in between child cycles).
357
358 TESTING
359
360 Want to make sure it's working? Run test.pl, and view the response codes.
361 It's best to run it several times on the same machine as the web server until
362 you get 403 Forbidden messages. Some larger servers with high child counts
363 may require more of a beating than smaller servers before blacklisting
364 addresses.
365
366 Please don't use this script to DoS others without their permission.
367
368 KNOWN BUGS
369
370 - This module appears to conflict with the Microsoft Frontpage Extensions.
371 Frontpage sucks anyway, so if you're using Frontpage I assume you're asking
372 for problems, and not really interested in conserving server resources anyway.
373
374 FEEDBACK
375
376 Please email me with questions, constructive comments, or feedback:
377 jonathan@nuclearelephant.com
378