Block bots: URL captcha

You are here:
Estimated reading time: 1 min
In this article
When creating URL captchas for your domain, please exercise extreme caution, particularly with URLs that are utilized by API calls, third-party services, or other automated processes. Implementing a captcha on such URLs may disrupt essential functionality, leading to failed API requests, integration errors, or broken services.

In case bots are creating spam accounts on your website or trying to brute force an access page. You can just use BitNinja’s Browser Integrity Check to block the bots.
If the bots fail the Browser integrity check, their IP will be Challange listed on your account, so they will not bother you anymore.

Enabled and functioning WAF 2.0 module is a pre requirement of this feature!

If you experience any issue with this module please let us know.
You can contact us at info@bitninja.io or via live chat from 7 AM to 7 PM CET.
Or send us a ticket here.

What is Browser Integrity Check (BIC)

The BIC has the same functionality as the CAPTCHA module. It blocks bots and lets through normal users. BIC does this without requiring the users to type or click anything. Users just need to wait for 5 seconds to pass the Browser integrity check and ONLY at the beginning of their session.

In summary:

  • Blocks bots
  • Lets through valid users and allow listed bots
  • No need to do anything (besides waiting for 5s)
  • Users get the BIC page once per session

This is what it looks like:

How to use BIC

From the Dashboard (New)

  1. Navigate to the Firewall menu point and select the URL captcha menu point at the top.
  2. Click on the “+ ADD new custom rule” button
  3. Add a name for the rule for identification at “Rule name”
  4. At the “PATH” text field, add the URI you wish to protect on all domains and on all servers under your account
    You can also use regular expressions e.g.: myform*
  5. Add the domain you wish to protect or add * instead to protect the same path on all domains.
  6. Add a description (Optional but useful in some cases)
  7. Click on the Add Rule button
The URL captcha also accepts GET parameters from version 2.36.0 and above.
E.g.: /index.php?route=account/login

You can later edit the rule from the Dashboard by clicking on the pen icon on the rule.

From CLI (for a specific domain or server)

The URL captcha rule is removed from the agent after it is restarted if it was added via the BitNinja CLI.

You can enable this feature for a specific domain’s specific URI on a specific server by issuing this command:

bitninjacli --module=SslTerminating --add-domainuri --domain=<domain> --uri=<uri>

For example, on example.com’s wp-login page: 

bitninjacli --module=SslTerminating --add-domainuri --domain=example.com --uri=wp-login.php
If there are subdomains, like www.example.com, shop.example.com the command should be
bitninjacli --module=SslTerminating --add-domainuri --domain=*.example.com --uri=wp-login.php

In this case, however, the URL captcha challenge will not take effect on example.com.
In this example, everyone who tries to access the example.com/wp-login page will get the BIC page. And if they are legitimate users, they will be allowed to access the page. If the incoming request is from a bot, they will get blocked and Challange listed.

You can also set BIC to be presented on every domain’s wp-login.php URI: 

bitninjacli --module=SslTerminating --add-domainuri --domain=* --uri=wp-login.php
BETA phase

The CAPTCHA module can handle 20 000-30 000 requests/sec. If the number of requests processed is higher than this, the CAPTCHA module might break meaning legitimate users will be unable to delist their IP address and also bots will not be blocked.

If this happens Turn off the BIC module from the URI and restart BitNinja to fix the issue.
You can restart BitNinaj with the service bitninja restart command
The URL captcha rules can be found in the /var/lib/bitninja/SslTerminating/domainuri.json file on the server locally.

How to disable

From the Dashboard

Click on the trash bin icon on the rule.

From the terminal

To revert the changes a specific domain on a specific URI issue the command below: 

bitninjacli --module=SslTerminating --del-domainuri --domain=<domain> --uri=<uri>

For example: 

bitninjacli --module=SslTerminating --del-domainuri --domain=example.com --uri=wp-login.php

To revert the changes on all domains for a specific URI:

bitninjacli --module=SslTerminating --del-domainuri --domain=* --uri=wp-login.php
Was this article helpful?
It was not helpful
Views: 4155