README

   1 $Id$
   2
   3 CONTENTS
   4
   5   * Overview
   6   * Donations
   7   * Requirements
   8   * Configuration
   9   * Starting Bansshee
  10   * Stopping Bansshee
  11   * Bansshee Website
  12   * Obtaining Bansshee
  13   * Contributing Code
  14   * Author
  15
  16
  17 OVERVIEW
  18
  19 Bansshee is a Perl script that runs as a daemon watching for SSH dictionary attacks. On detecting an attack it uses the firewall to temporarily prevent further access attempts. Many aspects of Bansshee are configurable, including the number of failed access attempts that may be generated by a given IP before they are considered an attack, how long an IP will remain on the blocklist before being removed and what the grace period should be between attempts before the internal counters are reset.
  20
  21
  22 DONATIONS
  23
  24 Bansshee is provided free of charge under the GPL (see the LICENSE file for details) so it is both free "as in beer" and free "libre". Although it is free you can encourage further development by making a donation and you are encouraged to do so if you find it to be useful. Donations can be sent via PayPal to author at win@wincent.org or via the website:
  25
  26   http://bansshee.org/donate/
  27
  28
  29 REQUIREMENTS
  30
  31 Perl
  32 ====
  33
  34 Bansshee requires a recent version of Perl compiled with multithreading support. Specifically it requires the newer "ithreads" (interpreter threads) implementation available in Perl 5.6.0 and later. This version of Bansshee was built and tested using Perl v5.8.0 (built for "i386-linux-thread-multi"). You can check the version of Perl installed on your system and whether it supports multi-threading by passing the -v or -V switch to Perl on the command line (more information on this below).
  35
  36 Perl modules
  37 ============
  38
  39 Bansshee relies on a number of Perl modules. More information about any of the modules can be found by going to http://search.cpan.org/ and performing a search for the module name. You can determine if a module is present on your system by using Perl's "-c" command line switch to check the syntax of the "bansshee" script; it will report any required modules missing from your system:
  40
  41   perl -c bansshee
  42
  43 To install any missing modules you can use Perl's CPAN module. For example, to install the "File::Tail" module you could use:
  44
  45   sudo perl -MCPAN -e 'install File::Tail'
  46
  47 Here follows a list of the modules used by Bansshee:
  48
  49 * threads
  50
  51 Bansshee is written to use the newer "ithreads" (interpreter threads) model introduced in Perl 5.6.0. To confirm that your version of Perl is compatible examine the output of "perl -V" and look for the following:
  52
  53   usethreads=define use5005threads=undef useithreads=define
  54
  55 Note that "use5005threads" (the old thread model) is set to "undef" and the new thread implementation ("useithreads") is set to "define".
  56
  57 * Sys::Syslog
  58
  59 A Perl interface to the UNIX syslog(3) calls. To my knowledge this module is included with the Perl base install.
  60
  61 * sigtrap
  62
  63 A Perl pragma to enable simple signal handling. Again I believe this is included with the Perl base install.
  64
  65 * Proc::Daemon
  66
  67 A module for running a Perl program as a daemon (background) process.
  68
  69 * File::Tail
  70
  71 A Perl extension for efficiently reading from continously updated files.
  72
  73 iptables
  74 ========
  75
  76 Bansshee uses the iptables administration tool to control the tables of the IP packet filter rules in the kernel.
  77
  78 General
  79 =======
  80
  81 Bansshee must be run with root privileges so as to be able to make modifications to the firewall using iptables, and also to monitor the log file (which may be owned by root and not world-readable).
  82
  83
  84 CONFIGURATION
  85
  86 Bansshee has a number of customizable settings that can be used to modify its behaviour. The settings appear near the top of the "bansshee" script itself under the
  87 heading "Default Settings". You may either edit the settings directly in the file itself, or place your customized settings in the "/etc/bansshee.conf" file. Settings in
  88 the conf file will override settings in the script. By using the conf file you can upgrade the Bansshee script without having to re-apply your customizations to the
  89 script each time.
  90
  91 * permitted_illegal_user
  92
  93 This is the number of attempts to log in using an illegal (unknown) username that will be permitted from a single IP address before that IP address gets blocked. Defaults to 5 attempts.
  94
  95 * permitted_incorrect_pass
  96
  97 This is the number of attempts to log in using a legal (known) username but supplying an invalid password that will be permitted from a single IP address before that IP address gets blocked. Defaults to 5 attempts.
  98
  99 * unban_wait
 100
 101 This is the minimum number of seconds that a blocked IP address must wait before it gets automatically removed from the blocklist. Defaults to 3600 seconds (1 hour).
 102
 103 * grace_period
 104
 105 This is the number of seconds that must pass before prior illegal user or incorrect password attempts from a given IP address are disregarded. Defaults to 3600 seconds (1 hour).
 106
 107 * unblocking_interval
 108
 109 This is the number of seconds that Bansshee waits before checking the blocklist and removing any IP addresses which have been in the blocklist for more than "unban_wait" seconds. Defaults to 300 (5 minutes).
 110
 111
 112 STARTING BANSSHEE
 113
 114 For information on installing Bansshee see the INSTALL file.
 115
 116 For automatic startup at boot time see the platform-specific files in the support directory. If Bansshee has been set up to
 117 start automatically at boot time then it should always be started (and stopped) using the same control script. For example,
 118 on Red Had Enterprise Linux the following command would be used:
 119
 120   sudo service bansshee start
 121
 122 For manual startup, working from the directory containing the bansshee script:
 123
 124   sudo ./bansshee
 125
 126
 127 STOPPING BANSSHEE
 128
 129 To manually stop Bansshee find its PID and kill it. For example, on a system like Red Hat Enterprise Linux which comes with a "pidof" command the following command can be used to stop Bansshee:
 130
 131   sudo kill $(pidof -x bansshee)
 132
 133 Bansshee will catch the kill signal, perform clean-up and then exit.
 134
 135 If Bansshee has been set up to start automatically at boot time then it should be stopped using the same control script that was used to start it. For example, on Red Hat Enterprise Linux the following command would be used:
 136
 137   sudo service bansshee stop
 138
 139 Unlike some other anti-dictionary attack tools currently available, Bansshee makes no attempt to save its state between sessions. This is because most attacks are transitory in nature anyway (the attacker tries and then moves on) and there is little benefit to trying to maintain state information between sessions. As a result the Bansshee code base is cleaner and less likely to contain bugs. It sets up its own IP tables rules on launch and cleans up after itself on exit. The need for a persistent store is also minimized by the fact that Bansshee is solid and stable enough to run for long periods without being restarted. At the time of writing my current Bansshee install has been up and running without interruption for an entire month without any problems.
 140
 141
 142 BANSSHEE WEBSITE
 143
 144   http://bansshee.org/
 145   http://wincent.com/a/products/bansshee/
 146
 147
 148 OBTAINING BANSSHEE
 149
 150 The latest released version of Bansshee can be downloaded from the website (link appears above).
 151
 152 The latest development version of Bansshee can be checked out via Subversion:
 153
 154   svn co svn://svn.wincent.com/bansshee/trunk
 155
 156 To check out a specific version, use the appropriate tag:
 157
 158   svn co svn://svn.wincent.com/bansshee/tags/1.0-RELEASE
 159
 160 Example tags: 1.0-RELEASE
 161
 162 To check out the latest release in a specific branch, specify the branch:
 163
 164   svn co svn://svn.wincent.com/bansshee/branches/1.0
 165
 166 Example branches: 1.0
 167
 168 Note that at the time of writing there are no special branches; all development occurs on the main trunk.
 169
 170 To update an existing working copy:
 171
 172   svn up
 173
 174 For more information on using Subversion please see the official Subversion website:
 175
 176   http://subversion.tigris.org/
 177
 178 Or the Subversion book:
 179
 180   http://svnbook.red-bean.com/
 181
 182
 183 CONTRIBUTING CODE
 184
 185 To submit changes against a copy of Bansshee checked out using Subversion (see OBTAINING BANSSHEE) simply perform an "svn
 186 diff" in your working copy and send your diff to the author (contact details below).
 187
 188
 189 AUTHOR
 190
 191 Bansshee is written and maintained by Wincent Colaiuta. Wincent's company website is:
 192
 193   http://wincent.com/
 194
 195 His personal weblog can be found at:
 196
 197   http://colaiuta.net/
 198