Combodo's customers only

This extension helps you secure the iTop login process against brute force attacks. (see wikipedia and especially the chapter Countermeasures)

Basically this extension watch every login tentative and on some conditions:

• If the login comes from some IP ranges
• If the login fails (invalid login or invalid password)
• If a captcha image was used to login and returns a high score
• If a recaptcha returns a low score

It can triggers brut force countermeasures, which can be any of those:

1. slowdown: user has to wait between login trials.
2. recaptcha: recaptcha is activated on the login page
3. captcha: a captcha image is added to the login page
4. login invalid: Could be used to deny iTop access from a given IP range for eg.
5. login invalid for a limited duration: applies to a specific login
6. no answer: do ​not reply to login request, should be limited to some conditions
7. no answer for a limited duration: applied to a particular login

Conditions and countermeasures are explained in further details below.

• The scripts called using CLI may not be secured by this extension.
• The login_mode form is the only one that can interact with captcha and recaptcha.
• By default this extension does not perform any securement, until you configure it.

• iTop 2.7 or above

• Use the Standard installation process

You'll find below a series of configuration examples, they vary in complexity.

configuration.php

   'itop-fence' => array (
      // if false, iTop Fence will be entirely disabled
      'enabled' => false,
   ),

You can use this minimal configuration, which slowdown after 3 failed logins:

configuration.php

'itop-fence' => array (
   // Associate countermeasure with checkers, 
   // optionnaly filtering them with levels and login_mode.
   'checker_to_countermeasure' => array (
      //The most basic configuration : if the login fail three times, slowdown the auth process
      array (
	'checker' => 'Combodo\\iTop\\Fence\\Checker\\LoginFailedListener',
	'countermeasure' => 'Combodo\\iTop\\Fence\\Countermeasure\\Slowdown',
	'min_level' => 3,
      ),
   ),
),

This configuration, with lock a login for one hour after 3 failed logins:

configuration.php

    'itop-fence' => array (
	'no_answer_duration' => 3600,
	'checker_to_countermeasure' => array (
	    0 => array (
		'checker' => 'Combodo\\iTop\\Fence\\Checker\\LoginFailedListener',
		'countermeasure' => 'Combodo\\iTop\\Fence\\Countermeasure\\NoAnswerUntil',
		'min_level' => 3,
	    ),
	),
    ),

If you want to always display a captcha:

configuration.php

    'itop-fence' => array (
	'checker_to_countermeasure' => array (
	    0 => array (
	        'checker' => 'Combodo\\iTop\\Fence\\Hybrid\\Captcha',
	        'countermeasure' => 'Combodo\\iTop\\Fence\\Countermeasure\\LoginInvalid',
	        'max_level' => 5,
	        'login_mode_included' => ['form']
	    ),
	),
    ),

In this example we want to:

• Let users with IP in a trusted range, login without captcha,
• Ask users to fill a captcha if their IP is not trusted and they use the “form” login_mode
• Do not answer in other situation

configuration.php

    'itop-fence' => array (
        // Define trusted IPs
	'trusted_ip_list' => array (
	    0 => '::1', // An IP mask
	    1 => '127.0.0.1',  //  A single IP
	    2 => '192.168.55.0/24',  // A subnet
	),
	'malicious_ip_list' => array (
	),
	'checker_to_countermeasure' => array (
            // If login_mode = 'form' and IP in trusted list
            //   => Ask for a captcha image to be filled
	    0 => array (
		'checker' => 'Combodo\\iTop\\Fence\\Checker\\IpRangeChecker',
		'countermeasure' => 'Combodo\\iTop\\Fence\\Hybrid\\Captcha',
		'max_level' => 1,
		'login_mode_included' => ['form']
	    ),
            // Else if login_mode other than 'form' and IP in trusted list
            //   => No answer
	    1 => array (
		'checker' => 'Combodo\\iTop\\Fence\\Checker\\IpRangeChecker',
		'countermeasure' => 'Combodo\\iTop\\Fence\\Countermeasure\\NoAnswer',
		'max_level' => 1,
		'login_mode_excluded' => ['form']
	    ),
	    // Else IP NOT in trusted list
            //   => No Answer
	    2 => array (
		'checker' => 'Combodo\\iTop\\Fence\\Checker\\IpRangeChecker',
		'countermeasure' => 'Combodo\\iTop\\Fence\\Countermeasure\\NoAnswer',
		'min_level' => 2,
	    ),
	),
    ),

Here is a complex example of configuration:

configuration.php

