pam_abl - Man Page

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 configuration file.	The 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 number of attempts to keep.	It’s value should have the following syntax "<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 and logging files.	Path to a directory where Berkeley DB can place it’s locking and logging files. Make sure this dir is writable.
host_db	Path to host database file.	Path to the Berkeley DB which is used to log the host responsible for failed authentication attempts.
host_purge	Purge time for the host database.	Defines how long failed hosts are retained in the host database. Defaults to 1 day.
host_rule	Rule for host blacklisting.	The rule (see below for format) which defines the conditions under which a failed hosts will be blackisted.
host_whitelist	Host that do not need to be tracked.	;-seperated list of host 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 file.	Path to the Berkeley DB which is used to log the user responsible for failed authentication attempts.
user_purge	Purge time for the user database.	Defines how long failed users are retained in the user database. Defaults to 1 day.
user_rule	Rule for user blacklisting.	The rule (see below for format) which defines the conditions under which a failed users will be blackisted.
user_whitelist	Users that do not need to be tracked.	;-seperated list of 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 peform 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