pam_shield by Walter de Jong <walter@heiho.net> (C) 2007

pam_shield COMES WITH NO WARRANTY. synctool IS FREE SOFTWARE.
pam_shield is distributed under terms described in the GNU General Public
License.

See the README file for some information about pam_shield.


Read the README and this file carefully. Failure to setup pam_shield
correctly, will render it useless.


Building pam_shield
-------------------

Pre-reqs:
	libpam0g-dev
	libgdbm-dev


There is no 'configure' script.
Edit the Makefile to customize the installation directories.

pam_shield consists of:
- one PAM module meant for installation under /lib/security
- one binary meant for /sbin
- one shell script meant for /sbin
- one shell script meant for /etc/cron.daily
- one config file meant for /etc
It will use a gdbm database under /var/lib/pam_shield

Type 'make' to build the software.
Do a 'make install' as root to install the software.
You may do 'make uninstall' to remove the software.


Configuring pam_shield
----------------------
Edit the config file /etc/security/shield.conf and make sure all paths are
correct.

pam_shield uses a shell script named shield-trigger.sh to block and unblock
sites. You have to customize this script to fit your situation.
By default, the script will run iptables to drop SSH packets on network
interface eth0 for the pam_shield iptables chain.


Setting up iptables
-------------------
The shield-trigger.sh script runs the iptables command on the chain
named 'pam_shield'. Therefore, this chain has to exist, otherwise it won't
work correctly. Edit /etc/sysconfig/iptables and add the lines:

:pam_shield - [0:0]
-A pam_shield -j DROP


and do /etc/init.d/iptables reload
or use the command line on systems that don't have sysconfig:

iptables -N pam_shield
iptables -A pam_shield -j DROP


iptables -L

At the bottom of the iptables output, you should see something like:

Chain pam_shield (0 references)
target     prot opt source               destination
DROP       0    --  anywhere             anywhere


The idea is that the iptables firewall will redirect any attackers to
the pam_shield chain, which will drop their packets.

Make sure the firewall configuration persists after reboot.


Configuring PAM
---------------
The PAM config files usually reside under /etc/pam.d/
The exact content of the PAM config files tends to differ between
distributions.
By default, shield-trigger.sh only works with port 22 (SSH), so it
makes sense to edit /etc/pam.d/sshd
If you want to use pam_shield for other services as well, edit their
respective pam.d files or use pam.d/common-auth.
Add the line

    auth optional   pam_shield.so

but just make sure it is not the only auth module that is listed
in the file. pam_shield does not do any authentication by itself and
trying to run it as standalone auth module will leave your system
wide open.


Testing pam_shield
------------------
Edit /etc/security/shield.conf and set max_conns to a small value
like 3 or so. Set the interval and the retention period both to 60 seconds.
Set debug on.
Now simulate an attack on your system by doing 4 quick logins to a
non-existing user from a remote host. If you check the syslog (often
/var/log/secure or /var/log/auth.log) you will see that pam_shield
is triggering and later, expiring. Check iptables -L to see what
rules are listed.
If you check the debug log (often /var/log/debug) you will see more
debug info from pam_shield.

pam_shield should now be completely installed and working.
Edit /etc/security/shield.conf and enter sensible values for max_conns,
interval and retention.
It is wise to periodically check whether pam_shield is still operating
correctly.


EOB
