GreatWebScripts.com Well Designed Scripts for the Busy WebMaster

HackTrap Users Guide



Requirements

HackerTrap Installation Manual

 

 

Table of Contents

 

 

Introduction. 1

Requirements. 3

Installation. 3

Installation Tests. 7

Setup Options. 8

First Steps. 9

Test the Installation. 9

Installation Complete. 10

Upgrade. 11

Customizations. 11

Error Page Templates. 11

Abuse Report Template. 12

Maintenance. 12

Troubleshooting. 13

Installation Failures. 13

Notices. 15

Further Information. 16

 

 

 

 

 

Introduction

 

Thank you for trying the HackerTrap™ Site Monitor.  We believe you will find it a significant aid to your site upkeep. 

 

Installation of HackerTrap is designed to be a 15-minute operation.  The installation script is designed to prompt you for needed information and guide you through the process.  After installation, we provide a setup screen you use to customize your installation to conform to your existing website look and feel.  There is actually very little information that HackerTrap needs to run as most of the values are set to default values so you can get up and running very quickly.

 

Important: HackerTrap is set by default to track, but not block, page requests to forbidden pages.  This is so that you can try out the product with no chance of interfering with your site operations.  We suggest you run HackerTrap for several days, check the logs, and if appears correct for your site, enable automatic mode.  [This setting is PROCESS_MODE on the General Parameters Page].

 

 


Requirements

 

Installation of HackerTrap™ requires the following:

  1. A webserver or web hosting account running (almost) any major Operating System (Linux, Windows, Unix) with an Apache Webserver.
  2. A SQL database system, one of:
    1. MySQL (3.22 or higher)
    2. PostgreSQL  (7.1.x or 7.2.x)
    3. MS SQL Server (7 or 2000)
    4. Microsoft db2
  3. PHP (4.3.1 or higher recommended for security, but above 4.0.3 will suffice).

 

If your hosting account does not meet the requirements above, HackerTrap cannot be installed on your account. 

                    

You will also need access on your local machine to an archival utility such as WinZIP or WinRAR to extract the product files, and an FTP Client such as FileZilla or FTP Commander to place the files on your webhosting directories.

 

Your first step after installation is to test that HackerTrap is installed correctly, and that you can recover should HackerTrap cause a problem on your site.  Do not skip this check under any circumstances.  If you cannot perform the test steps you could block yourself from being able to access your own site!

 

Before continuing, you need the following information in hand:

  1. The database type (MySQL, Postgres, etc) your webhost provides;
  2. A username to that database, with create/drop/insert/delete privileges;
  3. The password to the username account;
  4. The Host where the database server resides.  This value is typically localhost, but check with your webhosting company if unsure.

 

Installation

 

This section details how to install HackerTrap if you have never installed a copy on your site before.  See here for upgrade instructions if HackerTrap is already installed and you are trying to upgrade to a later version.

 

  1. Unzip the HackerTrap delivery package to your local drive.
  2. FTP all files to your host /HackerTrap.
    1. All .php, .sql, .css, .txt and .htm files should be uploaded in ASCII mode, while all graphics should be uploaded in BINARY mode. If you are unfamiliar with what this means please refer to your FTP client documentation. In most cases this is all handled transparently by your FTP Client but if you have problems later you should be sure the files where uploaded correctly as described here.
  3. Run the installer by pointing your web browser to http://www.yourhost.com/HackerTrap/install/install.php

 

You should see the HackerTrap Installation Script Display (Figure 1) below appear.

 

Figure 1: Installation Script Initial Display

Step 1 is to select the database type (also referred to as DBMS, DataBase Management System) your web hosting provides.  If you do not know the database type, contact your hosting company for details.

 

Step 2 is to provide the details of how to connect into the database; this includes the server where the database is installed, the username and password, and the name of the database to use.

 

The last step is to enter the Administrator Login name and Password you want to use.  This is required each time you start a session with HackerTrap and is designed to prevent unauthorized access.  Please select a Login name you will remember and a strong password containing a mix of letters and numbers.  You can change the login/password later if you desire.

 

When completed press the Submit Button.  The installation script will create and populate the necessary tables and create the configuration file.  The installation status is displayed in the top window, along with any suggested changes.  If any errors are detected, correct the problem and press the Submit Button again.  When the installation parameters are correctly configured, you will see the following status window (Figure 2):

 

Figure 2: Successful Installation Display

 

 

This indicates the installation was successful, and we can now proceed to verify the installation.

 

 

Installation Tests

 

The Installation Tests verify that HackerTrap is installed correctly and show you how to recover should you accidentally block yourself from accessing your site.  You can run the tests whenever and as many times as you need.

 

