//////////////////////////////////////////////////////////////////
// BotScout.com "BotBuster" Installation Instructions ver 1.20
// SMF mod package for use with the Simple Machines 
// Forum versions 1.x and 2.x
// version 1.20 Code by MrMike / LDM 2-2009 
// For more information, see http://BotScout.com
//////////////////////////////////////////////////////////////////

What Is BotBuster?
BotBuster is an automated method of preventing web robots, or 'bots', from registering on your forum, filling out your contact forms, or other web forms. 


How It Works
The BotScout "BotBuster" works by intercepting registration attempts on your message board and silently checking the user name, email, or IP address against the BotScout.com database of known 'bot' signatures. If a match is found, the registration is halted. The BotBuster code is run via a simple 'include()' statement, so it's as close to a "drop in" installation as we could make it. 

----------------------------------------------------------

BotBuster Installation 
Installing BotScout is very easy- normally it requires just one (1) edit, usually to the registration form or registration code on your forum. What follows are installation instructions for the Simple Machines Forum, versions 1.x. It may also apply to version 2.x. If you're using this with other software (phpBB, VBulletin, etc) the steps will be similar. (If you install this on another message board type, please contact us through the BotScout.com site and we'll be glad to add the specific steps you used to this guide.) 

Installation Steps: 

1) Edit the "BotScout.php" file and uncomment the line that corresponds to your forum type (SMF, phpBB, VBulletin, etc). You may also want to turn on email notifications for the first few days so you get a notice when BotBuster stops a bot, otherwise just leave it set to "off". 


2) OPTIONAL - If you have an API key from BotScout (recommended), enter it on the line that says:

// your optional API key 
$APIKEY = '';

Put your API key between the quotes. The API key is a 10 to 15 character mix of letters and numbers. You can do a limited number of API lookups every day without an API key, but if you need to do more than a few you're better off getting an API key. API keys are free, so why not get one? Go here to get an API key: http://botscout.com/getkey.htm


(This example is for the Simple Machines Forum, if using other software this part will vary somewhat.)

3) Save the "BotScout.php" file and place it in the 'Sources' directory (again, this example is for the SMF message board, if you're using a different message board or forum your directory will be different). (You can place the BotScout.php file in a different directory if you want to- just make sure that the path you set in the next step matches where you place it.) 


4) Open the file in the Sources directory named "Register.php". Search for this code in the function named "Register2()":


	foreach ($_POST as $key => $value)
	{
		if (!is_array($_POST[$key]))
			$_POST[$key] = str_replace(array("\n", "\r"), '', trim($_POST[$key]));
	}


Directly below this code, add these lines:

	////////////////////////////////////////////////////
	// BotScout.com "BotBuster" check
	include('/path/to/your/forum/Sources/BotScout.php');
	////////////////////////////////////////////////////

Change the part that says "/path/to/your/forum/Sources/" so that it goes to the same directory you placed the "BotScout.php" file in under Step 3. 


That's it. Now when anyone tries to register on your forum the email address will be checked against the BotScout.com database. If a match is found, the registration will simply halt. Since "real" users won't have the same email address as a bot they'll be able to register without any problem. 

You can also change the "BotScout.php" file so that it checks IP addresses and/or user names, but in most cases the email address is probably the best thing to check. 


Enjoy, and Happy Hunting!

MrMike / LDM


---------------------------------
Setting Custom Application Types
If you're using an unlisted message board or using BotBuster on a contact form or other web form, you may need to use the "CUSTOM" setting. To do this, just enter the names of the form fields that correspond to the user name and the email address in the configuration section that says "CUSTOM" fields. For example, if your user name field is named "myUserName" and the email field is named "myEmailAddress", set the CUSTOM fields like this:

	// create your own custom form fields here 
	// see documentation for more information
	$XUSER = $_POST['myUserName'];
	$XMAIL = $_POST['myEmailAddress'];

Uncomment the "CUSTOM" setting under in the configuration under "Application type". That should be all you need to do. If you need assistance, contact us through the BotScout.com site. 

---------------------------------






