Sample Code

Listed on this page are some PHP and ASP code samples to help you implement the API in your application (bulletin boards, contact pages, registration forms, etc). If you develop something interesting or useful with it and want to share, please do! We'll be glad to list it here and credit it to you.

If you're looking for information on the API itself, you can find that on the API documentation page.

How Does The BotScout Code Work?

The BotScout code works by intercepting registration attempts from your forum registration page, contact form, or any other kind of other web form. It then silently makes a call to our database and compares the email, user name, or IP address against our list of bot 'signatures'. If the item matches then the registration is aborted and the bot is stopped. You can also add code that redirects the bot, serves up fake error messages, or anything else you might want to do (such as banning the IP or email address).

The call to the BotScout database is very fast and users normally don't notice any delay when submitting the form. Real users aren't impacted, but bots are stopped in their tracks.

BotScout BotBuster 1.40 General Use PHP Code ( bytes)
Complete system with ReadMe file; works with most forums, contact pages, and other web forms. Easily modified for use with unlisted forums or custom applications. Currently includes settings for the following message boards: SMF, VBulletin, phpBB, Phorum, PunBB, Invision Power Board, FUDForum, Ikonboard, and W-Agora.
 Download BotBuster ver. 1.40

BotScout BotBuster 1.30 for Simple Machines Forum (versions 1.x and 2.0 Beta 4) ( bytes)
Custom package for SMF Forum (thanks to Atomic Blaze for the packaging!)
 Download BotBuster for SMF

BotScout BotBuster 1.10 for phpBB Forum (tested on version 3.0.4) (58.91 KB)
Custom package for the phpBB Forum (thanks to mtotheikle for the packaging!)
 Download BotBuster for phpBB ver b5 (local archive)
 Download BotBuster for phpBB (remote archive, may be newer)

BotScout BotBuster 1.10 for MyBB Forum (4,669 bytes)
Custom package for the MyBB Forum (thanks to Jimmy Pena for the packaging!)
 Download BotBuster for MyBB ver 1.6+ (local archive)
 Download BotBuster for MyBB (remote archive, may be newer)

BotScout BotBuster 1.10 ASP code for Snitz Forum 2000 (version 3.4.x) ( bytes)
Custom package for Snitz Forum (thanks to Podge for the packaging!)
 Download BotBuster for Snitz Forum (local archive)
 Download BotBuster for Snitz Forum from Google Code (latest version)

WordPress BotScout Comment Protection
Plugin module for WordPress that uses BotScout to screen coments (thanks to jp2112 for the plugin!)
 Link to latest version (on WordPress.org)


BotScout BotBuster 1.11 PHP code for Drupal ( bytes)
Custom module for Drupal v6.x (thanks to Acetolyne for the module!)
 Link to latest version (frequently updated)

BotScout BotBuster 1.10 PHP code for Joomla
Custom package for Joomla (thanks to purplepomegranite for the packaging!)
 Download BotBuster for Joomla (remote archive)

JJAntispam for Joomla, for Joomla ver 2.5 and above.
Custom package for Joomla by Adrian Rosian)
 Download JJAntispam for Joomla (remote archive)

BotScout jHackGuard for Joomla
Custom package for Joomla (thanks to SiteGround for the plugin)
  Download jHackGuard for Joomla (remote archive)
jHackGuard is an improperly-written plugin and we DO NOT recommend its use; we list it here only for completeness and NOT as any indication that we endorse its use. DO NOT USE THIS PLUGIN UNTIL THE AUTHOR CORRECTS ITS BEHAVIOR.

BotScout BotBuster 1.11 PHP code for UBB Threads ( bytes)
Custom module for UBB Threads (thanks to Jooel for the code!)
 Download BotBuster for UBB Threads

Sample XML Parser Code for use with XML Output ( bytes)
Sample PHP code with a demonstration file. Useful if you want to use the XML output from queries against the BotScout database.
 Download XML Sample Code

