modules/login_security/README.txt

$Id: README.txt,v 1.4.4.1 2009/06/24 10:43:20 ilo Exp $

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:


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. 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: (base time) x (login attempts)

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

 - Login delay base time: Delay in seconds for the next login count. It's 
   computed by host and 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
   the number of attempts is counted within the "Track time" time value. In the
   previous example of 24 hours, after 24h the login attemps will be cleared,
   and the delay decreased.

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

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 email message to the admin: An email could also be sent to the 
   administrator (uid 1), each time an account is blocked.

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


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


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

 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

 - 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 their accounts have 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.


Thanks to..
-----------
Christefano and deekayen, both have done great contributions and help with this
module.
1	$Id: README.txt,v 1.4.4.1 2009/06/24 10:43:20 ilo Exp $
2
3	Login Security
4	--------------
5	This module was developed to improve the security options in the login operation
6	of a Drupal site. By default, Drupal has only basic access control denying IP
7	access to the full content of the site.
8
9	With Login Security module, a site administrator may add any of the following
10	access control features to the login forms (default login form in /user and the
11	block login form).
12
13	These are the features included:
14
15
16	Soft Protections
17	----------------
18	Soft protections don't disrupt site navigation, but alter the way a login
19	operation is performed.
20
21	Currently, the login form submission can be soft-protected with these two
22	options:
23
24	- Request time delay: on any failed login, a time delay in included to the
25	submit request, hardenning the bruteforce attack to the login form. Including
26	a time delay in each submission, will reduce the number of login attempts a
27	user or script can do. On each attempt, the delay time is increased, using
28	the formula: (base time) x (login attempts)
29
30	- Invalidate login form submission: when the soft-block protection flag is
31	enabled the login form is never submited, and any new login request will
32	fail, but the host could still access the site.
33
34
35	Hard Protections
36	----------------
37	When there is evidence of hard account guessing operations, or when you need to
38	block users because of leak password guessing attempts, Hard protections may
39	help defeating the system.
40
41	- Block account: it's common to block an account after a number of failed login
42	attemps. Once this count is completed, the account can is blocked and user
43	and admin are advised about this.
44
45	- Block IP address: on a number of failed attempts, a host may be added to the
46	access control list. This action will leave the host completely banned from
47	the site.
48
49
50	Track time: Protection time window
51	----------------------------------
52	The time the protections operate is defined as the track time (or time window).
53	It's, the time that login events are being considered for the protections. For
54	example, we can say that an account will be blocked on the third login attempt,
55	but these three attempts should have happened in the protection time window.
56	If the time protection window is 1 hour, the three attemps should be in the
57	last 60 minutes. If one of this attempts was done earlier it's not considered.
58
59	The time protection window is not the time each protection is active. Blocked
60	accounts will remain blocked untill an administrator unblocks them, and banned
61	hosts need also administration interaction to be unbanned.
62
63
64	Duration of protections
65	-----------------------
66	The duration of the enabled protections depends of its type. Soft protections
67	are temporary, and will expire in the time defined by the 'track time' or
68	protection time window.
69
70	Hard protections are permanent, and an administrator should unblock or unban an
71	account or a host.
72
73	A blocked account could be unblocked through the administration section:
74	/admin/user/user
75	A banned host could be un banned through the Access rules section:
76	/admin/user/rules
77
78
79	Installation
80	------------
81	To install copy the login_security folder in your modules directory. Go to
82	Administer -> Site Building -> Modules and under the "Other" frame the
83	"Login Security" module Item will appear in the list. Enable the Checkbox
84	and save the configuration.
85
86
87	Configuration options
88	---------------------
89	Go to Administer -> User Management -> User Settings and new box will appear
90	close to the registering information with the following options. Any value
91	set to 0 will disable that option.
92
93	Basic options
94
95	- Track time: The time window where to check for security violiations. It's,
96	the time in hours the login information is kept to compute the login attempts
97	count. A common example could be 24 hours. After that time, the attempt is
98	deleted from the list, so it will not count.
99
100	- Login delay base time: Delay in seconds for the next login count. It's
101	computed by host and user, so any attempt to login again with the same user
102	from the same IP address will be delayed that number of seconds. The time the
103	user has to wait for the next login operation is (attempts * delay), and
104	the number of attempts is counted within the "Track time" time value. In the
105	previous example of 24 hours, after 24h the login attemps will be cleared,
106	and the delay decreased.
107
108	- Maximum number of login failures before blocking a user: It's that easy,
109	after this number of attempts to login as an user no matter the IP address
110	attempting to, the user will be blocked. To remove the blocking of the user,
111	you will have to go to: Administer -> User Management -> Users
112
113	- Maximum number of login failures before soft blocking a host: After that
114	number of attempts to login from that IP address, no matter the username
115	used, the host will not be allowed to submit the login form again, but the
116	content of the site is still accesible for that IP address. Login attempts
117	will start to clear of counts after the "Track Time" time window.
118
119	- Maximum number of login failures before blocking a host: As the soft block
120	protection does, but this time the IP address will be banned from the site,
121	included in the access list as a deny rule. To remove the IP from this ban,
122	you will have to go to: Administer -> User Management -> Access Rules.
123
124	Notifications
125
126	The module also provides some notifications for the users to understand what is
127	happening.
128
129	- Display last login timestamp: each time a user does success in login, this
130	message will remember him when was the last time he logged in the site.
131
132	- Display last access timestamp: each time a user does success in login, this
133	message will remember him his last site access.
134
135	- Notify the user about the number of remaining login attempts: It's also
136	possible to advice the user about the attempts available prior to block the
137	account.
138
139	- Disable login failure error message: Selecting this option no error message
140	will be shown at all, so user will not be aware of unsuccessful login
141	attempt, or blocked account messages.
142
143	- Send email message to the admin: An email could also be sent to the
144	administrator (uid 1), each time an account is blocked.
145
146	Some of the strings are configurable in the same administration section. The
147	strings can be personalized using the following placeholders:
148
149	%date : The (formated) date and time of the operation
150	%ip : The IP Address performing the operation
151	%username : The username entered in the login form (sanitized)
152	%email : If the user exists, this will be it's name
153	%uid : ..and if exists, this will be it's uid
154	%site : The configured site's name
155	%uri : The base url of the Drupal site
156	%edit_uri : Direct link to the user (name entered) edit page
157	%hard_block_attempts : Configured attempts before hard blocking the IP
158	%soft_block_attempts : Configured attempts before soft blocking the IP
159	%user_block_attempts : Configured login attempts before blocking the user
160	%user_ip_current_count : The total attempts for the name by this IP address
161	%ip_current_count : The total login attempts by this IP address
162	%user_current_count : The total login attempts for this name
163	%tracking_time : The tracking time: in hours
164
165
166	Understanding protections
167	-------------------------
168	Internally, protections could consider user name, ip address or both. This is a
169	list of what's now implemented and how login submissions affect the protections:
170
171	1.- On any login, the pair host<->username is saved for security, and only on a
172	successfull login or by track time expiration, the pair host-username is
173	deleted from the security log.
174
175	2.- For the delay operation, the host and the username are taken in count. This
176	way, your login time will not be affected is someone is attempting to brute
177	the account from other IP address.
178
179	3.- For the soft blocking operation, any failed attempt from that host is being
180	count, and when the number of attempts exceeds, the host is not allowed to
181	submit the form.
182
183	Note: (2nd and 3rd impose restrictions to the login form, and the time these
184	restrictions are in rule is the time the information is being tracked: "Track
185	Time").
186
187	4.- For the user blocking operation, any failed attempt is count, so no matter
188	what the source IP address is, when too many attempts appear the account is
189	blocked. A successful login, even if the user is blocked will remove any
190	tracking entry fron the database.
191
192	5.- For the host blocking operation, only the host is taken in count. When too
193	many attempts appear, no matter the username being tested, the host IP
194	address is banned.
195
196	Note: (4th and 5th operations are not being cancelled automatically).
197	Note: The tracking entries in the database for any host <-> username pair are
198	being deleted on: 'login', 'update' and 'delete' user operations.
199
200
201	Most used configuration
202	-----------------------
203	The most common configuration options will look like this:
204
205	Track time = 1 Hour
206	Login delay base time = 5 secs.
207	Max number of logon failures before blocking a user = 5
208	Max number of logon failures before soft blocking a host = 10
209	Max number of logon failures before blocking a host = 15
210
211	- The user will be blocked after five attemps of account guessing within the
212	last 60 minutes.
213	- Any host trying to guess an account will be punished with 5 seconds delay and
214	growing on each attempt.
215	- Any host trying 10 login attempts will be punished not being able to submit
216	the form again within the 60 minutes track time.
217	- If the number of attempts reaches 15, the host will be banned.
218
219
220	Other modules interaction
221	-------------------------
222	If you want your users to be informed when their accounts have been blocked,
223	you can use the module "Extended user status notifications":
224	http://www.drupal.org/project/user_status
225
226
227	Other notes
228	-----------
229	The session ID (PHP session neither Drupal's session) is not taking in count for
230	the security operations, as automated bruteforce tool may request new sessions
231	on any attempt, ignoring the session fixation from the server.
232
233
234	Thanks to..
235	-----------
236	Christefano and deekayen, both have done great contributions and help with this
237	module.