Protecting from password attacks

HCL Compass releases support enhanced security for HCL Compass authenticated users. HCL Compass can now limit the number of login attempts for a user before the user becomes locked out. HCL Compass can also limit the number login attempts from a host connecting through HCL Compass Web.

These enhancements provide protection for HCL Compass databases against brute-force password attacks. If an attacker is trying to determine the password of a particular user, they might send many login attempts with different username and password combinations until they find one that works. To protect against this HCL Compass can lock out a user or a host if a certain number of failed attempts have occurred. When a user or host locks out, the login error message is the same as if they entered an incorrect username and password. This prevents the attacker from seeing that any subsequent attempts will fail, causing them to waste resources on a continued fruitless attack. This severely limits the ability of an attacker to succeed in guessing the password.

When a user account is locked out, any subsequent login attempts for that user will be denied until the account lockout is removed by a user or security administrator. Any additional failed login attempts for this or any other user could result in the host eventually locking out. If the host is locked out then any login from that host will fail, but it will not cause any additional account lockouts. This limits the ability of an attacker from maliciously locking out many users.

The host lockout also limits the ability of an attacker to burden the system with a flood of login attempts. Once a host locks out after a certain number of failed attempts, HCL Compass will not allow any logins from that host. Fewer resources are consumed for any login attempts from locked out hosts. This prevents the attack from consuming too many resources, allowing legitimate use of the system even while an attack is underway.

This new feature is useful for deployments that have accounts that are not LDAP authenticated. Only HCL Compass-authenticated users are protected with this feature. For HCL Compass users that are LDAP authenticated, the LDAP server can be configured to enable account lockouts. The new lockout features introduced in this version are not meant to be a complete replacement for LDAP authentication. LDAP still provides many security capabilities that HCL Compass does not have, such as minimum password complexity and maximum password age. LDAP authentication is also useful for managing identity in a common location. If you need those capabilities, you should continue to use LDAP authentication. If you have accounts that are not protected by LDAP, this feature will protect those accounts.

Configuring Brute Force Protection

The default configuration of HCL Compass is that lockouts are disabled. You must configure it using the installutil loginsecurity command described below. To set loginsecurity configuration, a user needs Super User privileges. To get the current configuration you only need Security Administrator privileges.

Login security is configured using the loginsecurity command. The syntax is as follows: 


Usage: installutil loginsecurity
dbset_name (use empty quotes as default)
cq_login
cq_password
[-secret secret]
{-set {[-file configfileIn] [-setsecret new_secret]} | [-remove]} |
{-get [-file configfileOut]}

When setting the configuration you use the -set argument. You set lockout configuration using a file with the configuration options in them. Specify this file using the -file argument. There is also a secret word you can set that can be used if you are a Security Administrator or User Administrator and you are locked out. You would need this secret word and valid login credentials to remove the lockout on yourself. See the section below for removing lockout on yourself. An example configuration file is as follows: 


# Comments are preceded by '#' and are ignored.
# This enables lockouts
lockout_enable 1

# Host lockout configuration
# This sets the HOST lockout threshold to 10 tries
lockout_threshold HOST 10
# This sets the HOST reset period to 60 seconds.
lockout_reset HOST 60


# User lockout configuration
# This sets the USER lockout threshold to 10 tries
lockout_threshold USER 10
# This sets the USER reset period to 60 seconds.
lockout_reset USER 60


# Whitelist / blacklists
lockout_whitelist HOST whitelisthost
lockout_whitelist USER whitelistuser1, whitelistuser
lockout_blacklist HOST blacklisthost3
lockout_blacklist USER bl_user1
lockout_blacklist USER bl_user2,bl_user3 


# Login attempt table cleanup
# This says to cleanup any failed login attempts older
# than one day (60s/m * 60m/hr * 24hr/day), and only
# in about 1 in 20 login attempts (5%).
login_cleanup_age 8640000
login_cleanup_probability 5

Lockouts are enabled by the first line. Specifying a 1 enables lockouts and 0 disables them. The rest of the options have no effect if lockouts are disabled, but you can still include them in the configuration. If you decide to re-enable the lockouts you can just save the configuration to a file, change the value to 1 in the saved file and then set the configuration again with this edited file. The configuration file can include comments. Comments must be on their own line and the line must begin with '#'. Blank lines are ignored. More details about the configuration options are given in the Maintaining Brute Force Protection section.

You can specify both configuration file and secret in the same command, or you can specify them separately. This may be useful if you want to change the configuration but not the secret word.

You can remove the configuration and secret word by using the -set and -remove arguments. The configuration and secret word are completely removed from the database. If you want to keep a copy of the configuration you should first get it using the -get option, as described next. Removing the configuration does not remove any existing lockouts, but login security is disabled once the configuration is removed. The lockouts will not have any effect until login security is enabled again.

You use the same installutil command to get the configuration. Instead of using the -set argument you use the -get argument. If you specify the -file argument then the configuration is written to the specified file. If you don't specify a -file argument then the configuration is written to the console.

The output of this command merely indicates whether a secret word has been set or not, it does not say what the word actually is. Once you set the secret word, it can not be obtained from the database. The secret word is not actually stored in the database as-is. Instead, a one-way hash of it is stored in the database, and thus it cannot be retrieved. The admin must not forget this secret word or they will not be able to self-unlock their accounts.

