You are here

README.txt in Login Security 7

Same filename and directory in other branches
  1. 8 README.txt
  2. 5 README.txt
  3. 6 README.txt
  4. 2.x README.txt
Login Security
--------------
This module was developed to improve the security options in the login operation
of a Drupal site. By default, Drupal has only basic access control denying IP
access to the full content of the site.

With Login Security module, 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).

These are the features included:

Ongoing attack detection
------------------------
System will detect if a password guessing or bruteforce attack is being performed
against the Drupal login form. Using a threshold value, you may instruct the
module to alert (using a watchdog message, and optionally send an email) the
admin user when the number of invalid login attempts reaches the threshold value.

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:

 - 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
----------------
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 common to block an account after a number of failed login
   attemps. Once this count is completed, the account can be 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 have happened 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


Installation
------------
To install copy the login_security folder in your modules directory. Go to
Administer -> Site Building -> Modules and under the "Other" frame the
"Login Security" module Item will appear in the list. Enable the Checkbox
and save the configuration.


Configuration options
---------------------
You should have the 'administer site configuration' permission to configure the
Login Security module.

Go to Administer -> Site configuration -> Login Security (the url path is
admin/settings/login_security) and a form with the module options will be shown.
(Note: 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.

 - Maximum 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

 - Maximum 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.

 - Maximum 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.

 - Maximum number of login failures to detect ongoing attack: This value is the
   threshold used to detect a password guess attack. The limit means that during
   the "track time" period, this number of invalid logins indicates a password
   guessing attack.

Notifications

 The module also provides some notifications for the users to understand what is
 happening.

 - 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.

 - Display last access timestamp: each time a user does success in login, this
   message will remember him his last site access.

 - 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 a notification email message to a site user of your choice, each time an
   account is blocked.

 - Send a notification email message to a site user of your choice about login
   suspicious activity (a determined value threshold of invalid login attemps
   is reached).

Notifications are configurable in the Login Security settings section, where
the strings could be personalized using the following placeholders:

    %date                  :  The (formatted) date and time of the operation
    %ip                    :  The IP Address performing the operation
    %username              :  The username entered in the login form (sanitized)
    %email                 :  If the user exists, this will be it's name
    %uid                   :  ..and if exists, this will be it's uid
    %site                  :  The configured site's name
    %uri                   :  The base url of the Drupal site
    %edit_uri              :  Direct link to the user (name entered) edit page
    %hard_block_attempts   :  Configured attempts before hard blocking the IP
    %soft_block_attempts   :  Configured attempts before soft blocking the IP
    %user_block_attempts   :  Configured login attempts before blocking the user
    %user_ip_current_count :  The total attempts for the name by this IP address
    %ip_current_count      :  The total login attempts by this IP address
    %user_current_count    :  The total login attempts for this name
    %tracking_time         :  The tracking time: in hours
    %tracking_current_count:  Total tracked events
    %activity_threshold    :  Value of attempts to detect ongoing attack.


Cleaning the event tracking information
---------------------------------------
If for any reaons, you are encoutering problems with specific users (because
they are restricted), or if you change settings and want to do a module
'restart', you may clean the event track in this settings page.
At the bottom you will find a "Clear event tracking information" button.
If you click this button, all tracked events will be deleted.


Understanding protections
-------------------------
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 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").

 3.- 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.

 4.- 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.

 5.- For the onoing attack detection, all the tracked events are taken in count.
   The system detects an ongoing attack and notices the admin about that. It will
   remain in attack mode (no more notices will be sent) untill the attack is no
   longer detected. This will happen when the total number of tracked events is
   below 'maximum allowed to detect ongoing attack' / 3. Since then, once the
   threshold value is reached again, a new notification will be set in the log
   or sent by email.

   E.g Say you put 1 hour of track time and a maximum number of login failures
   to detect ongoing attack of 20. This means that if during the last hour there
   are more than 20 invalid login attemps an attack is detected. A log entry is
   created to notice the detected attack, and system switches to 'attack' status,
   where no more notices about the attack will be logged or sent. After sometime
   the attack stops. And once the number of invalid login attemps for this last
   hour is below 1/3 of this maximum: invalid attemps are below 6 (20 / 3 for
   the example) a normal status is recovered. If a new attack is detected, the
   module will alert again about it.

Most used configuration
-----------------------
The most common configuration options will look like this:

 Track time = 1 Hour
 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

 - The user will be blocked after five attemps of account guessing within the
   last 60 minutes.
 - 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 their accounts have been blocked,
you can use the module "Extended user status notifications":
 http://www.drupal.org/project/user_status


Important note
--------------

Currently, user uid 1 is never blocked even if the "user blocking operation" is
enabled. User uid 1 is widely exposed in too many sites (and probably the name
for that account is 'admin' in most of the cases) that deliberately was removed
from this protection because of the risk to be easily blocked. If you want to
protect your users, you may use a combination of features, and not only rely on
the user blocking operation.

More information: http://drupal.org/node/601846


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.


Thanks to..
-----------
Christefano and deekayen, both have done great contributions and help with this
module.

File

README.txt
View source
  1. Login Security
  2. --------------
  3. This module was developed to improve the security options in the login operation
  4. of a Drupal site. By default, Drupal has only basic access control denying IP
  5. access to the full content of the site.
  6. With Login Security module, a site administrator may add any of the following
  7. access control features to the login forms (default login form in /user and the
  8. block login form).
  9. These are the features included:
  10. Ongoing attack detection
  11. ------------------------
  12. System will detect if a password guessing or bruteforce attack is being performed
  13. against the Drupal login form. Using a threshold value, you may instruct the
  14. module to alert (using a watchdog message, and optionally send an email) the
  15. admin user when the number of invalid login attempts reaches the threshold value.
  16. Soft Protections
  17. ----------------
  18. Soft protections don't disrupt site navigation, but alter the way a login
  19. operation is performed.
  20. Currently, the login form submission can be soft-protected with these two
  21. options:
  22. - Invalidate login form submission: when the soft-block protection flag is
  23. enabled the login form is never submited, and any new login request will
  24. fail, but the host could still access the site.
  25. Hard Protections
  26. ----------------
  27. When there is evidence of hard account guessing operations, or when you need to
  28. block users because of leak password guessing attempts, Hard protections may
  29. help defeating the system.
  30. - Block account: it's common to block an account after a number of failed login
  31. attemps. Once this count is completed, the account can be blocked and user
  32. and admin are advised about this.
  33. - Block IP address: on a number of failed attempts, a host may be added to the
  34. access control list. This action will leave the host completely banned from
  35. the site.
  36. Track time: Protection time window
  37. ----------------------------------
  38. The time the protections operate is defined as the track time (or time window).
  39. It's, the time that login events are being considered for the protections. For
  40. example, we can say that an account will be blocked on the third login attempt,
  41. but these three attempts should have happened in the protection time window.
  42. If the time protection window is 1 hour, the three attemps should be in the
  43. last 60 minutes. If one of this attempts was done earlier it's not considered.
  44. The time protection window is not the time each protection is active. Blocked
  45. accounts will remain blocked untill an administrator unblocks them, and banned
  46. hosts need also administration interaction to be unbanned.
  47. Duration of protections
  48. -----------------------
  49. The duration of the enabled protections depends of its type. Soft protections
  50. are temporary, and will expire in the time defined by the 'track time' or
  51. protection time window.
  52. Hard protections are permanent, and an administrator should unblock or unban an
  53. account or a host.
  54. A blocked account could be unblocked through the administration section:
  55. /admin/user/user
  56. A banned host could be un banned through the Access rules section:
  57. /admin/user/rules
  58. Installation
  59. ------------
  60. To install copy the login_security folder in your modules directory. Go to
  61. Administer -> Site Building -> Modules and under the "Other" frame the
  62. "Login Security" module Item will appear in the list. Enable the Checkbox
  63. and save the configuration.
  64. Configuration options
  65. ---------------------
  66. You should have the 'administer site configuration' permission to configure the
  67. Login Security module.
  68. Go to Administer -> Site configuration -> Login Security (the url path is
  69. admin/settings/login_security) and a form with the module options will be shown.
  70. (Note: Any value set to 0 will disable that option.).
  71. Basic options
  72. - Track time: The time window where to check for security violiations. It's,
  73. the time in hours the login information is kept to compute the login attempts
  74. count. A common example could be 24 hours. After that time, the attempt is
  75. deleted from the list, so it will not count.
  76. - Maximum number of login failures before blocking a user: It's that easy,
  77. after this number of attempts to login as an user no matter the IP address
  78. attempting to, the user will be blocked. To remove the blocking of the user,
  79. you will have to go to: Administer -> User Management -> Users
  80. - Maximum number of login failures before soft blocking a host: After that
  81. number of attempts to login from that IP address, no matter the username
  82. used, the host will not be allowed to submit the login form again, but the
  83. content of the site is still accesible for that IP address. Login attempts
  84. will start to clear of counts after the "Track Time" time window.
  85. - Maximum number of login failures before blocking a host: As the soft block
  86. protection does, but this time the IP address will be banned from the site,
  87. included in the access list as a deny rule. To remove the IP from this ban,
  88. you will have to go to: Administer -> User Management -> Access Rules.
  89. - Maximum number of login failures to detect ongoing attack: This value is the
  90. threshold used to detect a password guess attack. The limit means that during
  91. the "track time" period, this number of invalid logins indicates a password
  92. guessing attack.
  93. Notifications
  94. The module also provides some notifications for the users to understand what is
  95. happening.
  96. - Display last login timestamp: each time a user does success in login, this
  97. message will remember him when was the last time he logged in the site.
  98. - Display last access timestamp: each time a user does success in login, this
  99. message will remember him his last site access.
  100. - Notify the user about the number of remaining login attempts: It's also
  101. possible to advice the user about the attempts available prior to block the
  102. account.
  103. - Disable login failure error message: Selecting this option no error message
  104. will be shown at all, so user will not be aware of unsuccessful login
  105. attempt, or blocked account messages.
  106. - Send a notification email message to a site user of your choice, each time an
  107. account is blocked.
  108. - Send a notification email message to a site user of your choice about login
  109. suspicious activity (a determined value threshold of invalid login attemps
  110. is reached).
  111. Notifications are configurable in the Login Security settings section, where
  112. the strings could be personalized using the following placeholders:
  113. %date : The (formatted) date and time of the operation
  114. %ip : The IP Address performing the operation
  115. %username : The username entered in the login form (sanitized)
  116. %email : If the user exists, this will be it's name
  117. %uid : ..and if exists, this will be it's uid
  118. %site : The configured site's name
  119. %uri : The base url of the Drupal site
  120. %edit_uri : Direct link to the user (name entered) edit page
  121. %hard_block_attempts : Configured attempts before hard blocking the IP
  122. %soft_block_attempts : Configured attempts before soft blocking the IP
  123. %user_block_attempts : Configured login attempts before blocking the user
  124. %user_ip_current_count : The total attempts for the name by this IP address
  125. %ip_current_count : The total login attempts by this IP address
  126. %user_current_count : The total login attempts for this name
  127. %tracking_time : The tracking time: in hours
  128. %tracking_current_count: Total tracked events
  129. %activity_threshold : Value of attempts to detect ongoing attack.
  130. Cleaning the event tracking information
  131. ---------------------------------------
  132. If for any reaons, you are encoutering problems with specific users (because
  133. they are restricted), or if you change settings and want to do a module
  134. 'restart', you may clean the event track in this settings page.
  135. At the bottom you will find a "Clear event tracking information" button.
  136. If you click this button, all tracked events will be deleted.
  137. Understanding protections
  138. -------------------------
  139. Internally, protections could consider user name, ip address or both. This is a
  140. list of what's now implemented and how login submissions affect the protections:
  141. 1.- On any login, the pair host<->username is saved for security, and only on a
  142. successfull login or by track time expiration, the pair host-username is
  143. deleted from the security log.
  144. 2.- For the soft blocking operation, any failed attempt from that host is being
  145. count, and when the number of attempts exceeds, the host is not allowed to
  146. submit the form.
  147. Note: (2nd and 3rd impose restrictions to the login form, and the time these
  148. restrictions are in rule is the time the information is being tracked: "Track
  149. Time").
  150. 3.- For the user blocking operation, any failed attempt is count, so no matter
  151. what the source IP address is, when too many attempts appear the account is
  152. blocked. A successful login, even if the user is blocked will remove any
  153. tracking entry fron the database.
  154. 4.- For the host blocking operation, only the host is taken in count. When too
  155. many attempts appear, no matter the username being tested, the host IP
  156. address is banned.
  157. Note: (4th and 5th operations are not being cancelled automatically).
  158. Note: The tracking entries in the database for any host <-> username pair are
  159. being deleted on: 'login', 'update' and 'delete' user operations.
  160. 5.- For the onoing attack detection, all the tracked events are taken in count.
  161. The system detects an ongoing attack and notices the admin about that. It will
  162. remain in attack mode (no more notices will be sent) untill the attack is no
  163. longer detected. This will happen when the total number of tracked events is
  164. below 'maximum allowed to detect ongoing attack' / 3. Since then, once the
  165. threshold value is reached again, a new notification will be set in the log
  166. or sent by email.
  167. E.g Say you put 1 hour of track time and a maximum number of login failures
  168. to detect ongoing attack of 20. This means that if during the last hour there
  169. are more than 20 invalid login attemps an attack is detected. A log entry is
  170. created to notice the detected attack, and system switches to 'attack' status,
  171. where no more notices about the attack will be logged or sent. After sometime
  172. the attack stops. And once the number of invalid login attemps for this last
  173. hour is below 1/3 of this maximum: invalid attemps are below 6 (20 / 3 for
  174. the example) a normal status is recovered. If a new attack is detected, the
  175. module will alert again about it.
  176. Most used configuration
  177. -----------------------
  178. The most common configuration options will look like this:
  179. Track time = 1 Hour
  180. Max number of logon failures before blocking a user = 5
  181. Max number of logon failures before soft blocking a host = 10
  182. Max number of logon failures before blocking a host = 15
  183. - The user will be blocked after five attemps of account guessing within the
  184. last 60 minutes.
  185. - Any host trying 10 login attempts will be punished not being able to submit
  186. the form again within the 60 minutes track time.
  187. - If the number of attempts reaches 15, the host will be banned.
  188. Other modules interaction
  189. -------------------------
  190. If you want your users to be informed when their accounts have been blocked,
  191. you can use the module "Extended user status notifications":
  192. http://www.drupal.org/project/user_status
  193. Important note
  194. --------------
  195. Currently, user uid 1 is never blocked even if the "user blocking operation" is
  196. enabled. User uid 1 is widely exposed in too many sites (and probably the name
  197. for that account is 'admin' in most of the cases) that deliberately was removed
  198. from this protection because of the risk to be easily blocked. If you want to
  199. protect your users, you may use a combination of features, and not only rely on
  200. the user blocking operation.
  201. More information: http://drupal.org/node/601846
  202. Other notes
  203. -----------
  204. The session ID (PHP session neither Drupal's session) is not taking in count for
  205. the security operations, as automated bruteforce tool may request new sessions
  206. on any attempt, ignoring the session fixation from the server.
  207. Thanks to..
  208. -----------
  209. Christefano and deekayen, both have done great contributions and help with this
  210. module.