Test Guidelines

The purpose of this document is to suggest the optimal procedure for testing of the BotGuard service. If you have any comments or questions, we will be happy to discuss them.

Please, use the following contacts for all the communication:

Mislav Oršolić, mislav@botguard.ee
Danica Gallon, danica@botguard.ee

Testing plan

You decide what you will test and when. Just a couple of recommendations: We would like to propose first to perform the functional testing to assure the quality of recognition of bots. Later it will be possible to perform load testing and speed testing to assure scalability of our product. It will require installation of the BotGuard servers in the network where the protected web servers are located.

Testing the Plesk module. Since we do not yet have a sufficiently large experience of operating the Plesk module in production mode, we will be very grateful to you for any comments and suggestions that will allow us to optimize this module and make it comfortable for you to use it.

Functional testing requirements and recommendations

Prerequisites

To prepare for testing, you need to integrate with the BotGuard server in Australia. We already installed a BotGuard node for testing purposes, here is the data you need:

API key:  

Primary server address: 

Secondary server address:

Note:At the testing stage, one server is enough, which can be used as primary and secondary nodes. Once installed in your network, they will of course be different.

After integrating the plugins according to the instructions below, you should add the protected domains to your BotGuard account:

URL: botguard.net

User:

Password:

In the case of hosting panels, this is done automatically. When integrating directly using Apache or Nginx plugins, you must do it manually (or use a script). Normally, if the module works correctly, and some of the domains haven't been added, then the sites will open as usual. At this time, an Apache/ Nginx plugin can add BotGuard API errors to the web server log, but the sites will work fine. You can add and check domains added at https://botguard.net/en/website.

Our recommendations

We highly recommend starting your testing with the web server integrations in a test environment. In order to analyze the protection events and check the functionality of the software, moderate traffic will be much more useful and convenient than a heavy load. We recommend that you avoid starting testing on production servers with a large number of domains. It is best to do this in the next step, right after testing the functionality in some test or limited environment.
In general, we recommend enabling protection categories one by one, checking and then disabling and enabling the next category. With the organic traffic, the most efficient order is the following:
- Nothing is blocked immediately after integration. This is the standard mode to avoid any problems.
- First, enable “deny access” for “content scrapers”. If there are no important errors and time allows you, it is better to leave the system in this state for 24 - 48 hours. The system adapts to your traffic, which is important for the following categories, especially for "security violators”. This will also allow us to check everything on our side.
- Then, disable “content scrapers” and enable “security violators”. Then you can test all the other categories.

Service architecture