The brute-force protection is configured only at the working-master but the protection works on a site-by-site basis. That is, you set the configuration on the master site, then replicate the configuration to the other sites using normal MultiSite synchronization. To ensure that accounts lock out quickly on sites being attacked, each site maintains its own list of lockouts. While this may allow an attacker additional login attempts to different sites, it is still difficult for the attacker to determine that an account or host is locked out, and typically the number of additional sites is small.

Note: Do not run the loginsecurity -set command on any site other than the working master. If you accidentally do this, then remove the configuration on the same site, using -set -remove and replicate the changes to all databases. Then set the configuration on the master.

Maintaining Brute Force Protection

Once the login security is enabled and configured, there are commands the administrator will use to look for lockouts and remove them. To find and remove lockouts, a user needs either Security Administrator or User Administrator privileges. Knowing which accounts are locked out is the first step. The following examples assume that the user running the command is a User Administrator.

Getting lockouts

To get a list of lockouts in the database, use the installutil getlockouts command: 


Usage: installutil getlockouts
dbset_name (use empty quotes as default)
cq_login
cq_password
[-secret secret]
[-type {ANY|LOGIN|HOST}]
[-match param]
[-max maxItems]

The first three arguments are self-explanatory. The -type is used to specify which type of lockout to list. You can specify that you want to see lockouts only for users (USER) or lockouts only for hosts (HOST). By default, the ANY option is chosen, which lists both users and hosts. You can limit the number of lockouts listed to make it easier to read using the -max option. By default, there is no limit to the number of lockouts listed.

If you only want the user lockouts then specify '-type USER', for example: 
installutil getlockouts mydbset admin admin_pwd -type USER
If you want to see if userA is locked out, you would specify both the '-type USER' and '-match userA', for example: 
installutil getlockouts mydbset admin admin_pwd -type USER -match userA
The command lists lockouts that match exactly and completely. For example, you cannot match by partial username. The following command would not show if userA was locked out:
installutil getlockouts mydbset admin admin_pwd -type USER -match user

The output is sorted by the USER name or HOST name. When both USER and HOST lockouts are listed, first USER lockouts are listed, and then HOST lockouts are listed. If the "-max" argument is used, then it is possible that not all lockouts will be shown. It will only list as many lockouts as you specify in that option.

Getting lockouts if you are locked out

If you are already locked out, then when you run the installutil getlockouts command, it will fail with invalid credentials. You must supply the secret word specified during configuration using the '-secret' argument along with valid HCL Compass credentials. The lockout is temporarily bypassed just for the purpose of this command. This allows a locked out user or security administrator to query the lockouts and remove them.
installutil getlockouts mydbset admin admin_pwd -secret my_secret -type USER -match admin

Removing lockouts

Once you know what is locked out, you can start removing lockouts. Remove lockouts using the installutil removelockouts command. The syntax of this command is as follows: 
Usage: installutil removelockouts
dbset_name (use empty quotes as default)
cq_login
cq_password
[-secret secret]
[-type {ANY|USER|HOST}]
[-match param]

The syntax is very similar to the getlockouts command. Any lockouts returned by the getlockouts command would be removed if you used the same arguments for the removelockouts command. Once the lockout is removed, the user or host has the full number of attempts before the user or host identified by the parameter locks out again. Here are some examples:

If you want to remove all USER lockouts then specify '-type USER', for example: 
installutil removelockouts mydbset admin admin_pwd -type USER
If you want to remove only the lockout for userA, you would specify both the '-type USER' and '-match userA', for example: 
installutil removelockouts mydbset admin admin_pwd -type USER -match userA
The command removes lockouts that match exactly and completely. For example, you cannot remove lockouts by partial username. The following command would not remove the lockout on userA: 
installutil removelockouts mydbset admin admin_pwd -type USER -match user

Removing lockout on self

If you are locked out, due to an attack or user error, the lockout on your account can only be removed if you supply a valid -secret argument, just as you did with getlockouts. Without this argument, the command will fail with an 'invalid credentials' error. For example: 
installutil removelockouts dbset_name admin admin_pwd -secret my_secret -type USER -match admin

Listing login attempts

To get a list of failed login attempts, use the installutil getloginattempts command: 
Usage: installutil getloginattempts
dbset_name (use empty quotes as default)
cq_login
cq_password
[-secret secret]
[-type {ANY|LOGIN|HOST}]
[-match param]
[-max maxItems]

This command will list any failed login attempts. The arguments are similar to the installutil getlockouts command. The attempts are listed from oldest to newest. For each failed login attempt, a USER value is logged. For HCL Compass Web, and OSLC APIs, a HOST is also logged, so each failed login may provide two lines of output, one for USER, and one for HOST. Included in the output of this command is date when the login attempt occurred, the type of the parameter that was used (e.g. "USER" or "HOST") and the actual parameter used (e.g. "bob").

Administrators may use this to monitor failed login attempts for the HCL Compass database. The output may be used to identify hosts that are being used to mount attacks, which should be added to the host blacklist. It may also reveal that attacks are under way on particular accounts that might be sensitive. Steps could then be taken to ensure that the accounts are properly secured.

The login attempts are listed from oldest to newest. If the "-max" argument is used to limit the number of login attempts printed, then the newest login attempts might not be shown. Login attempts are periodically removed from the system. See Cleaning up the login attempts.