Password protection scenarios
The system uses the configuration options to govern how it protects from brute force attacks.
Brute force attacks are characterized by a malicious agent attempting to quickly login many times with different username and password combinations in an attempt to find one that works. Lockouts occur when the system detects that the threshold for failed login attempts has been reached for a particular parameter. Two kinds of parameters can lockout independently, the username and the host. More details are given in the following scenarios.
Malicious attacks on one user account -non-web clients
Malicious agents may target a single account on the system, rapidly trying many possible passwords. The system locks out this account once a certain number of failed attempts have occurred. The threshold is specified by the login_threshold option in the configuration file. This is followed by either the word 'USER' or 'HOST' to specify which parameter type to lock out. To cause a user lockout after 10 failed attempts you would use this configuration option:
lockout_threshold USER 10
Once the threshold has been reached, the account is locked out. Even if the correct credentials are supplied, it will still fail with a generic 'invalid credentials' error. There is no specific indication given that the account is actually locked out. This is important, to avoid revealing any information about the validity of the credentials or whether the account is locked out.
These attacks may occur either by a person manually entering the user password in the HCL Compass client (either Eclipse or Windows™ client), or using a CQPerl or VisualBasic script and the HCL Compass APIs to try many different passwords for a user.
Malicious attacks via HCL Compass Web, OSLC
Denial-of-service mitigation and user-error mitigation
Any system of brute-force protection via lockouts is susceptible to denial-of-service attacks as the attacker may purposely attempt to lock out important users and hosts. It is also possible for users to accidentally lock themselves out by repeatedly using the wrong password. This adds administrative overhead as an administrator must take the time to periodically find and remove lockouts on valid users. There are several built-in mitigations to reduce the potential disruption for these kinds of attacks and user errors. These include an automatic lockout reset capability and whitelist/blacklist for hosts and users.
To reduce the potential for denial-of-service attacks caused by a malicious agent intentionally causing lockouts, the system allows lockouts to automatically reset. It is important to note that there is a difference between automatically resetting the lockout and removing the lockout via the installutil removelockouts command. The former (reset) simply allows one more attempt before locking out again. The second (removal) completely removes the lockout and allows the full number of retries before locking out again.
The automatic lockout resets are mainly effective against denial-of-service attacks when the HOST lockout is configured in addition to the USER lockouts. The idea is that once the HOST locks out, then any subsequent login attempts from that host will no longer cause USER lockouts. For this to work, the HOST must remain locked out so that the username will automatically reset once the configured reset period has elapsed. An example configuration for this is given in the next section.
In addition to denial-of-service mitigation, the automatic resets also reduce the amount of administration needed to respond to user errors. If a user is accidentally locked out due to too many failed attempts, they only would need to wait for the reset period to elapse before trying again. They would not have to contact support unless they truly forgot their credentials and need a password reset.
Lockout Reset Period
The login security can be configured to automatically reset a lockout after a certain amount of time has passed where no log in attempts have been made for that login parameter. This can be configured using the following line:
lockout_reset USER 60
This line configures the lockout reset period for USER parameters to 60 seconds. This can be thought of as a cooling-off period that allows the lockouts to automatically reset without administrative intervention. Once 60 seconds have passed and there have been no additional login attempts for the locked out parameter, the lockout expires and the user can make one more attempt. If that attempt fails, then the parameter locks out again. The user can try again in 60 seconds, ad-infinitum. If there is no lockout_reset line for the parameter type then there is no automatic reset. You can also specify a value of 0 which would explicitly disable the reset.
For an effective defense against denial-of-service attack causing lockouts on users, set the HOST reset period to a value higher than the USER reset period (or disabling automatic reset for HOST). This allows the USER lockout to be reset while the attacking HOST remains locked out. Remember, when a host is locked out, then any subsequent login attempts will not cause or prolong any user lockouts. Then the user can log in with valid credentials to remove the lockout. An attacker could circumvent this by mounting an attack from a different HOST (or proxy), but that may lock out eventually as well.
Here is an example configuration that would do this. The HOST locks out after 10 tries and remains locked out for 60 minutes. The USER locks out after 3 tries, but it resets within 1 minute. Once the USER lockout expires, the HOST lockout persists, since the reset period is longer. This prevents that host from causing future lockouts, giving the rightful user a chance to login and clear the lockout.
lockout_threshold HOST 10
lockout_reset HOST 3600
lockout_threshold USER 10
lockout_reset USER 60
Increasing Lockout Reset Period
lockout_reset HOST -60
When the first lockout on the HOST parameter occurs, it waits 60 seconds before resetting the lockout. If, after the reset period another failed attempt occurs, the new reset period is 120 seconds. Each subsequent reset period is a multiple of the absolute value provided in the configuration (e.g., 180 seconds, 240 sections, 300 seconds, ...).
Once a user or host is locked out, the user or anyone using the host must wait for the lockout to reset automatically or for the user administrator to remove it. If the lockout automatically resets, the person has one more try before the parameter locks out again, as described above. If, after the lockout resets, the user successfully logs in, then the lockout is completely removed (as if the administrator ran installutil removelockout).
Blacklists
If an attacker consistently mounts denial-of-service or brute-force attacks via a group of hosts or proxy servers, these hosts can be added to a blacklist. Any incoming request from a blacklisted host will fail as if the host is locked out. It will simply fail with invalid credentials, and it will not cause any additional user lockouts. A blacklisted host consumes less database, CPU, and memory resources during the login attempt, reducing the ability of an attacker to mount an effective resource-based denial-of-service campaign.
A blacklist is a list of users or IP addresses that will be prevented from logging in. If a USER or HOST is in the blacklist then HCL Compass does not even attempt to authenticate the user credentials. A blacklist is specified in the configuration file that is set with the installutil loginsecurity command. The relevant configuration lines look like this:
lockout_blacklist HOST blacklisthost3
lockout_blacklist USER bl_user1
lockout_blacklist USER bl_user2,bl_user3
An administrator can use the installutil getloginattempts command to get a list of failed login attempts. From that list the administrator can determine whether an attack is underway from a particular host, and then add that host to the blacklist.
Whitelists
There might be a HOST or a USER that should never be locked out. It may be so important that these never lockout that it is worth accepting the risk of an attacker breaking into this account using brute-force methods, or mounting a denial-of-service attack via a whitelisted host or user. Suppose you have an important service account. The account does not have any admin privileges but it can perform certain specific, regular, and important tasks defined for that service user. To prevent the account from being locked out, which would prevent the important regular tasks from being completed, the username could be added to a USER whitelist. Any username on the USER whitelist would never be locked out no matter how many attempts were made. It is therefore important that a suitably strong password be used for this account, and that it be changed regularly.
An example of a HOST that should never be locked out might be an important proxy server used by HCL Compass Web users to login to HCL Compass. When connecting to HCL Compass Web servers using a proxy server, HCL Compass sees the requests as coming from the proxy-server rather than the actual location of the browser client. If an attacker mounts an attack through the proxy he can effectively cause a denial-of-attack by locking out the proxy server and preventing all users who use that proxy server from connecting. To prevent this proxy server from being locked out the customer can put the proxy server on a HOST whitelist.
While the whitelisted values never lock out, the other parameter in the failed login attempt is still logged if it is not also in a whitelist. For example, if the user is in a whitelist but the host is not, then the failed login attempt is still logged for the host. This allows some protection in spite of the whitelisted login parameters.
Whitelist values are specified in the configuration file, just like blacklists. Here are some examples:
lockout_whitelist HOST whitelisthost
lockout_whitelist USER whitelistuser1, whitelistuser
Reference of login security configuration options
A reference for configuration options follows.
- Enabling lockouts
lockout_enable {0|1}
- Enable or disable lockouts. Use 0 to disable or 1 to enable lockouts.
To disable lockouts:
lockout_enable 0
To enable lockouts:
lockout_enable 1
- Setting lockout thresholds
lockout_threshold {USER|HOST} {threshold}
- Specifies how many failed login attempts should occur before a
parameter locks out. To lockout users after 5 attempts:
To lockout hosts after 10 attempts:lockout_threshold USER 5
lockout_threshold HOST 10
Automatic Lockout Resets
lockout_reset {USER|HOST} {reset_period_in_seconds}
- To reset USER lockouts after 60 seconds:
lockout_reset USER 60
- To reset HOST lockouts after 60 seconds after first lockout, then
120 seconds after second lockout, then 180 seconds after third lockout,
etc. The reset period starts again at 60 seconds after a successful
login or after the lockout is removed.
lockout_reset HOST -60
Adding to a whitelist or blacklist
You can add users or hosts to a whitelist or blacklist. A whitelist value never locks out, but during a failed login attempt that uses a whitelist value, a non-whitelist value may get locked out. For example, suppose BOB is on the USER whitelist. If a failed login attempt occurs from the host with IP address W.X.Y.Z, and this host is not on the HOST whitelist, then a failed login attempt will be logged for HOST W.X.Y.Z, but not for the username BOB.
lockout_whitelist {USER|HOST} value1[,value2[,value3[,...]]]
lockout_blacklist {USER|HOST} value1[,value2[,value3[,...]]]
Multiple lockout_whitelist or lockout_blacklist lines can exist in the configuration, making it easier to organize this file. Values must be comma separated and white space is ignored.
Cleaning up the login attempts
login_cleanup_age {age_to_cleanup_in_seconds}
login_cleanup_probability {percent_chance_that_cleanup_will_occur}
Multisite and Login Security
Configuration of login security is made on the working master for a multisite family of databases. This is automatically replicated to all the databases with normal MultiSite synchronization. Each site separately keeps track of login attempts and lockouts and these are not replicated between databases.