VB6 Project Code for use with BotScout ( bytes)
Sample VB6 code for a desktop "standalone" version of the Spambot Search Tool from Ur I.T. Mate Group. Project code provided by MysteryFCM.
 Download VB6 Project Code

PHP Code for use with BotScout specifically for AuroraGpt 4-mrV3 can be found here:
http://botscout.com/forum/index.php/topic,152.msg812.html.
This code was donated by "Allan J".

Forum Spam List Checker for use with BotScout ( bytes)
Stand-alone Windows desktop application for checking IPs, names, and emails against several online anti-spam and anti-bot databases, including BotScout, SFS, Project Honeypot, DroneBL, EFnet RBL, FSpamlist, SpamCop, SpamHaus, and many others. Thanks to Gunner for this great application!
 Download Forum Spam List Checker version 2.1 (local archive)
 Download Forum Spam List Checker version 2.1 (remote archive, latest version)

Raw PHP sample code for querying the API
Use this for developing your own API code (PHP) or plugins for forms, message boards, etc. This is a fairly well-commented example of the basic code and how to implement it. This example uses the 'MULTI' query for the best speed and efficiency.
<?php 
/////////////////////////////////////////////////////
// sample API code for use with the BotScout.com API
// code by MrMike / version 2.0 / LDM 2-2009 
/////////////////////////////////////////////////////

/////////////////// START CONFIGURATION ////////////////////////
// use diagnostic output? ('1' to use, '0' to suppress)
// (normally set to '0')
$diag = '0';
////////////////////////
// init vars
$diag='';
$returned_data='';
$botdata='';
$APIKEY='';
$USEXML='';
$XMAIL='';
$XIP='';
$multi_test='';
$ch='';
$botdata='';
////////////////////////
// your optional API key (don't have one? get one here: http://botscout.com/
$APIKEY = '';
////////////////////////
// use XML output responses?
// '1' to use XML, '0' to use standard responses
$USEXML = '0';
/////////////////// END CONFIGURATION ////////////////////////


////////////////////////
// test values 
// an email value...a bot, perhaps?
// these would normally come from your 
// web form or registration form code 
$XMAIL = 'werasomax@mail.ru';

// an IP address
$XIP = '66.226.194.174';

// a name, maybe a bot?
$XNAME = 'erarmazepay';

////////////////////////

// sample query strings - you'd dynamically construct this 
// string and use it as in the example below - these examples use the optional API 'key' field 
// for more information on using the API key, please visit http://botscout.com

// in most cases the BEST test is to use the "MULTI" query and test for the IP and email
//$multi_test = "http://botscout.com/test/?multi&mail=$XMAIL&ip=$XIP&key=$APIKEY";

/* you can use these but they're much less efficient and (possibly) not as reliable
$test_string = "http://botscout.com/test/?mail=$XMAIL&key=$APIKEY";	// test email - reliable
$test_string = "http://botscout.com/test/?ip=$XIP&key=$APIKEY";		// test IP - reliable
$test_string = "http://botscout.com/test/?name=$XNAME&key=$APIKEY";	// test name (unreliable!)
$test_string = "http://botscout.com/test/?all=$XNAME&key=$APIKEY";	// test all (see docs)
*/

// make the url compliant with urlencode()
$XMAIL = urlencode($XMAIL);

// for this example we'll use the MULTI test 
$test_string = "http://botscout.com/test/?multi&mail=$XMAIL&ip=$XIP";

// are using an API key? If so, append it.
if($APIKEY != ''){
	$test_string = "$test_string&key=$APIKEY";
}

// are using XML responses? If so, append the XML format key.
if($USEXML == '1'){
	$test_string = "$test_string&format=xml";
}

////////////////////////
if($diag=='1'){print "Test String: $test_string";}
////////////////////////


////////////////////////
// use file_get_contents() or cURL? 
// we'll user file_get_contents() unless it's not available 

