<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>The Auto Blacklist Module: pam_abl</title> <link href="style.css" rel="stylesheet" type="text/css" /> </head> <body> <h1>The Auto Blacklist Module: pam_abl</h1> <h2>Synopsis</h2> <dl> <dt>Module name:</dt> <dd>pam_abl</dd> <dt>Author[s]:</dt> <dd>Andy Armstrong <a href="mailto:andy@hexten.net"><andy@hexten.net></a></dd> <dt>Maintainer:</dt> <dd>Andy Armstrong <a href="mailto:andy@hexten.net"><andy@hexten.net></a></dd> <dt>Management groups provided:</dt> <dd>auth</dd> <dt>Cryptographically sensitive:</dt> <dd>No.</dd> <dt>Security rating:</dt> <dd></dd> <dt>Clean code base:</dt> <dd>Clean.</dd> <dt>System dependencies:</dt> <dd>Requires <a href="http://www.sleepycat.com/products/db.shtml">Berkeley DB</a> (tested with 4.3.21 and 4.2.50).<br /> Requires a configuration file (by convention /etc/security/pam_abl.conf)</dd> <dt>Network aware:</dt> <dd>No.</dd> </dl> <h2>Overview of module</h2> <p>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.</p> <p>This functionality is only available to services which call PAM as root. If pam_abl is called for uid != 0 it will silently succeed.</p> <h2>Auth component</h2> <dl> <dt>Recognised arguments:</dt> <dd> <table> <tr> <th>Name</th> <th>Arguments</th> <th>Description</th> </tr> <tr> <td>debug</td> <td>None</td> <td>Enable debug output to syslog.</td> </tr> <tr> <td>expose_account</td> <td>None</td> <td>Ignored</td> </tr> <tr> <td>no_warn</td> <td>None</td> <td>Disable warnings which are otherwise output to syslog.</td> </tr> <tr> <td>try_first_pass</td> <td>None</td> <td>Ignored</td> </tr> <tr> <td>use_first_pass</td> <td>None</td> <td>Ignored</td> </tr> <tr> <td>use_mapped_pass</td> <td>None</td> <td>Ignored</td> </tr> <tr> <td>config</td> <td>Path to the configuration file.</td> <td>The configuration file contains additional arguments. In order for the <a href="pam_abl.html">pam_abl</a> 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.</td> </tr> <tr> <td>host_db</td> <td>Path to host database file.</td> <td>Path to the Berkeley DB which is used to log the host responsible for failed authentication attempts.</td> </tr> <tr> <td>host_purge</td> <td>Purge time for the host database.</td> <td>Defines how long failed hosts are retained in the host database. Defaults to 1 day.</td> </tr> <tr> <td>host_rule</td> <td>Rule for host blacklisting.</td> <td>The rule (see below for format) which defines the conditions under which a failed hosts will be blackisted.</td> </tr> <tr> <td>user_db</td> <td>Path to user database file.</td> <td>Path to the Berkeley DB which is used to log the user responsible for failed authentication attempts.</td> </tr> <tr> <td>user_purge</td> <td>Purge time for the user database.</td> <td>Defines how long failed users are retained in the user database. Defaults to 1 day.</td> </tr> <tr> <td>user_rule</td> <td>Rule for user blacklisting.</td> <td>The rule (see below for format) which defines the conditions under which a failed users will be blackisted.</td> </tr> </table> </dd> <dt>Description:</dt> <dd> <p>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.</p> <p>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.</p> <p>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.</p> <p>This functionality is only available to services which call PAM as root. 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.</p> </dd> <dt>Usage:</dt> <dd> <p>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:</p> <table class="config"> <tr><td>auth</td><td>required</td><td>/lib/security/pam_env.so</td></tr> <tr><td>auth</td><td>required</td><td>/lib/security/pam_abl.so config=/etc/security/pam_abl.conf</td></tr> <tr><td>auth</td><td>sufficient</td><td>/lib/security/pam_unix.so likeauth nullok</td></tr> <tr><td>auth</td><td>required</td><td>/lib/security/pam_deny.so</td></tr> </table> <p>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 <a href="pam_abl.html">pam_abl command line tool</a> 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.</p> </dd> <dt>Config file syntax:</dt> <dd> <p>The config file can contain any arguments that would be supplied via PAM config. In the config file arguments are placed on separate lines. Comments may be included after a '#' and line continuation is possible by placing a back slash at the end of the line to be continued. Here is a sample /etc/security/pam_abl.conf:</p> <table class="config"> <tr><td># /etc/security/pam_abl.conf</td></tr> <tr><td>debug</td></tr> <tr><td>host_db=/var/lib/abl/hosts.db</td></tr> <tr><td>host_purge=2d</td></tr> <tr><td>host_rule=*:10/1h,30/1d</td></tr> <tr><td>user_db=/var/lib/abl/users.db</td></tr> <tr><td>user_purge=2d</td></tr> <tr><td>user_rule=!root:10/1h,30/1d</td></tr> </table> <p>All of the standard PAM arguments (<code>debug</code>, <code>expose_account</code>, <code>no_warn</code>, <code>try_first_pass</code>, <code>use_first_pass</code>, <code>use_mapped_pass</code>) are accepted; with the exception of <code>debug</code> and <code>no_warn</code> these are ignored.</p> <p>The arguments that are specific to pam_abl are as follows:</p> <table> <tr> <td><code>host_db, user_db</code></td> <td>Specify the name of the databases that will be used to log failed authentication attempts. The host database is used to log the hostname responsible for a failed auth and the user database is used to log the requested username. If host_db or user_db is omitted the corresponding auto blacklisting will be disabled.</td> </tr> <tr> <td><code>host_purge, user_purge</code></td> <td>Specify the length of time for which failed attempts should be kept in the databases. For rules to work correctly this must be at least as long as the longest period specified in a corresponding rule. You may wish to retain information about failed attempts for longer than this so that the <a href="pam_abl.html">pam_abl command line tool</a> can report information over a longer period of time. The format for this item is a number with an optional multiplier suffix, 's', 'm', 'h' or 'd' which correspond with seconds, minutes, hours and days. To specify seven days for example one would use '7d'. Note that in normal operation pam_abl will only purge the logged data for a particular host or user if it happens to be updating it, i.e. if that host or user makes another failed attempt. To purge all old entries the <a href="pam_abl.html">pam_abl command line tool</a> should be used.</td> </tr> <tr> <td><code>host_rule, user_rule</code></td> <td>These are the rules which determine the circumstances under which accounts are auto-blacklisted. The host_rule is used to block access to hosts that are responsible for excessive authentication failures and the user_rule is used to disable accounts for which there have been excessive authentication failures. The rule syntax is described in full below.</td> </tr> </table> </dd> <dt>Rule syntax:</dt> <dd> <p>Each rule consists of a number of space separated 'user clauses'. A user clause specifies the user (and service) names to match and a set of triggers. A simple example would be</p> <p><code>*:10/1h</code></p> <p>which means 'block any user (*) if they are responsible for ten or more failed authentication attempts in the last hour'. In place of the '*' which matches any user a list of usernames can be supplied like this</p> <p><code>root|dba|admin:10/1h</code></p> <p>which means 'block the users root, dba and admin if they are responsible for ten or more failed authentication attempts in the last hour'. You can also specify a service name to match against like this</p> <p><code>root/sshd|dba/*:3/1d</code></p> <p>which means 'block the users root for service 'sshd' and dba for any service if they are responsible for three or more failed authentication attempts in the last day'. Finally you can specify multiple triggers like this</p> <p><code>root:10/1h,20/1d</code></p> <p>which means 'block the user root if they are responsible for ten or more failed attempts in the last hour or twenty or more failed attempts in the last day.</p> <p>Multiple rules can be provided separated by spaces like this</p> <p><code>*:10/1h root:5/1h,10/1d</code></p> <p>in which case <em>all</em> rules that match a particular user and service will be checked. The user or host will be blocked if any of the rule triggers matches. The sense of the user matching can be inverted by placing a '!' in front of the rule so that</p> <p><code>!root:20/1d</code></p> <p>is a rule which would match for all users <em>apart from</em> root. It is important to treat root as a special case in the user_rule otherwise excessive attempts to authenticate as root will result in the root account being locked out even for valid holders of root credentials.</p> <p>Here is the full syntax for rules:</p> <table class="syntax"> <tr><td>word</td><td>::=</td><td>/[^\s\|\/\*]+/</td></tr> <tr><td>name</td><td>::=</td><td>word | '*'</td></tr> <tr><td>username</td><td>::=</td><td>name</td></tr> <tr><td>servicename</td><td>::=</td><td>name</td></tr> <tr><td>userservice</td><td>::=</td><td>username</td></tr> <tr><td></td><td>|</td><td>username '/' servicename</td></tr> <tr><td>namelist</td><td>::=</td><td>userservice</td></tr> <tr><td></td><td>|</td><td>userservice '|' namelist</td></tr> <tr><td>userspec</td><td>::=</td><td>namelist</td></tr> <tr><td></td><td>|</td><td>'!' namelist</td></tr> <tr><td>multiplier</td><td>::=</td><td>'s' | 'm' | 'h' | 'd'</td></tr> <tr><td>number</td><td>::=</td><td>/\d+/</td></tr> <tr><td>period</td><td>::=</td><td>number</td></tr> <tr><td></td><td>|</td><td>number multiplier</td></tr> <tr><td>trigger</td><td>::=</td><td>number '/' period</td></tr> <tr><td>triglist</td><td>::=</td><td>trigger</td></tr> <tr><td></td><td>|</td><td>trigger ',' triglist</td></tr> <tr><td>userclause</td><td>::=</td><td>userspec ':' triglist</td></tr> <tr><td>rule</td><td>::=</td><td>userclause</td></tr> <tr><td></td><td>|</td><td>userclause /\s+/ rule</td></tr> </table> </dd> <dt>Examples/suggested usage:</dt> <dd> <p>Sample PAM config fragment:</p> <table class="config"> <tr><td>auth</td><td>required</td><td>/lib/security/pam_env.so</td></tr> <tr><td>auth</td><td>required</td><td>/lib/security/pam_abl.so config=/etc/security/pam_abl.conf</td></tr> <tr><td>auth</td><td>sufficient</td><td>/lib/security/pam_unix.so likeauth nullok</td></tr> <tr><td>auth</td><td>required</td><td>/lib/security/pam_deny.so</td></tr> </table> <p>Sample /etc/security/pam_abl.conf:</p> <table class="config"> <tr><td># /etc/security/pam_abl.conf</td></tr> <tr><td>debug</td></tr> <tr><td>host_db=/var/lib/abl/hosts.db</td></tr> <tr><td>host_purge=2d</td></tr> <tr><td>host_rule=*:10/1h,30/1d</td></tr> <tr><td>user_db=/var/lib/abl/users.db</td></tr> <tr><td>user_purge=2d</td></tr> <tr><td>user_rule=!root:10/1h,30/1d</td></tr> </table> </dd> <dt>See also:</dt> <dd>The <a href="pam_abl.html">pam_abl command line tool.</a></dd> </dl> <h2>Licence</h2> <p>See <a href="copying.html">this page</a> for licensing details.</p> </body> </html>