The BotGuard service is integrated at the web server level. Each request to the protected website is sent to the closest BotGuard node for analysis (in production mode these servers are normally located on the hosting provider's network). BotGuard determines in real time whether the request is dangerous. The result is sent back to the web server.

We will install a configuration to let you test both our bot protection system and cloud WAF. This requires a short explanation.

BotGuard local cloud protection is built based on several subsystems including the bot protection subsystem and the cloud WAF subsystem, which provide slightly different functionalities. Most importantly, our bot protection subsystem protects against automated threats while WAF protects against security threats. Basically, this means that our bot protection analyzes where a request came from and what kind of software was used to generate it. In this case, the request is blocked if its source appears suspicious or inconsistent. On the contrary, cloud WAF subsystem is fully focused on the request content. It analyzes whether it contains any suspicious code and makes a blocking decision based on that. In terms of testing, the crucial point is that these two protection subsystems may have partially overlapping functionality while working together, which is their standard operation mode. Therefore, in order to avoid distortions of test results, it is necessary to separate these tests.

Enabling the “Security violators” category blocking in the Core protection rules of our Rules editor and disabling all the other categories will give you an option to test a pure WAF.
Quite the opposite, disabling the “Security violators” category blocking in the Core protection rules of our Rules editor end enabling blocking of different bots (the 3 other categories in the same line) will give you an opportunity to test our anti-bot protection.

In this case, you do not need to configure the proxying system and it will be much easier to ensure the quality of testing.

Integration on your side should be performed by your specialists according to the instructions below. We will provide all the necessary technical support.

Integration on your side

API key
Primary BotGuard server URL
Secondary BotGuard server URL

You are welcome to integrate protected web servers using direct Apache server integration, and direct Nginx server integration and Plesk plugin.

Testing web servers for WAF and bot protection separately.
Integrating web servers as close as possible to the traffic entry point. In theory, the service can be integrated deeper, but for the purity of testing it is desirable to avoid this. Integration without using proxying allows us to analyze a much larger number of features and avoid signal distortion.
Integrating at web server level (Nginx or Apache) and not at the particular application level, such as, for example, Content Management Systems, for the same reason.
When using Nginx + Apache bundles, integrating closer to the traffic entry point (i.e. Nginx), for the same reason.

Apache web server integration

This is one of the two most effective back-end integration methods we provide, and we recommend that you test it out.

Debian 10 ("buster"), 9 ("stretch"), 8 ("jessie")
Ubuntu 20.04 ("focal"), 18.04 ("bionic"), 16.04 ("xenial")
RHEL/CentOS 8, 7, 6
CloudLinux 7, 6 (EasyApache)

The integration procedure depends on the type of an operating system used. Our Apache Web Server Integration Manual is available on our website, see

Apache Extension Module Integration Manual

NGINX web server integration

This is the second of the two most effective back-end integration methods we provide, and we recommend that you test it out.

BotGuard provides the integration module for Nginx web server via operating systems package repository. We support the following operating systems:

Debian 10 ("buster"), 9 ("stretch")
Ubuntu 20.04 ("focal"), 18.04 ("bionic"), 16.04 ("xenial")
RHEL/CentOS 8, 7, 6

The integration procedure depends on the type of operating system used. Our Nginx Web Server Integration Manual is available on our website:

NGINX extension module integration manual

This integration method is also relevant for the OpenResty server, as it is based on Nginx.

WHM / cPanel module integration

It makes sense to test this integration method for a different reason. This will allow you to test the front-end integration, which provides access to convenient tools for enabling and disabling protection and billing, Protection Events Log and Protection Rules Editor. This integration is based on the BotGuard Partner API, which is used in all such plugins (cPanel, Plesk, DirectAdmin, WHMCS, ISPmanager etc.) and can also be integrated directly into any proprietary control panel, providing even more functionality.

BotGuard provides a WHM / cPanel integration plugin. When the plugin is installed, the BotGuard Apache web server extension module is installed as a dependency and activated. The control panel provides the appropriate configuration options for the WHM admin and cPanel user.

After installing the plugin, WHM admin must configure the plugin setting basic configuration options, i.e. the BotGuard API Key, primary and secondary BotGuard server addresses. After the plugin is configured, each user of this server will gain access to the website protection settings and the corresponding menu section in the cPanel web control panel.

Our WHM/cPanel Web Server Integration Manual is available on our website, see cPanel integration manual

Of course, in the future, we will offer you server configuration tools to automate this task, but at the stage of testing the core functionality it does not seem necessary.

Plesk module integration

This will allow you to test the front-end integration, which provides access to convenient tools for enabling and disabling protection and billing, Protection Events Log and Protection Rules Editor. This integration is based on the BotGuard Partner API, which is used in all such plugins.

The integration procedure depends on the type of the operating system used. Our Please Integration Manual is available on our website:

Plesk integration manual

What to test with the Bot-Protection System

We will provide a separate pre-configured environment for this set of tests as described above. We recommend using the Apache, Nginx and WHM/cPanel integrations for Bot-Protection testing. In this case, you can also test adding the custom rules, since with WAF disabled they will not distort the test results.

Our Bot Protection Subsystem is aimed to mitigate the following automated web application threats:

Overloading web applications
Scraping
Denial of Inventory
Automatic Account Creation
Scalping
Account Aggregation
Skewing
Sniping
Spamming
Vulnerability scanning

Basically, it blocks requests that are made by suspicious software tools. In this case, it is only important who the visitor is and who made the request. If protection against bots is enabled, the request will be blocked not because its content is dangerous, but because the request was made by an illegal visitor.

Testing Bot Protection System should be aimed at checking the quality of the system distinguishing different types of automated tools. We would recommend using a variety of technologies to check whether the BotGuard system can successfully detect and block them.

We recommend paying attention to the following cases:

Vulnerability scanning. This is typically done with quite simple bots. To test this one can use standard tools like curl requests, programming libraries embedded in popular programming languages like PHP, Python, or Go and check whether such requests are blocked. In addition, any scanner can be used for such testing.
Overloading web applications. For a basic test one can use the same simple tools configured to generate 50 - 100 requests per second to the web application form. Any product search form for an e-commerce application can be used.
Spamming, fake sign-ups. Any popular spambot tool can be used.
Brute-force and dictionary credential attacks. Any popular tools like ncrack or hydra or medusa can be used. Scraping. There are a lot of cloud scraping services on the web, most of them more or less the same, that can be used for such testing. Among the most popular of them:
- https://www.scrapinghub.com/scrapy-cloud/,
- https://www.octoparse.com
- https://www.dexi.io/
- https://www.outwit.com/
- https://www.scrapingbee.com,
- https://scrapestack.com,
- https://dataflowkit.com.

You can also take some tests by mirroring real traffic from any website. In this case, there are some nuances that must be taken into account when arranging such a mirroring to get objective results. Our specialists would be happy to provide the necessary support based on our experience.

BotGuard: The Official Blog