start portlet menu bar

HCLSoftware: Fueling the Digital+ Economy

Display portlet menu
end portlet menu bar
Select Page

HCL Compass allows the administrator to protect Compass database repositories from brute-force attacks, here is the official documentation It limits the number of invalid login attempts of an attacker, who pretends as a user, before the lock out and also limits the login attempts from a certain host connecting to HCL Compass. 

If an attacker is trying to hack and determine the password of a particular user, they might try many login attempts with different username and password combinations until they find one that works. As a defence against such attacks, HCL Compass can lock out the account or host used by the attacker when a certain number of failed attempts have occurred. When an account or a host is locked out, the login error message is the same as if the attacker entered an incorrect username and password. This prevents the attacker from knowing that the account has been locked out, causing them to waste resources on a continued fruitless attack. This severely limits the attacker to succeed in guessing the password. 

Steps to protect the credential 

HCL Compass enables the credential protection in just two simple steps. 

  1. First step to enable security is by creating a “.config” file with the below data. In this example we will create the config file with the name “SecureCredential.config”. This file can be created in any location; hence we have created the file in the HCL Compass default installation location, which is, “C:\Program Files\HCL\CCM\Compass” 

# 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 and disabled by the first line. Specifying a value of in “lockout_enable” enables lockouts and a value of 0 disables them. The rest of the options have no effect if the lockout is disabled 

2. After creating the config file, we can enable the lockout feature by executing the below installutil command  

installutil loginsecurity “connection1” “admin” “password” -set -file SecureCredential.config 

 In the above example we are using the connection (“connection1”) to which we are enabling the lockout, and Compass login credential (username: “admin” and password: “password”) along with the config file we created in Step #1.  

 Following is be the output of the command:

steps to protect the credential

With the above two steps, our setup is ready and once you have secured the credential, following are some specific customization for the login credential security. All the settings in the lockout configuration should be reviewed and set based on your organization needs. 

Lockout a user account 

Consider if we want the user account which the attacker is using to be locked out after 3 consecutive wrong attempts, then we make changes to our config file (SecureCredential.config) as below. 

 # User lockout configuration
# This sets the USER lockout threshold to 3 tries
lockout_threshold USER 3 

# This sets the USER reset period to 60 seconds.
lockout_reset USER 60

By the above configuration we set lockout threshold for the account as 3, which means that user will be locked after three consecutive wrong attempts. 

 The next statement is the reset time. From the above configuration, lockout reset for the user is 60 seconds, which means the lockout will automatically be removed after 60 seconds of no logon attempts. This can be changed as per requirement. In case the reset is set to 0, there will be no reset and the user will remain locked out until admin remove the lock against the user. 

After making the above change on the config file, run the “installutil” command again: 

installutil loginsecurity connection1 admin password -set -file SecureCredential.config 

The output to the command is as shown below: 

login security

Now login to HCL Compass and try incorrect password on a user for 3 or more times and then input the correct password. Login error would be displayed on all the attempts including the attempt with the correct credential. This behaviour is because the user is locked out after 3 consecutive wrong attempts and Compass is will not allow anymore login attempts.  


HCL compass login error

From the above screenshot we can see that even after providing the correct credential after multiple wrong attempts, the error message remains the same as if we entered an incorrect username and password. 

 We can either wait for 60 seconds (as per configuration) for the user to get unlocked, or unlock the user with a command. 

Unlock a user 

 As mentioned in the above section, if a user is locked out and the reset time is set to more than 60 seconds, instead of waiting longer, the admin user can unlock the user without any delay using the below command.

installutil removelockouts “connection1” “admin” “password 

 As seen in the above command we mention “removelockout” as parameter along with the connection (“connection1”) details to which we need to remove lock and its admin credential (username: “admin” and password: “password”) 

The output to the command is as shown below:

remove lockouts

The above removelockout command would unlock all the users in that connections. But if you want to unlock any specific user or a host, we can provide the “-type” parameter as below: 

 installutil removelockouts “connection1” “admin” “password -type USER -match lead 

 installutil removelockouts “connection1” “admin” “password -type HOST -match 

Unlock admin user 

As mentioned in the above section, an admin user unlocks the locked credential of a normal user. Similarly, there are chances of an admin user getting locked. To unlock an admin account, we must set a secret key; And this can be achieved by using “-setsecret” parameter as shown below. For this example, we will set a secret key with the value as “SecretKey”. 

installutil loginsecurity “connection1” “admin” password -set -file SecureCredential.config –setsecret SecretKey  

 The output to the command is as shown below: 

test login security

 Now in case of admin lockout, we can remove lockout on the admin account using the secret key with the below command.

 Installutil removelockouts “connection1” “admin” “password” -secret SecretKey -type USER -match admin 

remove lockouts

White listing & Black listing the Host and User 

 There are times when a trusted user from a certain host may forget their credential. For example, if the admin user always attempts his login from a certain host and if we know the host is secure, then we can whitelist that host. Similarly, we blacklist a host if you have detected continuous suspicious activity from a certain host. 

 We can whitelist or blacklist a host and user by configuring the config file by changing the desired values for the below parameters: 

# 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

For example, if we want to black list the user “lead”, then update the config file with below value: 

 lockout_blacklist USER lead 

 Next update the login security by running the “installutil” command. 

 installutil loginsecurity connection1 admin password -set -file SecureCredential.config 

secure credential config

Now HCL Compass will not let the “lead” user to login to the application. 

login error HCL Compass login applications


Similarly, we can whitelist and blacklist a hosts and users by changing the config file by updating the below parameters and running the “installutil” command as mentioned above. While executing theinstallutil loginsecurity, the command will take the value from the configuration file and overwrite the previously configured values for lockout in Compass’s DB. 

lockout_whitelist HOST
lockout_whitelist USER admin                                                                                                                                                    lockout_blacklist HOST
lockout_blacklist USER lead 


You can follow the above steps to protect your HCL Compass environment against unsolicited access and also to keep the confidential data from the attackers.  

Comment wrap
Secure DevOps | August 30, 2022
HCL Compass - Configuring secure connection on Compass Web with SSL communication
Compass Secure Web Client enables you to access your applications and data from any remote location without compromising the security of your data.
Secure DevOps | May 25, 2022
A step-by-step guide to install HCL Compass on your system with valid login credentials login into the repository.
Secure DevOps | May 19, 2022
Learn with a step-by-step guide for installing and setting up HCL compass with REST - server (trial version).