'itop-fence' => array (
   // if false, iTop Fence will be entirely disabled
   'enabled' => true,
   //recaptcha will not be activable until both two keys are configured
   // if you have no key, remove following entry from your configuration
   'recaptcha_public_key' => NULL, 
   'recaptcha_private_key' => NULL,
   // IpRangeChecker base configuration. 
   // NB: You can use ipv4 and ipv6, you can also use subnets   
   'trusted_ip_list' => array('::1', '127.0.0.1'),     
   'malicious_ip_list' => array(),   //you can use ipv4 and ipv6, you can also use subnets 
 
   // Associate countermeasure with checkers, 
   // optionally filter them with levels and login_mode.
   'checker_to_countermeasure' => array (
      //The most basic configuration : if the login fail three times, slowdown the auth process
      array (
	'checker' => 'Combodo\\iTop\\Fence\\Checker\\LoginFailedListener',
	'countermeasure' => 'Combodo\\iTop\\Fence\\Countermeasure\\Slowdown',
	'min_level' => 3,
      ),
      // Recaptcha is meant to be used only with the login_mode "form"
      // 0.4 is a really bad score, below let's consider the user as a BOT
      // and lie him by saying that the password is invalid 
      array (
	'checker' => 'Combodo\\iTop\\Fence\\Hybrid\\Recaptcha',
	'countermeasure' => 'Combodo\\iTop\\Fence\\Countermeasure\\LoginInvalid',
	'max_level' => 0.4,
	'login_mode_included' => ['form'],
      ),
      // Better score but still suspicious, let's add an image captcha in order to check
      array (
	'checker' => 'Combodo\\iTop\\Fence\\Hybrid\\Recaptcha',
	'countermeasure' => 'Combodo\\iTop\\Fence\\Hybrid\\Captcha',
	'min_level' => 0.4,
	'max_level' => 0.6,
	'login_mode_included' => ['form'],
      ),
      // IpRangeChecker: 
      // if the ip is not from the trusted list and the login mode is form, let's add a captcha
      array (
	'checker' => 'Combodo\\iTop\\Fence\\Checker\\IpRangeChecker',
	'countermeasure' => 'Combodo\\iTop\\Fence\\Hybrid\\Captcha',
	'max_level' => 1,
	'login_mode_included' => ['form'],
      ),
      // IpRangeChecker: 
      // if the ip is not trusted and the login mode is NOT form, let's refuse to answer
      // this require you to list every and each non interactive client's IP to iTop
      // generally, you'll need to provide a VPN for mobile users as their IP may vary otherwise
      array (
	'checker' => 'Combodo\\iTop\\Fence\\Checker\\IpRangeChecker',
	'countermeasure' => 'Combodo\\iTop\\Fence\\Countermeasure\\NoAnswerUntil',
	'max_level' => 1,
	'login_mode_excluded' => ['form'],
      ),	
      // IpRangeChecker: 
      // if the ip is from the malicious list, we don't even bother to answer.
      // note: you should use the malicious list as an emergency tool, 
      // Firewall rules offer better performance to handle thousand of rules
      array (
	'checker' => 'Combodo\\iTop\\Fence\\Checker\\IpRangeChecker',
	'countermeasure' => 'Combodo\\iTop\\Fence\\Countermeasure\\NoAnswerUntil',
	'min_level' => 2,
      ),
   ),
),

Here is the details of each possible parameter for this extension:

The main work is to associate checkers with countermeasure inside the configuration's checker_to_countermeasure entry, using optionally these filters:

1. max_level: When you set a max level, the returned level must be below or equal to max_level to apply the countermeasure
2. min_level: When you set a min level, the returned level must be above or equal to min_level to apply the countermeasure
3. login_mode_included - if not specified, all login_modes are included
4. login_mode_excluded - if not specified, none are excluded

If a login_mode is included and excluded at the same time, I can't predict the behavior, just change your configuration

Each security checker returns a level of risk. Depending on the level reached, iTop activates countermeasures.
The level depends on the security checker:

What is returned by the Checker:

• login failed: the number of successive fails
• ip range:
  • level 1: the IP is not in the trusted list (trusted_ip_list)
  • level 2: the IP is in the malicious list (malicious_ip_list)
• recaptcha: a float between 0 and 1, it's the confidence about the user being a human (1 : max trust)
• captcha image: the number of miss-typed characters

Question: If a trusted_ip_list and a malicious_ip_list are set and the IP is not in the first one but is in the second, the level returned? Answer: The returned level is 2.

Value to use in the configuration file

