Provided by: libpam-abl_0.6.0-5_amd64 
NAME
pam_abl - PAM Auto Blacklist Module
SYNOPSIS
Provides auto blacklisting of hosts and users responsible for repeated failed
authentication attempts. Generally configured so that blacklisted users still see normal
login prompts but are guaranteed to fail to authenticate.
This functionality is only available to services which call PAM as root. If pam_abl is
called for uid != 0 it will silently succeed.
DESCRIPTION
Brute force password discovery attacks involve repeated attempts to authenticate against a
service using a dictionary of common passwords. While it is desirable to enforce strong
passwords for users this is not always possible and in cases where a weak password has
been used brute force attacks can be effective.
The pam_abl module monitors failed authentication attempts and automatically blacklists
those hosts (and accounts) that are responsible for large numbers of failed attempts. Once
a host is blacklisted it is guaranteed to fail authentication even if the correct
credentials are provided.
Blacklisting is triggered when the number of failed authentication attempts in a
particular period of time exceeds a predefined limit. Hosts which stop attempting to
authenticate will, after a period of time, be un-blacklisted.
Commands can be specified which will be run when a host or user switches state from being
blocked to clear or clear to blocked. See below or the pam_abl.conf(5) manpage for the
details.
If pam_abl is called for uid != 0 it will silently succeed. If this was not the case it
would be possible for a malicious local user to poison the pam_abl data by, for example,
discovering the names of the hosts from which root typically logs in and then constructing
PAM authentication code to lock out root login attempts from those hosts.
OPTIONS
Name Arguments Description
debug None Enable debug output to
syslog.
expose_account None Ignored
no_warn None Disable warnings which
are otherwise output to
syslog. try_first_pass
None Ignored
use_first_pass None Ignored
use_mapped_pass None Ignored
config Path to the The configuration file
configuration file. contains additional
arguments. In order for
the pam_abl command line
tool to work correctly
most of the
configuration should be
placed in the config
file rather than being
provided by arguments.
The format of the config
file is described below.
limits Minimum and maximum It’s value should have
number of attempts to the following syntax
keep. "<minimum>-<maximum>".
If you do not block
machines that do too
many attempts, the db
can easily become
bloated. To prevent this
we introduced this
setting. As soon as
there are a <maximum>
number of attempts for a
user/host, the number of
stored attempts is
reduced to <minimum>. A
<maximum> of 0 means no
limits. Make sure that
<minimum> is larger then
any rule specified. We
recommend a value of
"1000-1200".
db_home Directory for db locking Path to a directory
and logging files. where Berkeley DB can
place it’s locking and
logging files. Make sure
this dir is writable.
host_db Path to host database Path to the Berkeley DB
file. which is used to log the
host responsible for
failed authentication
attempts.
host_purge Purge time for the host Defines how long failed
database. hosts are retained in
the host database.
Defaults to 1 day.
host_rule Rule for host The rule (see below for
blacklisting. format) which defines
the conditions under
which a failed hosts
will be blackisted.
host_whitelist Host that do not need to ;-seperated list of host
be tracked. that do not need to be
tracked. You can specify
single IP addresses here
or use subnets. For
example 1.1.1.1 or
1.1.1.1/24
host_blk_cmd Host block command Deprecated for security
reasons. Please use
host_block_cmd
host_clr_cmd Host clear command Deprecated for security
reasons. Please use
host_clear_cmd
host_block_cmd Host block command Command that should be
run when a host is
checked, and is
currently blocked.
Within the command, the
strings %u, %h and %s
are substituted with
username, host and
service. Not all need to
be used. Please see the
manpage of pam_abl.conf
for the correct syntax.
host_clear_cmd Host clear command Command that should be
run when a host is
checked, and is
currently clear. Within
the command, the strings
%u, %h and %s are
substituted with
username, host and
service. Not all need to
be used. Please see the
manpage of pam_abl.conf
for the correct syntax.
user_db Path to user database Path to the Berkeley DB
file. which is used to log the
user responsible for
failed authentication
attempts.
user_purge Purge time for the user Defines how long failed
database. users are retained in
the user database.
Defaults to 1 day.
user_rule Rule for user The rule (see below for
blacklisting. format) which defines
the conditions under
which a failed users
will be blackisted.
user_whitelist Users that do not need ;-seperated list of
to be tracked. users whose attempts do
not need to be recorded.
This does not prevent
the machine they are
using from being
blocked.
user_blk_cmd User block command Deprecated for security
reasons. Please use
user_block_cmd
user_clr_cmd User clear command Deprecated for security
reasons. Please use
clear_block_cmd
user_blk_cmd User block command Command that should be
run when a user is
checked, and is
currently blocked.
Within the command, the
strings %u, %h and %s
are substituted with
username, host and
service. Not all need to
be used.
user_clr_cmd User block command Command that should be
run when a user is
checked, and is
currently clear. Within
the command, the strings
%u, %h and %s are
substituted with
username, host and
service. Not all need to
be used.
USAGE
Typically pam_abl.so is added to the auth stack as a required module just before whatever
modules actually perform authentication. Here’s a fragment of the PAM config for a
production server that is running pam_abl:
auth required /lib/security/pam_env.so
auth required /lib/security/pam_abl.so
config=/etc/security/pam_abl.conf
auth sufficient /lib/security/pam_unix.so likeauth nullok
auth required /lib/security/pam_deny.so
Although all of accepted arguments can be supplied here they will usually be placed in a
separate config file and linked to using the config argument as in the above example. The
pam_abl command line tool reads the external config file (/etc/security/pam_abl.conf in
this case) to find the databases so in order for it work correctly an external config
should be used.
EXAMPLES
auth required /lib/security/pam_env.so
auth required /lib/security/pam_abl.so config=/etc/security/pam_abl.conf
auth sufficient /lib/security/pam_unix.so likeauth nullok
auth required /lib/security/pam_deny.so
SEE ALSO
pam_abl.conf(5), pam_abl(1)
AUTHORS
Lode Mertens <pam-abl@danta.be>
Andy Armstrong <andy@hexten.net>
Chris Tasma <pam-abl@deksai.com>
AUTHOR
Chris Tasma
Author.