Lockout plugin for SquirrelMail =============================== Ver 1.6, 2008/04/01 Copyright (c) 2008 Paul Lesniewski Description =========== This plugin allows you to create a list of users and/or domains that should be disallowed (or allowed) login access to SquirrelMail. It also allows you to block brute-force password guessing attacks, although please note that this will ONLY help fight such attacks in the SquirrelMail interface, and should really be implemented in your mail system's authentication backend. Tips on implementing this kind of security measure in the mail server's authentication backend: For Unix-like systems, there is a high probability that your backend authentication method is PAM. For PAM-based authentication, look at the pam_tally or pam_lockout add-on modules, both of which will prevent this kind of attack in a much more robust manner. For OpenLDAP-based authentication, you would set ppolicy_use_lockout and related configuration parameters (all the ppolicy parameters are password related) in the openldap configuration. License ======= This plugin is released under the GNU General Public License (see COPYING for details). Donations ========= If you or your company make regular use of this software, please consider supporting Open Source development by donating to the authors or inquire about hiring them to consult on other projects. Donation links for the author(s) are as follows: Paul Lesniewski: https://sourceforge.net/donate/index.php?user_id=508228 Requirements ============ * SquirrelMail version 1.4.1 or above * Compatibility plugin version 2.0.11 or above Security Considerations ======================= When configuring IP-based blacklisting with $max_login_attempts_per_IP, username-based blacklisting with $max_login_attempts, or adding a CAPTCHA requirement with $activate_CAPTCHA_after_failed_attempts, you should carefully consider your users' habits and the kinds of potential attacks you are trying to mitigate. The most risk-free of these features is to configure the CAPTCHA plugin to activate after a certain number of failed login attempts. This makes SquirrelMail somewhat harder to attack in an automated fashion while not creating any need for the administrator to have to manually unlock any account or IP address. If you use a very strong CAPTCHA backend (beware, however, that most CAPTCHA implementations are not very strong) and are only fighting off an *automated* attack, this step alone may suffice. Adding IP-based blacklisting is effective at blocking an attacker who is trying multiple user account names as long as it is triggered at a reasonably high level of login failures (the threshold should be especially high if you have a lot of users who log in from a small number of client addresses). Username-based blacklisting could be useful when an attacker is targetting a known user or small group thereof, although because locking the user's account is also inconvenient to the legitimate user, IP-based blacklisting will usually still be a better solution. However, if this feature is set with a fairly high threshold (higher than all others), it can be used to halt someone who consistently attacks the same account from a range of IP addresses. After triggering a lockdown on such an account, it might be prudent to change the username or take other (real world?) measures. See the configuration file for more information about how to configure each of the settings discussed above. If your SquirrelMail installation resides behind a proxy server that sends X_FORWARDED_* headers, you should turn on $obey_x_forwarded_headers, but in all other environments, please leave this setting off, otherwise an attacker might be able to thwart a domain lockout rule by tampering with the request headers. In the same vien, if a client is able to forge the regular HTTP_HOST request header, domain-based lockout rules defined in the lockout table may be compromised. The only solution for this kind of problem beside using user-based lockout rules or enforcing login restrictions in the IMAP server (which is ALWAYS more robust than implementing them in the mail client) is to make sure that your usernames are in the format of a full email address (that is, that they always carry a domain name in them, and are not, for instance, in the same format as local account usernames). Configuration ============= Please copy the sample configuration (config.sample.php) file in this plugin's data sub-directory to your own config.php and then edit it as necessary. If you choose to enable the $use_lockout_rules setting, you must also copy the sample lockout table (lockout_table.sample.php) in the data sub-directory into your own lockout_table.php and edit it as follows: Users and domains can be indicated using wildcards and can each have their own page that will be displayed when they are locked out. See the sample lockout_table.sample.php file in the data directory for help building this table. You may want to edit the file(s) you have indicated as the target lockout page to be displayed in order to customize the message that will be seen when someone is locked out, or send them to a special web page elsewhere or redirect them to the standard SquirrelMail "bad username or password" error page if you desire this plugin to be more stealthy. Note that this will typically catch locked out users no matter which of your domains they attempt to log in through. Note also that if you enable reverse lockout functionality, the users and domains listed in the lockout table will all be ALLOWED to log in, all OTHERS will be locked out. Troubleshooting =============== * If you have some SMTP authentication method configured in the main SquirrelMail configuration (or perhaps POP before SMTP is turned on) and administrative alert emails are not getting sent when a user is locked out, this is because the SMTP authentication credentials are not yet available before a user has logged in, so you need to provide administrative credentials for sending such emails. See $lockout_smtp_auth_mech (and related settings) in the configuration file. Help Requests ============= Before looking for help elsewhere, please try to help yourself: * Read the Troubleshooting section herein. * Look to see if others have already asked about the same issue. There are tips and links for the best places to do this in the SquirrelMail mailing list posting guidelines: http://squirrelmail.org/wiki/MailingListPostingGuidelines You should also try Google or some other search engine. * If you cannot find any information about your issue, please first mail your help request to the squirrelmail-plugins mailing list. Information about it can be found here: http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins You MUST read the mailing list posting guidelines (see above) and include as much information about your issue (and your system) as possible. Including configtest output, any debug output, the plugin configuration settings you've made and anything else you can think of to make it easier to diagnose your problem will get you the most useful responses. Inquiries that do not comply with the posting guidelines are liable to be ignored. * If you don't get any replies on the mailing list, you are welcome to send a help request to the authors' personal address(es), but please be patient with the mailing list. Change Log ========== v1.6 2008/04/01 Paul Lesniewski * Allow overrides of SquirrelMail SMTP/Sendmail settings when sending administrative alert emails v1.5 2008/03/11 Paul Lesniewski * Updated to use sq_send_mail for notification messages * Added ability to log lockout events in Squirrel Logger plugin * Remove use of login_top hook v1.4.1 2007/08/24 Paul Lesniewski * Very small change due to change in SM 1.5.2; does not affect plugin functionality - no upgrade needed for anyone who does not want to bother v1.4 2007/07/12 Paul Lesniewski * Added ability to disable accounts that have too many successive login failures, including optional administrative alert email * Added IP-based blacklisting * Added ability to enable the CAPTCHA plugin for IP addresses that have too many successive login failures * Move lockout check to hook that occurs BEFORE user is actually logged in * Updated for compatibility with SM 1.5.2+ * Updated for use with new Compatibility plugin * Miscellaneous cleanup * Security considerations/audit thanks to Ben at reCAPTCHA.net 1.3 - Paul Lesniewski * Added abilty to reverse lockout functionality (lock out everyone *except* those listed in the lockout table) 1.2 - Paul Lesniewski * Fixed typo in INSTALL 1.1 - Paul Lesniewski * Added ability to redirect to another web page or to the standard SquirrelMail "bad username or password" page (with simulated bad login delay) 1.0 - Paul Lesniewski * Initial release Future Work =========== * Ideas?