pam_sieĝo
---------

This is a pam module that helps to defend your "castle", by closing
the "gate" for visitors that repeatedly unsuccesfully try to come in.

This program is licensed GNU GPL (see COPYING).

The language is Esperanto. To start using it, delete the line "#define
UTF8 1" in pam_siegho.c (i suppose you want the non UTF-8 version,
without the "strange" letters ĉ, ĝ, ĥ, ĵ, ŝ and ŭ), and write:

$make
$su -c 'cp pam_siegho.so /lib/security' # location of the pam libraries

Then add a line for the services for which you want to use
attack-protection to the pam comfiguration file (/etc/pam.d/<service>
or /etc/pam.conf) "auth require pam_siegho.so" or "auth requisite
pam_siegho.so". If you use "require", pam will always ask for a
password (or another way of authentication), whether or not the
visitor already tried too many times; with "requisite", the visitor
will immediately be barred out (en the latter case, be sure to place
the line before the other authentication methods, like a password).
An example:

auth    requisite pam_siegho.so
auth    required  pam_unix.so
account required  pam_unix.so
session required  pam_unix.so

You should also make a ruleset for pam_siegho in /etc/siegho (you can
change the default location in pam_siegho.c or by adding an argument
"regularo=<path>" to the module line in the pam configuration). The
"regularo" can be a normal file or a folder. If it is a folder, the
file with the name of the pam service in the folder will be used, or
"aliaj" (others) if it doesn't exist. The settings you can make are
the following (if you don't specify a setting, the values given here
will be used; lines starting with "#" are comments):

-----
notlibro=/var/log/sieĝo
# Where to remember the "timo" (fear)

rekonajho=armeo
# How to recognise the visitor (not all services define everything;
# you cannot use undefined "rekonajhoj"). This is a list of
# recognisation things, separated by comma's (","). The possible
# "rekonajhoj" are:
#    * anonco (USER: who the visitor pretends to be
#    * militisto (RUSER: name of the visitor on the remote computer)
#    * armeo (RHOST: DNS name of the coputer of the visitor)
# You should be aware that a visitor can pretend whatever he wants for
# anonco, en maybe also for militisto. The armeo (DNS name) can change
# from time to time with dynamic IP addresses.
# So, if you want to count the tries of one man from one coputer, to
# come in as one user, write:
#rekonajho=anonco,militisto,armeo

timemo=1m
# How long to remember tries (s=seconds, m=minutes, h=hours, t=days).

limo=10
# Number of tries.

dauro=1t
# Time to ban out a visitor if the "timo" exceeds the "limo".

ago=
# Action when the visitor is barred out.
# To send an e-mail, use:
#ago=echo "$MILITISTO@$ARMEO --> $ANONCO tried too many times to get in" | mail -s "barred out $ARMEO" root
-----


Well, how does this work?
-------------------------

For every visitor, the time of the last try and the "timo" (fear) is
remembered (in the "notlibro"). Every time a visitor tries to get in
(when pam is called), the timo increases by one unit , and decreases
by one unit for each time "timemo" passed since the last try. If after
that the timo exceeds the limo, the visitor will not be able to come
in and the "ago" will be executed. If the visitor, while he is barred
out, tries to come in before the dauro passed, the time of the last
try is updated (so he will have to wait the whole dauro again), but
the ago isn't done again. After a successful login, the guard becomes
quiet about that visitor again (the timo becomes 0).

We'll look at an example: rekonajho is "armeo" ago is to send an email
to "root", timemo is one minute, limo is 10 en dauro is one day.

"good.org" tries to come in
   timo for "good.org" becomes 1
   visitor is accepted (he can try)
"good.org" gives a good password
   timo for "good.org" is reset to 0
"good.org" tries to come in
   timo for "good.org" becomes 1
"good.org" misses about the password
"good.org" tries again to come in
   timo for "good.org" becomes 2
   "good.org" can try
"good.org" gives a good password
   timo for "good.org" becomes 0
"bad.org" tries to come in
   timo for "bad.org" becomes 1
   "bad.org" can try to come in
"bad.org" gives a bad password
"bad.org" tries again
   timo for "bad.org" becomes 2
   "bad.org" can try
"bad.org" tries again
   timo for "bad.org" becomes 3
   "bad.org" can try
---after two minutes---
"bad.org" tries again
   timo for "bad.org" becomes 2
      (timemo passed two times (-2) and a new try (+1))
   "bad.org" can try
"bad.org" tries again
   timo for "bad.org" becomes 3
   "bad.org" can try
...
"bad.org" tries again
   timo for "bad.org" becomes 10
   "bad.org" can try
"bad.org" tries again
   timo for "bad.org" becomes 11
   visitor is barred out
   root receives an e-mail
---after half a day---
"bad.org" tries again
   timo for "bad.org" becomes 12
   visitor remains barred out
---after half a day---
"bad.org" tries again
   timo for "bad.org" becomes 13
   visitor remains barred out
      (because the last try was just half a day ago)
---after two days---
"bad.org" tries again
   timo for "bad.org" is already 0, becomes 1
   "bad.org" can try again


Ideas for use.
--------------

A way to use this is to protect you ssh (or another) server against
attacks from people who try to guess a password. Set rekonajho to
armeo (the remote host). With ipset (see http://ipset.netfilter.org/),
you can then have an action to add the remote host to an ip set with
timeout one day (or so), and in your iptable rules, add a rule which
blocks packets from that addresses.


I found a bug / want to contact the author
------------------------------------------

If you found a bug, have ideas for improvements, really want to tell
some story related to this little program, ... contact the author (por
program changes, patches are welcome, of course): Maarten Deprez
<maartendeprez at users dot sourceforge dot net>.