The status icons indicate the results of the tests:

  1. indicates the test was never run and hence no status is known.  This is the initial start point for each test.
  2.  indicates the test is in progress.  The status will not be known until the test is completed.
  3.   indicates the test was run but failed.  You should rerun the test and ensure it passes before using HackerTrap.  If you cannot resolve the problems, contact Technical Support at GreatWebScripts for  help.
  4.  indicates the test was run and was successful.

 

The Installation Tests are:

  1. .htaccess Operation: This test verifies that your webserver is the correct type (Apache) and will honor the htaccess file that HackerTrap creates.  It has two steps: the ALLOWED step, where access to an image is permitted based on settings in the htaccess file, and the DENIED step where access is prohibited based on the settings.  Press the button to start the test, and follow the directions within.
  2. Reset Operation: This test verifies that you are able to find and delete the htaccess file if necessary.  The file you are asked to delete is NOT the htaccess file, but a similar file in the same directory.

 

When the status indicates the tests were successful you can select the Setup Options you wish to set.  Select the link under “Please go to this page and complete the setup”, and you will see the Configuration page display.

 

 

Setup Options

 

The Setup Options Display allows you to select various parameters that affect how HackerTrap™ works.  Unlike the Installation Script from the previous step which is intended to be run only once, the Setup Options can be run anytime you want to update your selections.

 

The Setup options are split into several tabs.  First, visit the General tab and customize overall system parameters.  It is recommended you review and customize the top three parameters: Server Time Offset, Admin Email and Logo Image.  Explore the other parameters at your leisure.

 

Before leaving, press the HELP button.  HackerTrap comes with an extensive integrated context-sensitive help system.  Context-sensitive means the HELP is customized to the specific display you are on.  Note that the display is set for the General Parameters display – as you go through the other displays, press the HELP button for specific details and tips on each.

       

 

First Steps

 

You should notice a yellow message box indicating that the installation scripts are still present on the site.    In all cases, before you allow public access to HackerTrap, ensure you delete the installation scripts.  Leaving the scripts in place with a production system is a very serious security issue.  (If you decide you need the installation scripts after deletion, simply upload that install/ directory via your FTP Client).

 

The next step is to protect your own IP address from being blocked.  This minimizes the possibility that you will be locked out from your own site.  Press the Whitelist tab.  You will see an (empty) list of the IP addresses that are protected against being blocked.  Press the AddMe button at the bottom, and your IP address is added to the list.  Press the Save button to save off your addition.

 

Finally, visit the htaccess tab.  Scroll to the bottom of the display and press the Install button.  This replaces your site htaccess file (which may be empty) with the HackerTrap generated file, and completes the install of HackerTrap.

 

Test the Installation

 

This section ensures that HackerTrap is functioning by testing its search and log capabilities.

 

Visit the Forbidden tab.  At the bottom in the Test Field, enter the string: a/cmd.exe and press the Test button.  You will see a notice at the top of the display:

 

Page 'a/cmd.exe' is Permitted:
[BLACKLIST: */cmd.exe*, but ip WHITELIST: xx.xx.xx.xx]

 

The xx.xx.xx.xx will be replaced by your IP address.  This confirms that HackerTrap is able to detect the pattern and that your address is on the WhiteList.

 

Next, we will confirm that HackerTrap has replaced your Error Pages for 404 errors.  Fill in the address field on your browser with a non-existent page on your site by appending a “/xxx.yyy” onto the end of the field.  You should get an error message like the one below:

 

 

Figure 3: Missed Page Display

Now hit the “Back” button on your browser, and you should be taken to the HackerTrap Forbidden page.  Press the PageMiss tab at the top.  Ensure the missed page you just entered is in the log.

 

This confirms that HackerTrap has replaced your error processing and is monitoring your site for errors and hack attempts.

 

Installation Complete

 

This completes the installation process for HackerTrap – but you should be aware the HackerTrap is not set to automatically protect your site at this point.  By default, HackerTrap is configured to monitor, but not block access, to your site.  This is done so that you may experience HackerTrap working without interfering with normal site operations.  There may be cases where you expect a normal visitor to access some external page, and you do not want to block them. 

 

Run HackerTrap for several days.  Check the PageMiss and PageBlock logs periodically (reference the section below for more advice).  Check the IPs added to the BlackList.  If all seem to be what you want to ban, you can set the ProcessMode to AUTOMATIC on the General Parameters section.

 


Upgrade

 

This section details how to upgrade to a later version of HackerTrap from an earlier one.  It assumes HackerTrap is already installed and working at your site.  See here for information on how to install HackerTrap if you do not have an earlier version installed.

 

