Documentation
Submit Request Try Free
Documentation: WebShield

WebShield

Captcha

The CAPTCHA is a feature intended to distinguish human from machine input and protect websites from the spam and different types of automated abuse. Imunify360 uses reCAPTCHA service.

Warning

Please note that the WebShield Captcha is not compatible with aggressive CDN caching modes, like Cloudflare 'cache everything' with 'Edge Cache TTL'. If the Сaptcha page is cached by CDN, a visitor will see the Captcha from CDN cache disregarding it has been passed or not. In order to fix that, either disable the aggressive CDN caching or the Captcha functionality in the Imunify360.

There are two layers in CAPTCHA behavior:

  1. If a user of a website is added to the Grey List (the access is blocked), then the CAPTCHA allows him to unblock himself. When he tries to get to the website he is redirected to the Captcha Server by ipset, where he can see the protection page asking to confirm that he is not a robot by ticking a checkbox.

Note

The IP address on the screenshot above is given as an example.

If successful, a user is redirected to the website, which means that the access is unblocked and the IP address of this user is removed from the Grey List.

It is also possible to enable the invisible reCAPTCHA via the Imunify360 Settings page. With the invisible reCAPTCHA enabled, a human user is not required to go through human confirmation - the process will pass under the hood and a user will be redirected to the website. In case if invisible reCAPTCHA failed to detect if a user is a human or not, then visible reCAPTCHA appears.

  1. The CAPTCHA is always on guard of the websites and checks the activity of each IP. With the help of reCAPTCHA it blocks bots and protects websites from spam and abuse. To learn more about reCAPTCHA follow the link.

The reCaptcha supports localization. Depending on user’s browser settings, reCaptcha will use the browser default language and allow to change it:

Captcha page customization

To modify footer, header or body of the CAPTCHA use the templates in /usr/share/imunify360-webshield/captcha/templates/.

There are three files:

  • head.tpl – this file goes inside <head></head> tags. So you can add JavaScript, CSS styles, etc.

  • body.tpl – the main template file, modify it as you wish. CAPTCHA goes above all the layers.

  • static – here you can place images, CSS, JavaScript, etc. and access these files as /static/<filename>.

To find information on supported browsers follow this link https://support.google.com/recaptcha/answer/6223828.

Update Captcha localizations

Note

Custom Captcha localization is available starting from Imunify360 version 2.6.0 and later.

A user can change the text of captcha messages for the supported languages. Note that adding custom language is not supported.

To change the text of the Imunify360 Captcha and update the localizations text, please do the following:

  1. Locate appropriate Captcha localization files by running:

    ls /usr/share/imunify360-webshield/captcha/translations/locale/{lang}/LC_MESSAGES/messages.po
    For example for Polish language the catalog looks like this: 
    /usr/share/imunify360-webshield/captcha/translations/locale/pl/LC_MESSAGES/messages.po

  2. Update Captcha localization files by editing msgstr "my customization or translation" for appropriate msgid “original plain english text".

    Where msgstr contains text that is shown to user and msgid contains Captcha original English text.

    For example:

    #: templates/index.html:154
msgid ""
"We have noticed an unusual activity from your <b>IP {client_ip}</b> and "
"blocked access to this website."
msgstr ""
"Zauważyliśmy nietypową aktywność związaną z twoim adresem <b>IP "
"{client_ip}</b> i zablokowaliśmy dostęp do tej strony internetowej"

  3. To add Polish translation edit text in the msgstr field. To change the text for a default English translation, edit text in the msgid field.

  4. Save files.

  5. When translation in messages.po files is finished, restart imunify360-webshield service:

service imunify360-webshield restart
6. Block yourself (remove your IP from Imunify360 White List and try to log in to the server via ssh with wrong password until it blocks you). Then go to website and log in. Captcha should appear. Set Polish language and assert that new text is displayed.

Changing the default keys to Google reCAPTCHA keys

If a server owner has his own Google reCAPTCHA keys (both private and public), he may use them instead of the default CloudLinux keys.

To set Google reCAPTCHA keys, do the following:

  1. In the /etc/imunify360-webshield/virtserver.conf file find the set $captcha_key line

  2. Replace the provided key with your own public key, for example:

    location @to_captcha {
...
set $captcha_key YOUR_OWN_PUBLIC_KEY;
content_by_lua_file lua/captcha.lua;
}

    Note

    Pay attention to semicolon at the end of the line.

  3. Then go to the /etc/imunify360-webshield/webshield.conf file and uncomment the captcha_custom_secret_key directive

  4. Place your private key into it, for example:

    # Uncomment the following line if you have your own google recaptcha key and want to use it
captcha_custom_secret_key YOUR_SECRET_KEY;

  5. Reload WebShield

CDN Support 3.8+

Starting from version 3.8 Imunify360 correctly graylists and blocks IPs behind Cloudflare and other CDNs (see here for the full list).

Imunify360 passes all requests from CDN through WebShield, and uses CF-Connecting-IP and X-Forwarded-For headers to identify real IPs.

The feature is disabled by default in Imunify360 version 3.8 but will be enabled in the future versions.

To enable it now, add the following section to the Imunify360 config file (/etc/sysconfig/imunify360/imunify360.config):

WEBSHIELD:
 known_proxies_support: true
And restart WebShield For EL6: 
service imunify360-webshield restart
For other systems: 
systemctl restart imunify360-webshield

Note

If you are using cPanel/EasyApache3, Imunify360 will not automatically deploy mod_remoteip, and log files will show local server IP for visitors coming from CDN. EasyApache 3 is EOL in December 2018, and we don't plan to add automated mod_remoteip setup and configuration for it.

Note

For cPanel/EasyApache 4, Plesk, DirectAdmin and LiteSpeed mod_remoteip will be automatically installed and configured.

Supported CDN providers:

  • Cloudflare
  • MaxCDN
  • StackPath CDN
  • KeyCDN
  • Dartspeed.com
  • QUIC.cloud CDN
  • NuCDN
  • Google CDN
  • CloudFront CDN
  • GoCache CDN
  • Opera
  • QUANTIL
  • QUIC.cloud CDN
  • BunnyCDN
  • Sucuri WAF

SplashScreen for Chinese customers

Imunify360 Captcha isn't available in some countries due to certain restrictions, for example, in China. To alleviate this, Chinese customers can use Imunify360 SplashScreen as Captcha.

To enable SplashScreen, add the following line:

wscheck_splashscreen_as_captcha= on

to the /etc/imunify360-webshield/webshield-http.conf.d/wscheck.conf and run the following command.

For Ubuntu:

service imunify360-websheld reload

For CentOS:

systemctl reload imunify360-webshield

The graylisted visitors will see such screen for 5 seconds before redirecting to their initial destination.

How to block attacks from a particular country in WebShield

Note

Imunify360 4.3+

By default, country traffic blocking is not applied to the requests that come via a legitimate proxy such as Cloudflare. Even if the country is blocked in settings. Starting from Imunify360 version 4.3, we introduce a new way of country traffic blocking.

  1. Add those countries to the /etc/imunify360-webshield/blocked_country_codes.conf file. For example:
CH 1;
RU 1;
2. Then reload WebShield with the following command: 
systemctl reload imunify360-webshield

It will block traffic from those countries no matter if it goes via known proxies or directly.

Note

You can find WebShield and Captcha related logs in the /var/log/imunify360-webshield/ file.

Edit this page
We are Cloudlinux
2020. CloudLinux Inc
How to
Getting started
Contact support
Blog