+VERSION=1.0
+PACKAGE=bouncer-$(VERSION)
+
PKG_CFLAGS := $(shell pkg-config --cflags libucw libipset)
PKG_LIBS := $(shell pkg-config --libs libucw libipset)
clean:
rm -f `find . -name "*~" -or -name "*.[oa]" -or -name "\#*\#" -or -name TAGS -or -name core -or -name .depend -or -name .#*`
rm -f bouncer
+ rm -f bouncer-*.tar.gz bouncer-*.tar.sig
install: bouncer
install -d $(DESTDIR)/usr/sbin $(DESTDIR)/etc
install -m755 bouncer $(DESTDIR)/usr/sbin/
install -m644 config $(DESTDIR)/etc/bouncer
+
+release:
+ git tag --sign v$(VERSION)
+ git push --tags
+ git archive --format=tar --prefix=$(PACKAGE)/ HEAD >$(PACKAGE).tar
+ gpg --armor --detach-sign -o $(PACKAGE).tar.sig $(PACKAGE).tar
+ gzip $(PACKAGE).tar
+ scp $(PACKAGE).tar.gz $(PACKAGE).tar.sig atrey:~ftp/pub/local/mj/linux/
+ scp README jw:web/sw/bouncer/
+ ssh jw "cd web && bin/release-prog bouncer $(VERSION)"
+ mv $(PACKAGE).tar.gz $(PACKAGE).tar.sig ~/archives/mj/
-This is Bouncer. More information to come.
+================================================================================
+
+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.
projects / bouncer.git / commitdiff