Poject Honey Pot's API

Project Honey Pot has an API called Http:BL which uses effecient DNS queries to check IP addresses against their black list of web based activities. It can determine if a user's IP is a search engine, a harvester, a comment spammer, or just suspicious, as well as a theat level. You can see more about this project, (and help out by adding a honey pot to your site) at: http://www.projecthoneypot.org/httpbl_api.php

Features of this class

This small class encapsulates requests to the Http:BL for easy integration with your code. With this PHP class one can easily identify/filter out spammers, harvesters, and other types of suspicious traffic. It is built using OO PHP and optimized for use with eclipse or other IDE's which support phpdoc and autocomplete. Results can be returned in an object. Best if used with PHP 5.3+, but PHP > 5 is required.

Configuration

The class is self contained and requires no setup other then adding your Http:BL API key. If you do not already have one, grab an API key from: http://www.projecthoneypot.org/httpbl_configure.php
Save the API key as the value of the constant HP_API_KEY at the top of the file. If you would rather store the API key somewhere else, perhaps in another configuation file, you can use the method getAPIKey() to fetch the value.

Methods

method	Description
allow($ip)	A public static method which returns true if the passed in IP address is less than the thresholds set, or false on failure. Adjust $threatThreshold and $typeBitThreshold to adjust this method's sensitivity. On error, this method assumes the IP should be allowed.
check($ip)	A public static method which checks the IP against the black list and returns an object of HP_BlackListResult populated with the returned information. On error this method returns an almost empty object, but the type is set to 'not blacklisted', and threat to 0.
getAPIKey($ip)	A private static method which returns the API key. Can be used if you wish to store the API key elsewhere. By default it returns the constant HP_API_KEY.

HP_BlackListResult

The result object represents the response from the query, as well as some translations back into human readable values. It is returned when using the check() method.

property	Values
$ip	The IP address queried
$activity	The number of days since the last activity detected from this IP. This is the second octect of the response. This will be null if the IP is detected to be from a search engine.
$theat	A thread score as returned by Project Honey Pot. It is an integer from 0 to 255, where 255 is the most threatening. This is the third octect.
$typeBit	The bit mask returned by as returned by the query. This is the fourth octect.
$typeArray	An array of detected types as parsed out of the typeBit mask. The possible values of this array are stored as constants at the top of the class. For example, this array could be: array(HP_BlackList::TYPE_SUSPICIOUS, HP_BlackList::TYPE_HARVESTER)
$searchEngineType	The type of search crawler detected, in plain text. Eg: 'Google' or 'InfoSeek' :). Only set if a search engine crawler is detected.
$searchEngineTypeCode	The type code returned by the query. This represents the search engine type, and the mapping between the type and the code are defined at the top of the file. Only set if a search engine crawler is detected.

Examples

A simple way to block known malicious IP addresses:

require_once(HP_BlackList.class.php);

if( !HP_BlackList::allow($_SERVER['REMOTE_ADDR']) ) {
    die('not allowed');
}

Or you can use the HP_BlackListResult object for more fine grain control. For example here we block only harvesters:

require_once(HP_BlackList.class.php);

$blr = HP_BlackList::check($_SERVER['REMOTE_ADDR']);
if( in_array( $blr->typeArray, HP_BlackList::TYPE_HARVESTER) ) {
    die('no harvesters allowed');
}

Find only google search crawlers

require_once(HP_BlackList.class.php);

$blr = HP_BlackList::check($_SERVER['REMOTE_ADDR']);
if( $blr->searchEngineType == 'Google' ) {
    echo "Hello google!";
}

License

Released under MIT license. http://www.opensource.org/licenses/mit-license.php

Authors

Graham McNicoll for Education.com

Download

You can download this project in either zip or tar formats.

You can also clone the project with Git by running:

$ git clone git://github.com/Auz/HP_BlackList