README.install
$Id: README.install,v 1.10 1999/03/22 04:57:16 crowland Exp crowland $ HostSentry Quick Installation Instructions =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- PLEASE READ ALL THE DOCS BEFORE USING THIS PROGRAM. This program is fairly easy to setup and run, but it can perform actions on your host that may block users, drop routes to systems and other assorted goodies. If you don't read the documentation to fully understand what is going on then you may break something. While the default install is set to only log infractions, it is imperative that you know how the program is fully running. Load Python =-=-=-=-=-= This program requires Python 1.5.1 or higher to run. This program ships with many versions of Unix. If your system does not have this program then please go to: http://www.python.org There are two modules you need to activate in your Python build to run HostSentry: syslog (for logging) dbm/gdbm (for DB functions) - Download Python sources. - Go to the Modules directory under Python. - Edit the "Setup" file under this directory and uncomment the "syslog" module. - Edit the "Setup" file under this directory and uncomment the "gdbm" or "dbm" module (gdbm preferred). - Re-compile and install. Check Directories =-=-=-=-=-=-=-=-= The makefile with this program will want to install HostSentry in the following directories: /usr/local/abacus/hostsentry /usr/local/abacus/hostsentry/modules If this is not where you want the files you will need to edit the makefile and change this setting. Run Make =-=-=-=- Type 'make install' and the Makefile will make directories and copy the files with the correct permissions to the directory described above. Edit Config File =-=-=-=-=-=-=-=- Filename: hostsentry.conf Go to the HostSentry install directory and edit the file hostsentry.conf. Make sure the paths are pointed to the install directory for the fields: IGNORE_FILE ACTION_FILE MODULE_FILE MODULE_PATH DB_FILE DB_TTY_FILE The field WTMP_FILE should point to your system wtmp directory (typically in /var/log/wtmp for Linux). Most installations will not have to change any of the above. The field WTMP_FORMAT tells HostSentry what your wtmp entries will look like. Because many Unices use different "standards" (See README.wtmp) you may have to change this. Several defaults are provided, please choose the one that closest fits your system. If you are not getting HostSentry to recognize your logins/logouts you probably have the wrong format selected. If you cannot get any of the formats to work you can try making your own. This process is described in the conf file. If you get an unknown format to work for your box please send it to me so I can include it in future builds. BETA NOTE: Future (non-beta) versions will probably have a built in Python module to handle wtmp/utmp and this hack will go away. Edit Modules File =-=-=-=-=-=-=-=-= Filename: hostsentry.modules The modules file tells HostSentry what modules to execute on login/logout and in what order. If you don't want a particular module to run for whatever reason (false alarms, not interested, etc.) then delete it here. If you, for some reason, want to re-order the execution of modules (you want to check for foreign domains first before anything, etc.) then you can just move the modules from top to bottom to affect this operation. Most installations will not have to change this file. Edit Ignore File =-=-=-=-=-=-=-=- Filename: hostsentry.ignore The file hostsentry.ignore contains a list of users you want HostSentry to never process with the modules and never take action against. This is useful for users such as "ftp" who show up in wtmp but would cause a large number of false alarms because of the anonymous access. Place only one user per line. It's important to note that users in this file will still have a DB entry created and updated just like normal users. This is useful if you still want to do processing on other aspects of the users with separate scripts later on. Edit Action File =-=-=-=-=-=-=-=- Filename: hostsentry.action NOT IMPLEMENTED YET READ THE MODULE INSTRUCTIONS =-=-=-=-=-=-=-=-=-=-=-=-=-=- Filename: README.modules Some of the modules have their own files that need to be modified to properly operate. PLEASE read the README.modules documentation for information on how to do this!!! READ THE INTRO =-=-=-=-=-=-=- Filename: README.intro Find out what HostSentry is and is not and what it will and will not protect you from. Start HostSentry =-=-=-=-=-=- Run hostsentry by hand to make sure it initializes correctly: python hostsentry.py Your syslog should be watched for any errors or warnings. A successful startup will look like this: Oct 28 19:22:46 somehost hostsentry[30542]: adminalert: HostSentry version X is initializing Oct 28 19:22:46 somehost hostsentry[30542]: adminalert: Send bug reports to <crowland@psionic.com> Oct 28 19:22:46 somehost hostsentry[30542]: adminalert: HostSentry is active and monitoring logins. Test =-=- Perform some logins/logouts and you should see various hostsentry messages appear in your logs such as: Oct 28 19:24:08 somehost hostsentry[30542]: adminalert: LOGIN User: crowland TTY: ttyp6 Host: 192.168.2.12 Oct 28 19:24:08 somehost hostsentry[30542]: securityalert: First time login for user: crowland Oct 28 19:24:08 somehost hostsentry[30542]: securityalert: Action being taken for user: crowland Oct 28 19:24:08 somehost hostsentry[30542]: securityalert: Module requesting action is: moduleFirstLogin Oct 28 19:24:08 somehost hostsentry[30542]: securityalert: Foreign domain login detected for user: crowland from: 192.168.2.12 Oct 28 19:24:08 somehost hostsentry[30542]: securityalert: Action being taken for user: crowland Oct 28 19:24:08 somehost hostsentry[30542]: securityalert: Module requesting action is: moduleForeignDomain Anomaly detection requires time to establish patterns in how users interact with the host. As a result it may take some time for HostSentry to "learn" login behavior and messages will decrease for users accordingly. BETA NOTE: This early version is very verbose. The later revisions will cut back on the amount of logging done. Automate Startup =-=-=-=-=-=-=-=- Have HostSentry run on system startup automatically by editing your rc.local or init files according to your OS. (ALPHA NOTE: Detailed instruction will be provided later in doc revs) Write if you have any questions. Thanks for using HostSentry!! -- Craig <crowland@psionic.com>