pam_shield by Walter de Jong <walter@heiho.net> (C) 2007-2011
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 on a Debian or Ubuntu-like system:
libpam0g-dev
libgdbm-dev
Pre-reqs on a RedHat or Fedora-like system:
pam-devel
gdbm-devel
There is no 'configure' script.
Edit the Makefile to customize the installation directories.
(install-sh is provided just in case you have no 'install' command).
pam_shield consists of:
- one PAM module: /lib/security/pam_shield.so
or /lib64/security/pam_shield.so on 64-bit systems
- one binary: /usr/sbin/shield-purge
- one shell script: /usr/sbin/shield-trigger
- one cron script: /etc/cron.daily/pam-shield
- one config file: /etc/security/shield.conf
- a gdbm database: /var/lib/pam_shield/db
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. Also, create an 'allow' line for your local networks. (If you do not
list your local networks, a local user may be able to lock you out (DoS
attack)).
pam_shield uses a shell script named shield-trigger to block and unblock
sites. It will use null-routing to do so.
A script named shield-trigger-iptables is provided too, which uses iptables
to block sites, but beware that it needs system-specific customization to
work correctly.
Configuring PAM
---------------
The PAM config files usually reside under /etc/pam.d/
Note that exact content of the PAM config files tends to differ between
distributions.
pam_shield.so must be included in the PAM configuration file for any
services where it might be useful. In general, /etc/pam.d/sshd.
Different configurations are possible, depending on your taste.
There is a certain "play" between the config of your PAM stack and what
you put into the shield.conf file, so pay attention.
Here are some examples of configurations:
1. Block many failing login attempts
auth sufficient pam_unix.so
auth required pam_shield.so
Explanation: good logins will succeed by pam_unix, and pam_shield will
not even be invoked. Bad logins fall through and are caught by pam_shield,
which may activate null-routing for the failing IPaddress.
The shield.conf option 'block unknown-users' will do what it says, and
'block all-users' will activate the IP block even for known users _if_
there are many failed logins for that user.
The options 'allow_missing_dns' and 'allow_missing_reverse' do not do
anything useful in this configuration.
2. Block suspicious looking folks
auth requisite pam_shield.so
auth include system-auth
Explanation: Every login attempt will be screened by pam_shield. If all
looks well, the system may continue to authenticate the user as usual.
If all is not well, pam_shield will abort the login immediately.
The shield.conf options 'allow_missing_dns' and 'allow_missing_reverse'
play an important role here. Missing DNS entries are suspicious because
hackers use this to try stay hidden. However, pam_shield will still allow
logins for _known_ users if you set 'block unknown-users'.
If you enable 'block all-users', it is easy to lock yourself out from a
machine that has no DNS entry. You will also block legitimate users that
do too many logins in a short period of time. For example, when a user
does this:
for file in *; do scp $file remotemachine: ; done
NB. If there are other "required" modules in the stack that must run no
matter what, you may change "requisite" to "required".
3. Block login attempts no matter what
auth optional pam_shield.so
auth include common-auth
Explanation: Let pam_shield do its job, and then do the usual stuff to
authenticate the user.
This is not an optimal configuration. "optional" means that pam_shield can
not abort the login attempt (unless it is already null-routing the IP).
The shield.conf parameters 'allow_missing_dns' and 'allow_missing_reverse'
have no useful meaning here, they don't do anything in this configuration.
So, if you want to be nice to the users of your system, go for config #1.
If you are more paranoid, go for config #2.
Whatever you do, make sure pam_shield is not the only auth module that
is listed for the service. 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
------------------
When testing pam_shield, be wary that you are going to lock yourself out.
The safest way to test it, is to have console access with a root prompt open
just in case things go wrong and you can not access your machine anymore.
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. To see what hosts are blocked,
use any of the following commands (whichever you prefer):
netstat -r
route
ip route show
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
