================================================================================

Bouncer -- a simple daemon for kicking out brute-force attackers on passwords

Copyright (c) 2016 Martin Mares <mj@ucw.cz>

All files in this package can be freely distributed and used according
to the terms of the GNU General Public License, either version 2 or
(at your opinion) any newer version. See http://www.gnu.org/ for details.

================================================================================

Introduction
~~~~~~~~~~~~
System administrators often face brute-force attacks trying to guess passwords
of users through SSH, IMAP, and other protocols. As users are generally not much
inventive when it comes to passwords, such attacks can be successful, especially
when they manage to try several passwords per second.

An obvious solution is to monitor logs for peaks of failed logins and ban the
offender's address for some time. There already exist programs which do that
(most importantly Fail2ban), but I was not satisfied with their performance,
so I decided to write my own.

Unlike other programs, this one acts in real time (instead of scanning logs
periodically). It maintains the banned IP addresses in an ipset, so it is fast
even with an enormous amount of offenders.


Theory of operation
~~~~~~~~~~~~~~~~~~~
The system logger daemon (usually rsyslogd) is configured to forward all
auth-class messages to the bouncer through a dedicated UNIX-domain socket.

The bouncer detects PAM authentication failures and remembers offending IP
addresses. When a threshold is exceeded, the IP address is added to an ipset,
which is typically matched by custom rules in iptables and thus banned.

More specifically, the offenders pass through several states:

  * suspect: we detected an authentication failure, so we keep counting.
    If a threshold is exceeded, the offender is banned (see next state).
    If a timeout passes without exceeding the threshold, the offender is
    acquitted and all data on it forgotten.

  * banned: the offender is listed in the ipset. After a timeout passes,
    it is removed from the ipset and enters probation.

  * probation: the ban was lifted, but we are still suspicious and watch
    if there are any further login failures. If so, the offender is banned
    again and the ban period is increased. If a timeout passes, the offender
    is acquitted.


Installation
~~~~~~~~~~~~
The current version can be obtained from bouncer's home page at:

	http://mj.ucw.cz/sw/bouncer/

To compile bouncer, you need:

	- LibUCW (http://www.ucw.cz/libucw/)
	- development package for libipset

You can either chant the usual `make && make install` incantation,
or create a Debian package (see debian/*).

Copy the default configuration file (./config) to /etc/bouncer and edit
it accordingly.

Configure your rsyslogd to send relevant messages to bouncer's socket.
I use the following in my /etc/rsyslogd.conf:

	$ModLoad omuxsock
	$template BouncerFormat,"%timegenerated:::date-rfc3339% %syslogtag%%msg%\n"
	$OMUxSockSocket /var/run/bouncer.sock
	auth.*,authpriv.* :omuxsock:;BouncerFormat

Configure your networking scripts to call:

	ipset create bouncer4 hash:ip family inet
	ipset create bouncer6 hash:ip family inet6

(you can omit bouncer4 or bouncer6 if you do not run IPv4 or IPv6). Also configure
your firewall (typically the INPUT chain in the main table) to reject connections
from sources contained in the ipset. For example:

	iptables -A INPUT -m set --match-set bouncer4 src -j REJECT --reject-with icmp-admin-prohibited
	ip6tables -A INPUT -m set --match-set bouncer6 src -j REJECT --reject-with adm-prohibited

Check that all your daemons using PAM pass unresolved IP addressed to it
(for OpenSSH, use "UseDNS no" in sshd_config).

Then run the bouncer daemon and watch the fireworks :)


Feedback
~~~~~~~~
Please send all bug reports and suggestions to the author.

However, please note that the author wants to keep the bouncer simple,
so requests for spectacular features outside the primary raison d'etre
will be honored quite unlikely.