SSHblock

SSHblock is intended to dynamically and automatically stop SSH-based dictionary attacks. Even if you have secure passwords and are sure no attacker will be able to get in, it can still be annoying to have your logs littered with “failed password” messages. SSHblock automatically blocks any IP address that fails an SSH login too many times too quickly, and automatically unblocks it after a while.

How long? That depends on how many times that IP address has already been blocked; SSHblock tracks repeat offenders and applies an exponential increase algorithm to block repeat offenders for progressively increasing times.

SSHblock consists of a pair of Perl scripts, a Bourne-Again rc/init script, and a file containing a couple of Swatch rules. It also includes an installation script that interactively prompts for your desired install location and reporting options, checks for all needed dependencies, and sets everything up for you.

Features

Uses an exponential increase algorithm to ramp up the blocking time for repeat offenders.
Includes rc/init script for easy administration.
Allows whitelisting of IP addresses that should never be blocked.
Logs activity using standard Unix syslog facility.
Can also send email to an administrator when an address is blocked for the Nth or greater time (where N is configurable).

Requirements

Perl 5.004: SSHblock is written in Perl.
iptables: SSHblock does its blocking by adding a firewall rule to iptables.
Linux 2.4 or greater: Required by iptables. Theoretically, you could backport SSHblock to Linux 2.2 by simply changing all iptables commands to their corresponding ipchains equivalents, but I haven’t tried.
Swatch: SSHblock detects dictionary attacks in progress by watching for a bunch of “failed password” alerts in your log files. It relies on Swatch (the “Simple WATCHer”) to do this.

SSHblock’s installation script will check for all of these dependencies as part of the installation process.

Documentation

You’re reading it. There are also man pages available using perldoc for the two executable Perl scripts, sshblock.pl and sshunblock.pl. Just run perldoc -u scriptname after installation to read those man pages.

Download

Version 0.5: sshblock-0.5.tar.bz2

Installation

Get a copy of the SSHblock installation tarball. Extract it and cd into the directory it creates.
Run install.pl. It will prompt you for a few configuration values, giving sensible defaults for most or all of them.
You’re done! The install script should activate SSHblock and set it to start automatically on the next reboot. If it has any troubles, it will let you know.

Frequently Asked Questions

What counts as “an attack”?

SSHblock has Swatch watch your main log file (usually /var/log/messages) for “failed password” messages. If it sees 3 or more “Failed password for invalid user (whoever)” within 90 seconds from the same IP address, it blocks that address. If it sees 3 or more “Failed password for root” messages from one IP within 30 seconds, it also considers that an attack.

How long does SSHblock block an attacking IP address for?

That depends on how many times the address has been blocked before. The timing is actually maintained by a formula in sshunblock.pl: every time it gets invoked, sshunblock checks each currently-blocked address to see how long it’s been blocked for, and if its block time has expired, then it gets unblocked.

If you don’t fiddle with the default parameters, the schedule will work out as follows:

When Blocked for Nth Time	Block Time in Hours	Block Time in Days
1	3	0.125
2	12	0.5
3	48	2
4	192	8
5	768	24
6	3,072	96
7	12,288	384

You should very quickly find that “repeat offenders” cease to be a problem. People who can’t secure their machines will no longer be able to SSH into — or perform dictionary attacks against — yours.

It looks like SSHblock can actually block for longer than the number of hours listed in that table.

Example: If someone dictionary-attacks you at 3 minutes after midnight, and then gets blocked for 12 hours (because this is the second time they’ve attacked you), their blocking time should theoretically expire at 12:03 pm. However, SSHblock won’t actually unblock them until the next scheduled sshunblock.pl run, at 1:00 pm.

SSHblock doesn’t guarantee immediate unblocking the moment the IP has been blocked for precisely N hours. Instead, it works on the assumption that if an address has been dictionary-attacking you, unblocking it at all is something of a courtesy, and if the unblocking happens up to an hour late, the attacker will have to live with that.

You can consider all the times in the table above to be “anywhere from N hours to N+1 hours” — e.g., the 4th time an address is blocked, it will be blocked for anywhere from 192-193 hours.

When I try to install SSHblock, it aborts because I don’t have Swatch installed. When I try to install Swatch, the make step bombs with “make error[2]”. What can I do?

If you were doing “perl Makefile.PL && make && make test && make install”, the results of the first step may have gone by too fast for you to see. It may be warning you about missing CPAN packages; Swatch requires a few other packages of its own. Try just “perl Makefile.PL”, and if the output warns of missing dependencies, install those using CPAN.

Uninstallation

If you want to uninstall SSHblock, here’s how you could do it. Note that these steps assume you installed everything to its default location.

/etc/init.d/rc.sshblock stop
/etc/init.d/rc.sshblock clear
rm /etc/init.d/rc.sshblock
rm /usr/local/sbin/sshblock.pl
rm /usr/local/sbin/sshunblock.pl
rm /etc/swatch/sshblock
rm /etc/ssh/block-history
rm /etc/cron.hourly/sshunblock

If you’ve changed the installation file paths and don’t remember what you changed them to, you can try doing ps auxww | grep swatch | grep sshblock. You should see a pointer to the swatch config file; that will tell you where to find the binaries. Reading those should help you find everything else.

Feedback

If you have ideas or suggestions, or want to report bugs, or want to contact me in other ways, you can reach me at kai@mactane.org. I welcome bug reports, feature requests, and any other comments or suggestions.

License

SSHblock is released under the Apache License, Version 2.0. It’s a fairly straightfoward open-source license that allows unrestricted use, copying, modification and redistribution, but keeps anyone from closed-sourcing it.