OVERVIEW
-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.
+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.
DONATIONS
-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.com or via the website:
+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.com or via the website:
http://wincent.com/a/products/bansshee/#donations
Perl
====
-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).
+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).
-By default Bansshee expects to find perl installed at /usr/bin/perl; if perl is installed at a different location on your system then you must edit the first line of the bansshee script to reflect the location.
+By default Bansshee expects to find perl installed at /usr/bin/perl; if perl is
+installed at a different location on your system then you must edit the first
+line of the bansshee script to reflect the location.
Perl modules
============
-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:
+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:
perl -c bansshee
-To install any missing modules you can use Perl's CPAN module. For example, to install the "File::Tail" module you could use:
+To install any missing modules you can use Perl's CPAN module. For example, to
+install the "File::Tail" module you could use:
sudo perl -MCPAN -e 'install File::Tail'
* threads
-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:
+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:
usethreads=define use5005threads=undef useithreads=define
-Note that "use5005threads" (the old thread model) is set to "undef" and the new thread implementation ("useithreads") is set to "define".
+Note that "use5005threads" (the old thread model) is set to "undef" and the new
+thread implementation ("useithreads") is set to "define".
* Sys::Syslog
-A Perl interface to the UNIX syslog(3) calls. To my knowledge this module is included with the Perl base install.
+A Perl interface to the UNIX syslog(3) calls. To my knowledge this module is
+included with the Perl base install.
* sigtrap
-A Perl pragma to enable simple signal handling. Again I believe this is included with the Perl base install.
+A Perl pragma to enable simple signal handling. Again I believe this is
+included with the Perl base install.
* Proc::Daemon
iptables
========
-Bansshee uses the iptables administration tool to control the tables of the IP packet filter rules in the kernel.
+Bansshee uses the iptables administration tool to control the tables of the IP
+packet filter rules in the kernel.
General
=======
-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).
+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).
CONFIGURATION
-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 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 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 script each time.
+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 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 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 script each time.
* permitted_illegal_user
-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.
+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.
* permitted_incorrect_pass
-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.
+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.
* unban_wait
-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).
+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).
* grace_period
-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).
+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).
* unblocking_interval
-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).
+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).
STARTING BANSSHEE
For information on installing Bansshee see the INSTALL file.
-For automatic startup at boot time see the platform-specific files in the contrib directory. If Bansshee has been set up to start automatically at boot time then it should always be started (and stopped) using the same control script. For example, on Red Had Enterprise Linux the following command would be used:
+For automatic startup at boot time see the platform-specific files in the
+contrib directory. If Bansshee has been set up to start automatically at boot
+time then it should always be started (and stopped) using the same control
+script. For example, on Red Had Enterprise Linux the following command would be
+used:
sudo service bansshee start
STOPPING BANSSHEE
-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:
+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:
sudo kill $(pidof -x bansshee)
Bansshee will catch the kill signal, perform clean-up and then exit.
-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:
+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:
sudo service bansshee stop
-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.
+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.
BANSSHEE WEBSITE
git.wincent.com / bansshee.git / commitdiff