Before starting, backup your data, including the php files, and especially the data from the database.  Reference your web hosting provider documentation for steps on how to backup your database.

 

  1. Backup your data!
  2. Unzip the archive to your hard drive
  3. FTP the files up to the HackerTrap directory on your web host.
  4. Point your browser to http://<sitename>/hackertrap/install/install.php.
  5. a. Under the database section, if there is a ‘LoadDB’ button select it to update your database.

b  If there is no ‘LoadDB’ button, select the ‘Submit’ button at the bottom of the display.  This will update your database with the latest default set of parameter without disturbing your current installation.

Please ensure you select either the’ LoadDB’ or the’ Submit’ button before leaving this window.

  1. Select the link under “Please go to this page and complete the setup”, and review the Parameters to ensure they are customized to your desires (reference next section).

 

 

 

Customizations

 

Error Page Templates

 

You can customize the error templates HackerTrap displays better harmonize with your site.  There are several files in the /templates directory that are used to display the error pages for Missed and Blocked pages:

  1. bannedIP_html.php (optional): is the page displayed when a blacklisted (banned) IP attempts to access a page on your site.  If this file is not provided, the 403_html.php page below is used.
  2. 403_html.php: is the 403 / Forbidden Page Handler.  It is displayed when a banned IP attempts to access a site page and the bannedIP_html.php page is not found; OR if the user attempts to access a password-protected page and does not supply the correct password.
  3. bannedPage_html.php (optional): is the page displayed when a user attempts to access a banned page (a page that matches an entry in your Forbidden List).  This is usually the last page that user will see from your site, as his IP will then be added to the BlackListed IPs.  If this file is not provided, the 404_html.php page below is used.
  4. 404_html.php: is the 404 / Page Not Found Handler. It is displayed when a user enters a URL that is not supplied by your site, but is not in your Forbidden List.  It is a typical user error, and does not cause the IP to be blacklisted.

 

You may enter standard html into these pages, or if you are familiar with php, you can use it as well as long as it is enclosed with <?php and ?> characters. 

 

