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

If a constant reset period does not provide enough disincentive for the brute-force attack, the administrator can configure an increasing reset period. This is done by passing a negative number in the configuration, as follows:


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:
```
lockout_threshold USER 5
```
To lockout hosts after 10 attempts:
```
lockout_threshold HOST 10
```

Automatic Lockout Resets


lockout_reset {USER|HOST} {reset_period_in_seconds}

Specifies how long until a lockout automatically resets, allowing one more login attempt before locking out. The reset period is specified in seconds. The reset happens the next time the user or host is used during the login after the reset period has elapsed.

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

Note: The installutil getlockouts command will continue to show that the parameter is locked out past the reset period. This is expected since the reset actually occurs on the next successful login with that user or host after the reset period has elapsed.

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.

If a value is on a blacklists, the failed login is not logged (in order to prevent an attack from consuming database space) but it still behaves as it was locked out. This prevents any lockout on values not in the blacklist. For example, suppose host W.X.Y.Z is on the blacklist but JOE is not. If a failed login attempt comes from W.X.Y.Z, it will not contribute to a lockout of JOE. The configuration for whitelist or blacklist is one or more lines like this:

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

Failed login attempts are stored in the HCL Compass master database. Over time this list may grow very large. You should configure HCL Compass to automatically clean up this list, removing the record of attempts that are no longer needed. You configure this by specifying two values. The first value is how old (in seconds) the record of a login attempt must be before it can be removed. The second value is the probability that any given login should do the cleanup. The cleanup will happen during a successful login, and the probability that the cleanup will happen is specified by login_cleanup_probability. For example if you specify 600 for login_cleanup_age and 5 for login_cleanup_probability, then cleanup will happen roughly once for every 20 logins and it will remove the records for any attempts that are older than 10 minutes. If you specify 100 for login_cleanup_probability then cleanup happens on every login. If you specify 0 then cleanup never happens. The default value for login_cleanup_probability is 1 (1%). The default value for login_cleanup_age is one day.

login_cleanup_age {age_to_cleanup_in_seconds}
login_cleanup_probability {percent_chance_that_cleanup_will_occur}

Note: There is no way to view the failed login attempts except by connecting to your database directly and running an SQL query. This capability may be added to installutil in a future release.

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.