• login failed: Combodo\\iTop\\Fence\\Checker\\LoginFailedListener
• ip range: Combodo\\iTop\\Fence\\Checker\\IpRangeChecker
• captcha: Combodo\\iTop\\Fence\\Hybrid\\Captcha |
• recaptcha: Combodo\\iTop\\Fence\\Hybrid\\Recaptcha |

Note: there is possibility for the NoAnswer and NoAnswerUntil, to display an error message, also this is rather incoherent with the purpose of NoAnswer. For this just define this dictionary entry: UI:iTopFence:NoAnswerUntil:Message.

Value to use in the configuration file:

• Slowdown: Combodo\\iTop\\Fence\\Countermeasure\\Slowdown
• Captcha image: Combodo\\iTop\\Fence\\Hybrid\\Captcha
• Recaptcha: Combodo\\iTop\\Fence\\Hybrid\\Recaptcha
• LoginInvalid: Combodo\\iTop\\Fence\\Countermeasure\\LoginInvalid
• LoginInvalidUntil: Combodo\\iTop\\Fence\\Countermeasure\\LoginInvalidUntil
• NoAnswer: Combodo\\iTop\\Fence\\Countermeasure\\NoAnswer
• NoAnswerUntil: Combodo\\iTop\\Fence\\Countermeasure\\NoAnswerUntil

There is a global parameter in iTop which allow to configure how talkative a log should be for a given module

log_level_min: You can filter/disable the logs by adding an entry into log_level_min.

• Info: (default) use this value in production
• Debug: if you are trying to configure itop fence, you should switch to this level
• Trace: This level enable more logs than Debug, most of the time you don't need this.

$MySettings = array(
    // ...
    'log_level_min' => array (
       // ...
       'iTopFence' => 'Info',
       // ...
    ),
    // ...
);    

The above example give you a hint at how to properly use iTop fence : you define countermeasure that are called when checker trigger

optionally filtering them to a specific level and/or to specific login_mode.

Question: Which countermeasure is applied, when two or more are triggered by a different checker?
Answer:

• NoAnswer and NoAnswerUntil, take over all other countermeasures, which are not applied.
• Then LoginInvalid and LoginInvalidUntil, will take precedence, on the remaining countermeasures
• Then, the 3 others work in parallel

iTop Fence is written as an plugin system: so you can write your own checkers and countermeasures.

Writing your own checkers and countermeasures require very few code. This is made possible because they have no dependencies with each other (the StrategyManager is the glue bringing them together based on the checker_to_countermeasure configuration).

Writing your own checker is extremely easy, you just have to plug yourself in the login process of iTop, the easiest way is to extend AbstractLoginFSMExtension (see https://wiki.combodo.com/doku.php?id=latest:customization:authentication#extending_the_authentication_process for a full list of possibilities).

Once you've done this, you'll just have to call StrategyManager::enable(self::class, $yourOwnLevelSystem); when relevant. please note that this call must take place:

• before the standard login procedure
  • so the ListSupportedLoginModes() must at least return 'before'
• during the start and during the check credential states

tip: StrategyManager::IsCheckerUsed(self::class) return true only if the checker if configured for the current login_mode.

This is easily feasible by defining a GetLoginData method. Please note that this probably mean that you checker is not compatible with other login mode than form, thus, every time a configuration reference this checker, it should filter using 'login_mode_included' ⇒ ['form']. This also mean that another checker should cover the case of 'login_mode_excluded' ⇒ ['form'],.

Please refer to https://wiki.combodo.com/doku.php?id=latest:customization:authentication#screen_customization in order to discover how to write the GetLoginData method.

In order to create your own countermeasure, you just have to extend AbstractCountermeasure and write your own OnCheckCredentials method.

• if you want to let the login process continue, return LoginWebPage::LOGIN_FSM_CONTINUE
• if you want to stop the login process
  • set to a relevant error code (ie $iErrorCode = LoginWebPage::EXIT_CODE_WRONGCREDENTIALS)
  • return LoginWebPage::LOGIN_FSM_ERROR

tip: $this→IsEnabled() return true only if you have been activated has a countermeasure.

This is the case of captcha and recaptcha, so, you know the idea : you should take a look at Captcha. And then read those explanations ;)

You have to call StrategyManager::enable(self::class, $iLevel) when you detect a suspicious activity, and alway return a relavant value for the statemachine (ie return LoginWebPage::LOGIN_FSM_ERROR in the OnCheckCredentials method)

Finally, checker and countermeasure are always called by the login FSM, so if you want to perform code only if you are legit, you should do this check if (StrategyManager::IsCheckerUsed(self::class) || $this→IsEnabled()).