wincent / bansshee Goto Github PK

CONTENTS

  * Overview
  * Donations
  * Requirements
  * Configuration
  * Starting Bansshee
  * Stopping Bansshee
  * Bansshee Website
  * Obtaining Bansshee
  * Contributing Code
  * Author


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.


DONATIONS

Bansshee is provided free of charge under the simplified, 2-clause version of
the BSD license, as used by FreeBSD (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
[email protected] or via the website:

  http://wincent.com/a/products/bansshee/#donations


REQUIREMENTS

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).

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:

  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:

  sudo perl -MCPAN -e 'install File::Tail'

Here follows a list of the modules used by Bansshee:

* 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:

  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".

* Sys::Syslog

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.

* Proc::Daemon

A module for running a Perl program as a daemon (background) process.

* File::Tail

A Perl extension for efficiently reading from continously updated files.

iptables
========

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).


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.

* 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.

* 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.

* 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).

* 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).

* 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).


PLATFORM-SPECIFIC CONFIGURATION

In addition to the already-discussed configuration variables, there are a
number of settings which may need to be adjusted depending in order to make
Bansshee work on different platforms. These settings are:

* logpath

The path to the logfile that Bansshee should watch in order to detect breakin
attempts. Defaults to "/var/log/secure".

* illegal_user_regex

A regular expression used to detect log entries corresponding to attempt to log
in using an illegal/invalid (non-existent) user. The regular expression should
contain two parenthesised subpatterns, one for the username and one for the
remote IP address, so that Bansshee can extract those subpatterns. If you need
to use brackets for any other part within the regular expression than you
should use a non-capturing subpattern -- denoted with (?:subpattern) --
instead; see the RHEL 5.3 configuration file in the contrib directory for an
example of this.

* incorrect_pass_regex

Like the illegal_user_regex, this setting provides a regular expression to
detect connection attempts which supply a valid user but an incorrect password.
Again, two parenthesised subpatterns (for username and remote IP) are required
so that Bansshee can extract the corresponding information.

* iptables

The path to the iptables executable. Defaults to "/sbin/iptables".

* iptables_create

Arguments that should be passed to iptables to create the BANSSHEE chain.
Defaults to "-N BANSSHEE".

* iptables_add

Arguments that should be passed to iptables to add the BANSSHEE jump rule.
Defaults to "-I INPUT -p tcp --dport ssh -j BANSSHEE".

* iptables_remove

Arguments that should be passed to iptables to remove the BANSSHEE jump rule.
Defaults to "-D INPUT -p tcp --dport ssh -j BANSSHEE".

* iptables_flush

Arguments that should be passed to iptables to flush the BANSSHEE chain.
Defaults to "-F BANSSHEE".

* iptables_delete

Arguments that should be passed to iptables to delete the BANSSHEE chain.
Defaults to "-X BANSSHEE".

* id

Command that should be executed to determine if Bansshee is running as root.
Defaults to "/usr/bin/id -u".

* log_facility

Controls Bansshee's logging of status messages to /var/log/secure or similar.
Defaults to "authpriv".

The default settings were developed and tested using Red Hat Enterprise Linux
ES3 and may work with other platforms.

In addition there are some user-contributed support files in the "contrib"
directory that may be helpful when setting up Bansshee on other platforms.


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:

  sudo service bansshee start

For manual startup, working from the directory containing the bansshee script:

  sudo ./bansshee


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:

  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:

  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.


BANSSHEE WEBSITE

  http://wincent.com/a/products/bansshee/


OBTAINING BANSSHEE

The latest released version of Bansshee can be downloaded from the website
(link appears above).

You can clone the source code repository using Git:

  git clone git://git.wincent.com/bansshee.git

Or explore the repository contents using a browser:

  http://git.wincent.com/bansshee.git

Older versions can be checked out via Subversion:

  svn co svn://svn.wincent.com/bansshee


CONTRIBUTING CODE

To submit changes to Bansshee please use "git format-patch" (see OBTAINING
BANSSHEE for information on cloning the repository) and send your patch via
email to [email protected].


AUTHOR

Bansshee is written and maintained by Wincent Colaiuta:

  http://wincent.com/
  [email protected]