Commit c6885199 authored by ueli heuer's avatar ueli heuer

Update README.md

parent c4751706
......@@ -50,15 +50,15 @@ mod_honeypot is an Apache 2.4 loadable module which checks to see if an incoming
When a request is received, the module proceeds as follows:
1. Check to see if the HTTP request method is in the list of methods to be checked. If not, accept the request and exit.
2. Check to see if the requester's IPv4 address is in the module's cache of previously checked IP addresses. If so, accept or reject the request accordingly and exit.
3. Build a DNS query for the Project Honeypot DNS server.
4. Issue the DNS query. If it fails, fail-safe by accepting the request.
5. If the DNS lookup returned HOST_NOT_FOUND, the requesting IP address is not known to Project Honeypot. Add the requester's address to the IP accept cache, accept the request and exit.
6. Check octet 4 of the response (Project Honeypot visitor types) to see if it is a type being monitored. If not, accept the request and exit.
7. Check octet 3 of the response (Project Honeypot threat level) to see if it is less than the threshold. If so, accept the request and exit.
8. Check octet 2 of the response (Project Honeypot threat age) to see if it is greater than the threshold. If so, accept the request and exit.
9. Reject the request with HTTP error code FORBIDDEN and the message "Your IP address is on the Project Honeypot offender list."
1. Check to see if the HTTP request method is in the list of methods to be checked. If not, accept the request and exit.
2. Check to see if the requester's IPv4 address is in the module's cache of previously checked IP addresses. If so, accept or reject the request accordingly and exit.
3. Build a DNS query for the Project Honeypot DNS server.
4. Issue the DNS query. If it fails, fail-safe by accepting the request.
5. If the DNS lookup returned HOST_NOT_FOUND, the requesting IP address is not known to Project Honeypot. Add the requester's address to the IP accept cache, accept the request and exit.
6. Check octet 4 of the response (Project Honeypot visitor types) to see if it is a type being monitored. If not, accept the request and exit.
7. Check octet 3 of the response (Project Honeypot threat level) to see if it is less than the threshold. If so, accept the request and exit.
8. Check octet 2 of the response (Project Honeypot threat age) to see if it is greater than the threshold. If so, accept the request and exit.
9. Reject the request with HTTP error code FORBIDDEN and the message "Your IP address is on the Project Honeypot offender list."
# 5.0 Installation
......@@ -72,21 +72,21 @@ Download and unpack the mod_honeypot distribution.
In the top level directory, locate Makefile and open it with a text editor. Locate the following line:
APXS=/usr/local/apache2/bin/apxs
APXS=/usr/local/apache2/bin/apxs
Change this to point at the location of the Apache 2 binaries directory.
Issue the command:
make clean
make clean
followed by:
make
make
If the build is successful, stop the Apache 2 server and issue:
make install
make install
Optionally, add a conditional configuration section to httpd.conf as described in the next section.
......@@ -136,7 +136,7 @@ This section describes the configuration directives which control the optional f
This directive sets the Project Honeypot access key used for DNSBL queries. An example is seen below:
HP_ACCESSKEY abcdefghijkl
HP_ACCESSKEY abcdefghijkl
This directive is required. The value is free-format lower-case text, 12 characters long. There is no default.
......@@ -147,31 +147,31 @@ A Project Honeypot access key must be obtained from Project Honeypot's web site
This directive controls production of execution trace and debugging messages to the Apache log file. An example is seen below:
HP_LOGDEBUG 0xF00E03
HP_LOGDEBUG 0xF00E03
This directive is optional. The value is bit-coded hexadecimal, case-insensitive and length-insensitive. The default is 0x0, no debug / trace messages.
This directive is intended primarily for developer use and for debugging when a specific problem is suspected. There are four exceptions to this, bits 0x01, 0x02, 0x08 and 0x10 - see the table below for their definitions.
Bit Function
\-------- ---------------------------------------------
00000001 Log URI when blocked
00000002 Log cache turnovers
00000004 Report trace/debug flag bits
00000008 Report offenders under level threshold
00000010 Report offenders over age threshold
00000080 hp_check_ipv4_cache entry
00000100 search cache
00000800 hp_add_ipv4_cache entry
00001000 insert address
00200000 honeypot_handler entry
00400000 request method processing
00800000 IPv4 cache processing
01000000 DNSBL lookup
02000000 visitor type processing
04000000 threat level processing
08000000 threat age processing
10000000 add IP to accept/reject cache
Bit Function
-------- ---------------------------------------------
00000001 Log URI when blocked
00000002 Log cache turnovers
00000004 Report trace/debug flag bits
00000008 Report offenders under level threshold
00000010 Report offenders over age threshold
00000080 hp_check_ipv4_cache entry
00000100 search cache
00000800 hp_add_ipv4_cache entry
00001000 insert address
00200000 honeypot_handler entry
00400000 request method processing
00800000 IPv4 cache processing
01000000 DNSBL lookup
02000000 visitor type processing
04000000 threat level processing
08000000 threat age processing
10000000 add IP to accept/reject cache
Use of the execution trace options can result in very large server logs when used on a busy server. Debug tracing is intended for use on test-bed systems, not in production.
......@@ -180,7 +180,7 @@ Use of the execution trace options can result in very large server logs when use
This directive controls the HTTP request methods handled by the module. An example is seen below:
HP_METHODS GET,POST,PUT
HP_METHODS GET,POST,PUT
This directive is optional. No spaces are permitted in the list. The default value is POST,PUT,OPTIONS.
......@@ -191,7 +191,7 @@ For sites wishing to exclude blog spammers and posting bots, the default value i
This directive controls the age threshold for visitors reported as threats by Project Honeypot. An example is seen below:
HP_THREATAGE 30
HP_THREATAGE 30
This directive is optional. It is a decimal value in days ranging from 0 to 254. The default value is 90.
......@@ -202,7 +202,7 @@ When a request is from an IP with a threat age, if the threat age is greater tha
This directive controls the threat level threshold for visitors reported as threats by Project Honeypot. An example is seen below:
HP_THREATLEVEL 15
HP_THREATLEVEL 15
This directive is optional. It is a decimal value ranging from 0 to 254. The default value is 10.
......@@ -213,15 +213,15 @@ When a request is from an IP with a threat level, if the threat level is less th
This directive controls the monitored visitor types for visitors reported as threats by Project Honeypot. An example is seen below:
HP_VISITORTYPE 0x5
HP_VISITORTYPE 0x5
This directive is optional. The value is bit-coded hexadecimal, case-insensitive and length-insensitive. The default is 0x7, monitor Suspicious, Harvester, Comment Spammer.
Bit Project Honeypot Visitor Type
-------- ---------------------------------------------
0x0001 Suspicious
0x0002 Harvester
0x0004 Comment Spammer
Bit Project Honeypot Visitor Type
-------- ---------------------------------------------
0x0001 Suspicious
0x0002 Harvester
0x0004 Comment Spammer
When a request is from an IP with a visitor type, if the visitor type bit does not match any of the monitored type bits the request is accepted. The visitor type is octet 4 of the DNSBL response. Consult the Project Honeypot API for specific information about this octet.
......@@ -235,7 +235,7 @@ This section describes ordinary error messages which may be logged by the module
mod_honeypot logs error messages in the form:
mod_honeypot: descriptive text
mod_honeypot: descriptive text
## 7.2 Log Message Breakup Warning
......@@ -252,28 +252,28 @@ These are error messages seen in normal operation. Internal trace / debug messa
### 7.3.1 Project Honeypot DNS Check Failure
mod_honeypot: Project Honeypot DNS check failed
mod_honeypot: abcdefghijkl.r4.r3.r2.r1.dnsbl.httpbl.org
mod_honeypot: DNS lookup error message
mod_honeypot: Passthrough
mod_honeypot: Project Honeypot DNS check failed
mod_honeypot: abcdefghijkl.r4.r3.r2.r1.dnsbl.httpbl.org
mod_honeypot: DNS lookup error message
mod_honeypot: Passthrough
The module did a DNS lookup to query the Project Honeypot threat list. The lookup failed for the reason described in the lookup error message.
The DNS lookup string comprises:
abcdefghijkl. The Project Honeypot access key
r4.r3.r2.r1. The requester's IPv4 address, octet order reversed
abcdefghijkl. The Project Honeypot access key
r4.r3.r2.r1. The requester's IPv4 address, octet order reversed
with "dnsbl.httpbl.org" appended.
with "dnsbl.httpbl.org." appended.
Resolution: The most probable reason for failure is that the Project Honeypot DNS server is overloaded or down. A caching DNS server on the server's host system will not help with this issue as the Project Honeypot DNSBL is only queried on the first request.
### 7.3.2 Request Rejection
mod_honeypot: Blocklisted
mod_honeypot: Blocklisted
which may optionally be followed by
mod_honeypot: Local resource URI
mod_honeypot: Local resource URI
The requester's IP address is a known Project Honeypot threat and meets all rejection criteria. The request is rejected with error code 403, "Forbidden." The requester also receives the text message "Your IP address is on the Project Honeypot offender list."
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment