Index: README.txt =================================================================== RCS file: /cvs/drupal-contrib/contributions/modules/login_security/README.txt,v retrieving revision 1.4 diff -u -r1.4 README.txt --- README.txt 21 Oct 2007 20:56:23 -0000 1.4 +++ README.txt 23 Jun 2009 11:09:51 -0000 @@ -7,30 +7,72 @@ of a drupal site. By default, drupal has only basic access control deniying IP access to the full content of the site. -With Login security a site administrator may add two types of access control to -the login forms (default and block). These are the features included: +With Login security a site administrator may add any of the following access control +features to the login forms (default login form in /user and the block login form). - Soft Protections: +These are the features included: + +Soft Protections +---------------- + + Soft protections don't disrupt site navigation, but alter the way a login operation + is performed. + + Currently, the login form submission can be soft-protected with these two options - Request Time delay: On any failed login, a time delay in included to the submit - request, hardenning the bruteforce attack to the login form. - - Block login forms or requests, when the protection flag is enabled the form is - never submited, and any request even with a valid form token ID will be dropped, - but the host still can access the site. + request, hardenning the bruteforce attack to the login form. Including a time + delay in each submission, will reduce the number of login attempts a user or script + can do. On each attempt, the delay time is increased, using the formula: + + - Invalidate login form submission: when the soft-block protection flag is enabled + the login form is never submited, and any new login request will fail, but the host + could still access the site. - Hard Protections: - - Block account: on a number of failed attempts, the account can be blocked. - - Block IP: on a number of failed attempts, a host may be added to the access - control list. - -Notes: - - soft block for hosts will expire in the ammount of hours configured. - - hard blocke hosts will not be removed from list. It should be done by manually. - - blocked accounts will not be removed from block list. It should be donde manually. -The session ID (php session neither drupal's session) is not taking in count for -the security operations, as automated bruteforce tool may request new sessions on -any attempt, ignoring the session fixation from the server. +Hard Protections +---------------- + + When there is evidence of hard account guessing operations, or when you need to block + users because of leak password guessing attempts, Hard protections may help + defeating the system. + + - Block account: It's really common to block an account after a number of failed + login attemps. Once this count is completed, the account can is blocked and user + and admin are advised about this. + + - Block IP address: on a number of failed attempts, a host may be added to the access + control list. This action will leave the host completely banned from the site. + + +Track time: Protection time window +---------------------------------- + + The time the protections operate is defined as the track time (or time window). It's + the time that login events are being considered for the protections. For example, we + can say that an account will be blocked on the third login attempt, but these three + attempts should happend in the protection time window. If the time protection window + is 1 hour, the three attemps should be in the last 60 minutes. If one of this attempts + was done earlier it's not considered. + + The time protection window is not the time each protection is active. Blocked accounts + will remain blocked untill an administrator unblocks them, and banned hosts need also + administration interaction to be unbanned. + + + +Duration of protections +----------------------- + + The duration of the enabled protections depends of its type. Soft protections are + temporary, and will expire in the time defined by the 'track time' or protection time + window. + + Hard protections are permanent, and an administrator should unblock or unban an + account or a host. + + A blocked account could be unblocked through the administration section: /admin/user/user + A banned host could be un banned through the Access rules section: /admin/user/rules @@ -43,20 +85,22 @@ and save the configuration. - -Configuration -------------- +Configuration options +--------------------- Go to Administer -> User Management -> User Settings and new box will appear close to the registering information with the following options. Any value set to 0 will disable that option. + Basic options + + - Track time: The time window where to check for security violiations. It's, the time in hours the login information is kept to compute the login attempts count. A common example could be 24 hours. After that time, the attempt is deleted from the list, so it will not count. - - Delay on login fail: Delay in seconds for the next login count. It's computed + - Login delay base time: Delay in seconds for the next login count. It's computed if the form: host & user, so any attempt to login again with the same user from the same IP address will be delayed that number of seconds. The time the user has to wait for the next login operation is (attempts * delay), and @@ -64,59 +108,47 @@ previous example of 24 hours, after 24h the login attemps will be cleared, and the delay decreased. - - Soft block host on login fail: After that number of attempts to login from - that IP address, no matter the username used, the host will not be allowed to - submit the login form again, but the content of the site is still accesible - for that IP address. The block will start to clear of counts after the - "Track Time" time window. - - - Hard block host on login fail: As the soft block, but this time the IP address - will be banned from the site, and included in the access list as a deny rule. - To remove the IP from the list you will have to go to: - Administer -> User Management -> Access Rules. + - Maximun number of login failures before blocking a user: It's that easy, after + this number of attempts to login as an user no matter the IP address attempting + to, the user will be blocked. To remove the blocking of the user, you will have + to go to: Administer -> User Management -> Users + + - Maximun number of login failures before soft blocking a host: After that number + of attempts to login from that IP address, no matter the username used, the host + will not be allowed to submit the login form again, but the content of the site + is still accesible for that IP address. Login attempts will start to clear of + counts after the "Track Time" time window. + + - Maximun number of login failures before blocking a host: As the soft block + protection does, but this time the IP address will be banned from the site, + included in the access list as a deny rule. To remove the IP from this ban, you + will have to go to: Administer -> User Management -> Access Rules. - - Block user on login fail: It's that easy, after N attempts of login as a user - no matter the IP address attempting to, the user will be blocked. To remove - the blocking of the user, you will have to go to: - Administer -> User Management -> Users - - - The flow will happend like described: - -1st - On any login, the pair host<->username is saved for security, and only -on a successfull login, the pair host-username is deleted from the security log. - -2nd - For the delay operation, the host and the username are taken in count. -This way, your login time will not be affected is someone is attempting to brute -the account. - -3rd - For the soft blocking operation, any failed attempt from that host is -being count, and when the number of attempts exceeds, the host is not allowed -to submit the form. + +Notifications +------------- -Note: (2nd and 3rd impose restrictions to the login form, and the time these -restrictions are in rule is the time the information is being tracked: "Track Time"). + The module also provides some notifications for the users to understand what is + happening. -4th For the user blocking operation, any failed attempt is count, so no matter -what the source IP address is, when too many attempts appear the account is -blocked. A successful login, even if the user is blocked will remove any tracking -entry fron the database. + - Display last login timestamp: each time a user does success in login, this message + will remember him when was the last time he logged in the site. -5th For the host blocking operation, only the host is taken in count. When too -many attempts appear, no matter the username being tested, the host IP address -is banned. + - Display last access timestamp: each time a user does success in login, this + message will remember him his last site access. -Note: (4th and 5th operations are not being cancelled automatically). -Note: The tracking entries in the database for any host <-> username pair are - being deleted on: 'login', 'update' and 'delete' operations. + - Notify the user about the number of remaining login attempts: It's also possible to + advice the user about the attempts available prior to block the account. + - Disable login failure error message: Selecting this option no error message will + be shown at all, so user will not be aware of unsuccessful login attempt, or blocked + account messages. + - Send email message to the admin: An email could also be sent to the administrator + uid 1, each time an account is blocked. -Notifications -------------- - -Thanks to christefano, the module now accepts configurable notifications for the -actions. These are the available placeholders for the displayed messages: + Some of the strings are configurable in the same administration section. The strings + can be personalized using the following placeholders: %date : The (formated) date and time of the operation %ip : The IP Address performing the operation @@ -135,46 +167,80 @@ %tracking_time : The tracking time, it's maximun soft blocking time. -Also, the placeholders are propagated to the watchdog system for any customization -needed in the auditing properties, but this has to be modified in the module source code. - -If you want your users to be informed when it's account has been blocked, you can use the -module "Extended user status notifications": http://www.drupal.org/project/user_status - - -Other modules interaction +Understanding protections ------------------------- -Thanks to christefano, now the login_security fits well in any drupal installation allowing -without breaking other module operations. The only interaction being performed for just -blocks a user, so to switch the user status an update hook is launched. Other modules can -now react to that hook. +Internally, protections could consider user name, ip address or both. This is a +list of what's now implemented and how login submissions affect the protections: + + 1.- On any login, the pair host<->username is saved for security, and only on a + successfull login or by track time expiration, the pair host-username is deleted + from the security log. + + 2.- For the delay operation, the host and the username are taken in count. This way, + your login time will not be affected is someone is attempting to brute the account + from other IP address. + + 3.- For the soft blocking operation, any failed attempt from that host is being count, + and when the number of attempts exceeds, the host is not allowed to submit the form. + + Note: (2nd and 3rd impose restrictions to the login form, and the time these + restrictions are in rule is the time the information is being tracked: "Track Time"). + + 4.- For the user blocking operation, any failed attempt is count, so no matter what + the source IP address is, when too many attempts appear the account is blocked. A + successful login, even if the user is blocked will remove any tracking entry fron the + database. + + 5.- For the host blocking operation, only the host is taken in count. When too many + attempts appear, no matter the username being tested, the host IP address is banned. + + Note: (4th and 5th operations are not being cancelled automatically). + Note: The tracking entries in the database for any host <-> username pair are + being deleted on: 'login', 'update' and 'delete' user operations. + -This module doesn't include the option to notify the user when it's account is blocked. You -can use the module: "Extended user status notifications" for that operation. +Most used configuration +----------------------- -Future Roadmap --------------- + The most common configuration options will look like this: -In a future a better bruteforce and control function is to be included, so -database is now ready for this future update. A fuzzy dataminner will be able -to detect bruteforce attacks no matter the time and scope. + Track time = 1 Hour + Login delay base time = 5 secs. + Max number of logon failures before blocking a user = 5 + Max number of logon failures before soft blocking a host = 10 + Max number of logon failures before blocking a host = 15 -Why is not password policy included in this module? Because of: -http://drupal.org/project/password_policy + - The user will be blocked after five attemps of account guessing within the last 60 minutes. + - Any host Trying to guess an account will be punished with 5 seconds delay and growing on + each attempt. + - Any host trying 10 login attempts will be punished not being able to submit the form again + within the 60 minutes track time. + - If the number of attempts reaches 15, the host will be banned. + + +Other modules interaction +------------------------- + +If you want your users to be informed when it's account has been blocked, you can use the +module "Extended user status notifications": http://www.drupal.org/project/user_status + + + +Other notes +----------- + +The session ID (php session neither drupal's session) is not taking in count for +the security operations, as automated bruteforce tool may request new sessions on +any attempt, ignoring the session fixation from the server. -There exists a module for that, may be you should encourage it's mantainer to -update the code for 5.x and 6.x branches of drupal. Thanks to.. ----------- -Christefano has done a great job helping with the code cleanup and the string -cleaning.. my english is not that good yet!. The module has more options -now! Thanks dude! +Christefano and deekayen, both have done great contributions and help with this module. ilo [at] reversing.org -christefano can be located at http://parahuman.org/contact/