The entire set of standard $_SESSION and $_SERVER variables are available.  The following list contains the commonly used variables:  To display these variables, use the format

  <?php ech  <variablename> ?>, as in <?php echo $_SERVER ['REMOTE_ADDR']?>

 

  1. $_SERVER ['REMOTE_ADDR'] :                  IP Address of user
  2. $_SERVER ['HTTP_HOST] :              Your host (domain name)
  3. $_SERVER [‘REQUEST_URI’]:                     The page (URL) that was requested

 

 

Abuse Report Template

 

You can customize the Abuse Report that HackerTrap generates by modifying the file hacktrap.abuse.txt in the /templates directory.  This is the body of the report that is generated and placed into an email frame for you automatically.  The following variables are available and automatically translated for you:

 

To display these variables, use the format  %variablename%  

 

 

  1. DOMAIN                                Your domain, used to indicate sending site
  2. ABUSE_DOMAIN                 The domain of the IP where the abuse originated
  3. ABUSE_IP                              The IP Address where the abuse originated
  4. ABUSE_LIST                          The formatted list of IP, time, URL constituting the

  abuse; this makes up the body of the report.

  1. SOURCE_EMAIL                   Your email address where questions or comments

  may be sent.  

 

 

Maintenance

 

From here, the only tasks left is to monitor the site Activity Log  – initially on a daily basis, then less often as you gain confidence in HackerTrap.  Ensure the proper accesses are blocked.  If you haven’t set ProcessMode to AUTOMATIC, consider doing so now. The portions to monitor are:

  1. BlackListed IPs: ensure the IPs added are correct.  Ensure someone has not inadvertently entered the list due to a typo (not likely, but always a possibility).
  2. PageBlocked Log: Check how many and how often access are blocked.  Generally a spammer will send several requests in a short span, so many attempts from the same address is not necessarily a sign of an attack, but someone running a script.
  3. PageMiss Log: Check how many pages are missed.  This is also useful to indicate broken links on your site that need to be corrected.  If you see many bad entries from a single IP, you may need to add another entry to the Forbidden List.

 

 

Troubleshooting

 

Installation Failures

 

This section deals with problems that preclude the installation from completing.  They are indicated by Red Errors at the top of the HackerTrap Installation Screen.

 

Message

Explanation

Remedy

Could not connect to database: verify username, password, and host.

HackerTrap could not connect to your database.

Double check the values you supplied for username, hostname, and password are correct and try again.

No write access to current directory

HackerTrap must write to the current directory it is installed in to create the configuration file

Before Installation:

   - chmod the /hackertrap directory to 0755

  

Post Installation:

   - chmod the /hackertrap directory to 0555

   - You may chmod all php files to 0555, but will

        need to chmod before running the update

        install script again (to install an update)

Could not write to test file

HackerTrap must write to the current directory it is installed in to create the configuration file.

Ensure the hackertrap directory default file creation privileges are set to 0755.

Could not close test file

HackerTrap must write to the current directory it is installed in to create the configuration file.

Ensure the hackertrap directory default file creation privileges are set to 0755.

Could not delete test file

 

Before Installation:

   - chmod the /hackertrap directory to 0755

  

Post Installation:

   - chmod the /hackertrap directory to 0555

   - You may chmod all php files to 0555, but will

        need to chmod before running the update

        install script again (to install an update)

DB Create Failed: <reason code>

HackerTrap received an error when creating the database tables.

Ensure the database account you created has Privileges to create tables in the account.

DB Update Failed: <reason code>

You are attempting to update your database to the latest version and the update failed.

Determine reason from the reason code displayed.

Failed to backup .htaccess file!

HackerTrap could not create a backup copy of the current .htaccess file.

Before Installation:

   - chmod the /hackertrap directory to 0755

  

Post Installation:

   - chmod the /hackertrap directory to 0555

   - You may chmod all php files to 0555, but will

        need to chmod before running the update

        install script again (to install an update)

Please enter the <parameter>

Not all required input was provided.

Provide the data indicated and press the Submit button.

Error Creating the Configuration File

HackerTrap must write to the current directory it is installed in to create the configuration file

Before Installation:

   - chmod the /hackertrap directory to 0755

  

Post Installation:

   - chmod the /hackertrap directory to 0555

   - You may chmod all php files to 0555, but will

        need to chmod before running the update

        install script again (to install an update)

Error writing the Configuration File

HackerTrap must write to the current directory it is installed in to create the configuration file

Before Installation:

   - chmod the /hackertrap directory to 0755

  

Post Installation:

   - chmod the /hackertrap directory to 0555

   - You may chmod all php files to 0555, but will

        need to chmod before running the update

        install script again (to install an update)

Failed to close DB Configuration File

HackerTrap must write to the current directory it is installed in to create the configuration file

Before Installation:

   - chmod the /hackertrap directory to 0755

  

Post Installation:

   - chmod the /hackertrap directory to 0555

   - You may chmod all php files to 0555, but will

        need to chmod before running the update

        install script again (to install an update)

 

 


Notices

 

This section deals with notices that HackerTrap supplies during installation.  These messages appear in a whitebox at the top of the display.

 

 

 

Message

Explanation

Remarks

Connected to DBMS

HackerTrap used the database parameters you supplied to connect to the database.

Expected Message.  The database username and password are correct.

Tables Created

HackerTrap created the database tables

Expected Message

Tables Loaded

HackerTrap loaded the default values into the tables

Expected Message

Database created and loaded

HackerTrap completed the installation of the database.

Expected Message

Existing Database retained

HackerTrap updated the installation without modifying your existing data.

Expected Message

Database Reload Failed: <error text>

You attempted to update your installation, but HackerTrap was not able to update the database tables completely.

Determine reason from error text supplied.

Created .htaccess file back up

On initial installation HackerTrap creates a backup copy of your site .htaccess file for safekeeping.

Expected Message

Original .htaccess file not present

On initial installation HackerTrap attempted to create a backup of your site .htaccess file but none was found.

Expected Message

Could not read site data

(I won't be able to lookup IP Addresses)

Attempting to open a socket to read from another site failed.  HackerTrap will work correctly except the Abuse Reports will not be able to determine the destination email address correctly.

Ensure the allow_url_fopen setting in php.ini is enabled.

Could not read site data

(I won't be able to lookup IP Addresses)

Attempting to read from another site failed.  HackerTrap will work correctly except the Abuse Reports will not be able to determine the destination email address correctly.

Ensure the allow_url_fopen setting in php.ini is enabled.

Could not open a socket to a webpage (I won't be able to lookup IP Addresses)

Attempting to open a socket to read from another site failed.  HackerTrap will work correctly except the Abuse Reports will not be able to determine the destination email address correctly.

Ensure the allow_url_fopen setting in php.ini is enabled.

HackerTrap Successfully Installed: ({$install_type})

Installation/Upgrade completed successfully.

Expected Message

 

 

 

Further Information

 

HackerTrap contains an extensive list of suggestions, tips, and explanations in its HELP section.  The HELP files are context-sensitive so you can aid on what you’re doing, when you’re doing it.  Press the HELP button for an individual display to see specific, targeted information on what that screen presents and what actions you can take.

 

For more specific and advanced issues, GreatWebScripts maintains an 24´7 online forum for customer questions, comments, and other feedback.  Visit our board at www.greatwebscripts.com/support for individual assistance.