-
Notifications
You must be signed in to change notification settings - Fork 0
Anti-SSH-attack tool
License
wincent/bansshee
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
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 win@wincent.com 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 win@wincent.com. AUTHOR Bansshee is written and maintained by Wincent Colaiuta: http://wincent.com/ win@wincent.com