if(function_exists('file_get_contents')){
	// Use file_get_contents
	$returned_data = file_get_contents($test_string);
}else{
	$ch = curl_init($test_string);
	curl_setopt($ch, CURLOPT_HEADER, 0);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	$returned_data = curl_exec($ch);
	curl_close($ch);
}

// diagnostic output 
if($diag=='1'){
	print "RETURNED DATA: $returned_data";
	// sanity check 
	if($returned_data==''){ print 'Error: No return data from API query.'; exit; } 
} 


// take the returned value and parse it (standard API, not XML)
$botdata = explode('|', $returned_data); 

// sample 'MULTI' return string 
// Y|MULTI|IP|4|MAIL|26|NAME|30

// $botdata[0] - 'Y' if found in database, 'N' if not found, '!' if an error occurred 
// $botdata[1] - type of test (will be 'MAIL', 'IP', 'NAME', or 'MULTI') 
// $botdata[2] - descriptor field for item (IP)
// $botdata[3] - how many times the IP was found in the database 
// $botdata[4] - descriptor field for item (MAIL)
// $botdata[5] - how many times the EMAIL was found in the database 
// $botdata[6] - descriptor field for item (NAME)
// $botdata[7] - how many times the NAME was found in the database 


if(substr($returned_data, 0,1) == '!'){
	// if the first character is an exclamation mark, an error has occurred  
	print "Error: $returned_data";
	exit;
}


// this example tests the email address and IP to see if either of them appear 
// in the database at all. Either one is a fairly good indicator of bot identity. 
if($botdata[3] > 0 || $botdata[5] > 0){ 
	print $returned_data; 

	if($diag=='1'){ 
		print "Bot signature found."; 
		print "Type of test was: $botdata[1]"; 
		print "The {$botdata[2]} was found {$botdata[3]} times, the {$botdata[4]} was found {$botdata[5]} times"; 
	} 

	// your 'rejection' code would go here.... 
	// for example, print a fake error message and exit the process. 
	$errnum = round(rand(1100, 25000));
	print "Confabulation Error #$errnum, Halting.";
	exit;

}
////////////////////////


?> 


Raw ASP sample code for querying the API
Use this for developing your own API code (ASP) or plugins for forms, message boards, etc.
<%

'#####################################################
'##  ASP API code for use with the BotScout.com API ##
'##  version 1.0 asp code by Podge                  ##
'#####################################################
'Get the most recent version here
'http://sites.google.com/site/hypodof/botscout
######################################################

function botCheck(ipAddress, emailAddress, Username)
  botCheck = 0
  strBotScoutAPIKey = "YOUR API KEY" ' (register at botscout.com to get your key)
  Dim objXMLHTTP, xml
  Dim apiKey
  Dim responseArray
  Dim ipResponse, usernameResponse, emailResponse

  Set xml = Server.CreateObject("Microsoft.XMLHTTP")
  ' Set xml = Server.CreateObject("MSXML2.ServerXMLHTTP")

    xml.Open "GET", "http://botscout.com/test/?multi&name=" & Username & "&mail=" & emailAddress & "&ip=" & ipAddress & "&key=" & strBotScoutAPIKey, False
    xml.Send
    
    responseArray = Split(xml.responseText, "|")
    
    ipResponse = responseArray(3)
    usernameResponse = responseArray(5)  
    emailResponse = responseArray(7)
    
    botCheck = CLng(ipResponse) + CLng(usernameResponse) + CLng(emailResponse)

  Set xml = Nothing
end function

%>


 


FireHOL

You may also be interested in FireHOL, a firewall blacklist composed from IP lists, including BotScout and several other bot protection services.

FireHOL is a language (and a program to run it) which builds secure, stateful firewalls from easy to understand, human-readable configurations. The configurations stay readable even for very complex setups.

FireQOS is a program which sets up traffic shaping from an easy-to-understand and flexible configuration file.