README

   1 ================================================================================
   2
   3 Bouncer -- a simple daemon for kicking out brute-force attackers on passwords
   4
   5 Copyright (c) 2016 Martin Mares <mj@ucw.cz>
   6
   7 All files in this package can be freely distributed and used according
   8 to the terms of the GNU General Public License, either version 2 or
   9 (at your opinion) any newer version. See http://www.gnu.org/ for details.
  10
  11 ================================================================================
  12
  13 Introduction
  14 ~~~~~~~~~~~~
  15 System administrators often face brute-force attacks trying to guess passwords
  16 of users through SSH, IMAP, and other protocols. As users are generally not much
  17 inventive when it comes to passwords, such attacks can be successful, especially
  18 when they manage to try several passwords per second.
  19
  20 An obvious solution is to monitor logs for peaks of failed logins and ban the
  21 offender's address for some time. There already exist programs which do that
  22 (most importantly Fail2ban), but I was not satisfied with their performance,
  23 so I decided to write my own.
  24
  25 Unlike other programs, this one acts in real time (instead of scanning logs
  26 periodically). It maintains the banned IP addresses in an ipset, so it is fast
  27 even with an enormous amount of offenders.
  28
  29
  30 Theory of operation
  31 ~~~~~~~~~~~~~~~~~~~
  32 The system logger daemon (usually rsyslogd) is configured to forward all
  33 auth-class messages to the bouncer through a dedicated UNIX-domain socket.
  34
  35 The bouncer detects PAM authentication failures and remembers offending IP
  36 addresses. When a threshold is exceeded, the IP address is added to an ipset,
  37 which is typically matched by custom rules in iptables and thus banned.
  38
  39 More specifically, the offenders pass through several states:
  40
  41   * suspect: we detected an authentication failure, so we keep counting.
  42     If a threshold is exceeded, the offender is banned (see next state).
  43     If a timeout passes without exceeding the threshold, the offender is
  44     acquitted and all data on it forgotten.
  45
  46   * banned: the offender is listed in the ipset. After a timeout passes,
  47     it is removed from the ipset and enters probation.
  48
  49   * probation: the ban was lifted, but we are still suspicious and watch
  50     if there are any further login failures. If so, the offender is banned
  51     again and the ban period is increased. If a timeout passes, the offender
  52     is acquitted.
  53
  54
  55 Installation
  56 ~~~~~~~~~~~~
  57 The current version can be obtained from bouncer's home page at:
  58
  59         http://mj.ucw.cz/sw/bouncer/
  60
  61 To compile bouncer, you need:
  62
  63         - LibUCW (http://www.ucw.cz/libucw/)
  64         - development package for libipset
  65
  66 You can either chant the usual `make && make install` incantation,
  67 or create a Debian package (see debian/*).
  68
  69 Copy the default configuration file (./config) to /etc/bouncer and edit
  70 it accordingly.
  71
  72 Configure your rsyslogd to send relevant messages to bouncer's socket.
  73 I use the following in my /etc/rsyslogd.conf:
  74
  75         $ModLoad omuxsock
  76         $template BouncerFormat,"%timegenerated:::date-rfc3339% %syslogtag%%msg%\n"
  77         $OMUxSockSocket /var/run/bouncer.sock
  78         auth.*,authpriv.* :omuxsock:;BouncerFormat
  79
  80 Configure your networking scripts to call:
  81
  82         ipset create bouncer4 hash:ip family inet
  83         ipset create bouncer6 hash:ip family inet6
  84
  85 (you can omit bouncer4 or bouncer6 if you do not run IPv4 or IPv6). Also configure
  86 your firewall (typically the INPUT chain in the main table) to reject connections
  87 from sources contained in the ipset. For example:
  88
  89         iptables -A INPUT -m set --match-set bouncer4 src -j REJECT --reject-with icmp-admin-prohibited
  90         ip6tables -A INPUT -m set --match-set bouncer6 src -j REJECT --reject-with adm-prohibited
  91
  92 Check that all your daemons using PAM pass unresolved IP addressed to it
  93 (for OpenSSH, use "UseDNS no" in sshd_config).
  94
  95 Then run the bouncer daemon and watch the fireworks :)
  96
  97
  98 Feedback
  99 ~~~~~~~~
 100 Please send all bug reports and suggestions to the author.
 101
 102 However, please note that the author wants to keep the bouncer simple,
 103 so requests for spectacular features outside the primary raison d'etre
 104 will be honored quite unlikely.