Bot & Country Blocker for PrestaShop

Overview

Stop AI crawlers, scrapers, vulnerability scanners and unwanted countries before PrestaShop builds a page. Every storefront request is checked right after PrestaShop resolves the page and reads its cookie, from a compiled rule file, so a normal visitor costs no extra database query and a blocked bot never reaches the page code. Googlebot and Bingbot are verified by DNS and always allowed, so your search rankings are safe.

It starts in learning mode: rules only write "would block" entries to the log, so you see what would happen before anything is blocked.

Key features

• Countries: block, challenge, redirect or close only the checkout for selected countries, or for every country except the selected ones. Free DB-IP Lite country and network databases in one click (no account), MaxMind GeoLite2 with a free key, or upload your own .mmdb; Cloudflare's CF-IPCountry header is used when the request comes through Cloudflare. IPv4 and IPv6.
• IP addresses and networks: single IPs, CIDR ranges, ranges, IPv6, public list URLs refreshed daily, AS numbers and a preset of 50+ hosting, cloud and server providers.
• Built-in bot list with one switch per bot: 50+ AI training crawlers (GPTBot, ClaudeBot, CCBot, Bytespider, meta-externalagent, Amazonbot and more), AI assistants and AI search, SEO crawlers, scripts and HTTP libraries, headless browsers and vulnerability scanners.
• Search engines stay safe: Googlebot, Bingbot, Applebot, YandexBot and Baiduspider are verified by reverse and forward DNS and allowed before any rule runs; impostors are blocked.
• Rate limits per IP address for the whole store, for search and faceted filters, and for the account and contact forms (fake registrations, password reset and contact spam), with an optional temporary ban.
• Honeypot paths (/wp-login.php, /.env, /xmlrpc.php and more) that ban scanners, and the add to cart flood fix: cart and wish list calls without the PrestaShop cookie every browser has (bots that create thousands of carts and guest rows).
• Empty user agents and browser impostors (a browser user agent without the Accept-Language header every browser sends).
• Actions per rule: block (styled, editable 403 page), challenge (a one-second JavaScript proof of work: no captcha, no third-party service), redirect, checkout only, allow, log only.
• Dashboard, log and CSV export: decisions per day, top countries, bots, rules and IP addresses, filters, a reference on the block page your customers can quote, retention.
• Tools: IP tester with a decision trace, Cloudflare WAF expressions for the same rules at the edge, AI crawler group for robots.txt, bans and administrator IP addresses.
• You cannot lock yourself out: administrator IP addresses are allowed automatically, signed-in customers are never blocked (option), the web service, payment module callbacks and the back office are never checked, and an emergency file switches everything off.
• Cache safe: block and challenge answers are sent with Cache-Control: no-store and X-LiteSpeed-Cache-Control: no-cache; clean pages are left untouched (no cookie, no header), so a page cache never stores a block page.
• Clean install: two hooks (actionDispatcherBefore, displayBackOfficeHeader), no overrides, no core or theme file changes.

Compatibility

• PrestaShop 8.2.0 – 9.x, one module for both (tested on 8.2.8 and 9.2.0).
• PHP 7.2.5 or newer (PrestaShop 9 needs PHP 8.1+). APCu is used for rate limits when the server has it.
• Any theme (Classic, Hummingbird, custom): the module adds no storefront markup; its block, challenge and checkout pages are self-contained. Standard and one-page checkout. Multistore: one rule set for all shops.

Installation

Requirements

• PrestaShop 8.2.0 – 9.x
• PHP 7.2.5 or newer (PrestaShop 9: PHP 8.1+), allow_url_fopen or outbound HTTPS for the database and list downloads
• About 20 MB free in the var/ folder for the GeoIP databases

Install

1. Modules > Module Manager > Upload a module: upload kvbotcountryblocker-1.0.0.zip (or the zip from PrestaShop Addons). PrestaShop installs it.
2. Click Configure, or open Advanced Parameters > Bot & Country Blocker.
3. On the dashboard click Download now to install the free DB-IP Lite country and network databases. Skip it if you only use bot rules, or if your store is behind Cloudflare.
4. Recommended: add the cron URL from Tools > Maintenance to your hosting's cron jobs once a day, for example wget -q -O /dev/null "<cron URL>" (or use the Cron tasks manager module). Without it, light maintenance runs once an hour while an administrator uses the back office.

Only for the own-site edition: enter your license key under Settings > License. The module works for 14 days without a key.

After installing

The module starts in learning mode with ten ready-made rules: scanner paths, fake search engine bots, empty user agents, the built-in bot list, the add to cart flood fix, browser impostors, three rate limits (search and filters, account and contact forms, whole store) and a disabled hosting-network rule. Look at the Log for a few days, adjust the rules, then click Switch protection on in the header.

The menu entry Bot & Country Blocker is added under Advanced Parameters. Employees need the view permission on it to see the pages and the edit permission to change anything (Advanced Parameters > Team > Permissions).

Where the data lives

• Seven tables PREFIX_kv_bcb_* (rules, bans, administrator IP addresses, DNS cache, rate buckets, log, daily counters) and settings KVBOTCOUNTRYBLOCKER_*.
• The compiled rule file and the GeoIP databases in var/modules/kvbotcountryblocker/ (protected from web access, kept on cache clears and module upgrades).

Updating

Upload the new zip the same way (Module Manager > Upload a module). Rules, settings, the log and the databases are kept; upgrade steps run automatically.

Uninstalling

Module Manager > Bot & Country Blocker > Uninstall removes the settings, the seven tables, the compiled rule file and the downloaded databases, the menu entry and its group from robots.txt if you added it.

Configuration

Open Advanced Parameters > Bot & Country Blocker (or Module Manager > Configure). The header shows the mode (learning or protection) and the GeoIP databases; the tabs are Dashboard, Rules, Bots, Log, Tools and Settings.

Rules

Rules run from top to bottom; the first rule that matches decides. "Log only" rules record and continue. Change the order numbers and click Save order. Add a rule with the buttons at the top:

The built-in rules Fake search engine bots, Empty user agent, Browser impostors and Built-in bot list exist once: switch them on or off and choose their action.

Routes are PrestaShop front controllers (search, cart, order, registration, contact) or module controllers written module/<module>/<controller> (module/blockwishlist/action). module/ps_emailsubscription/* matches every controller of a module; category?q matches only when the q parameter is set (faceted search filters).

Actions

• Block: the block page (HTTP 403) with a reference such as BCB-4F2K.
• Challenge: a browser check that takes about a second (proof of work, no captcha, no third-party service). People pass once and are not asked again for the configured hours; scripts cannot pass.
• Redirect: to a URL or a path.
• Checkout only: the visitor can browse and use the cart; the order page (standard and one-page checkout) and the order validation of payment modules show the checkout restriction page. Use it for countries you cannot ship to.
• Allow: skips all later rules (put it on top for your office or partners).
• Log only: records and continues.

Bots

One switch per bot: Off, Log only, Challenge or Block, and Set all per group. AI assistants (ChatGPT-User, OAI-SearchBot, PerplexityBot and others) are off by default because they fetch pages when a person asks about your products; AI training crawlers are blocked by default. Googlebot, Bingbot, Applebot, YandexBot and Baiduspider are not in the list: they are verified by DNS and always allowed when real.

Settings

• Status and Learning mode.
• Never blocked: signed-in customers, verified search engines, administrator IP addresses (remembered for N days), and your own paths or routes (for example a product feed).
• Block and challenge pages: accent colour, titles and messages (placeholders [store], [ip], [country], [ref]), challenge difficulty, how long a solved challenge is valid.
• IP address and GeoIP: Automatic trusts Cloudflare's CF-Connecting-IP only from Cloudflare edge addresses and your proxy header only from the trusted proxies you list; otherwise the connection address is used, which cannot be forged. Monthly GeoIP update (DB-IP Lite or MaxMind GeoLite2) and the MaxMind account ID and licence key.
• Log: retention in days and maximum rows.
• License (own-site edition): your license key and its status.

Settings are global: in a multistore installation one rule set protects every shop.

Usage

First week: learning mode

After installing, every rule only logs. Open the Log and filter by rule or action; look for real customers among the "would block" entries. Typical adjustments: switch off a rate limit for a busy business customer, allow an integration's user agent, or set an SEO tool you use to Off on the Bots page. Then click Switch protection on.

Dashboard

Blocked and challenged requests, solved challenges, learning-mode hits and today's decisions; a 7, 30 or 90 day chart; top countries, bots, rules and IP addresses. Click an IP address to see its log entries.

When a customer says "I am blocked"

Ask for the reference on the block page (for example BCB-4F2K) and type it in the log filter: you see the rule, the IP address, the country and the user agent. Add an Allow rule for the address on top, or change the rule.

Tools

• Test a visitor: enter an IP address, a user agent and a page (/index.php?controller=search or a friendly URL); the result shows the country, the network and every step of the decision. Nothing is logged or blocked.
• GeoIP databases: download DB-IP Lite or MaxMind GeoLite2, upload a file, remove a database.
• Cloudflare WAF rules: expressions for "Block" and "Managed Challenge" built from your rules, to stop the same bots at the edge, in front of cached pages.
• AI crawlers in robots.txt: add or remove a Disallow: / group for the AI crawlers you block (a backup of robots.txt is kept). When PrestaShop regenerates robots.txt (SEO & URLs), the group is added back.
• Maintenance: last run, run now, the cron URL. Active bans and administrator IP addresses can be removed here.

The pages visitors see

Self-contained pages in your accent colour, light and dark, readable on phones, never cached and marked noindex.

• Block page: title, message, reference and IP address (optional).
• Challenge page: a progress bar; passes on its own in about a second and returns to the page the visitor asked for.
• Checkout restriction page: message, detected country and a "Back to the store" button.

AJAX calls (add to cart and similar) get a JSON answer with status 403 instead of a page.

Emergency switch

If you ever lock yourself out of the storefront, create an empty file var/kvbotcountryblocker.off in the PrestaShop folder (FTP or file manager), or add define('KV_BCB_DISABLED', true); to config/defines_custom.inc.php. The blocker stops at once; delete the file to turn it back on. The back office is never blocked.

FAQ

Will it hurt my Google rankings?

No. Googlebot, Bingbot, Applebot, YandexBot and Baiduspider are verified by reverse and forward DNS (cached for 7 days) and allowed before any rule runs, even before country or rate-limit rules. Fake crawlers that only copy Googlebot's user agent are blocked.

Do I need Cloudflare or a paid GeoIP service?

No. Country and network data come from the free DB-IP Lite databases (no account, CC BY 4.0) or MaxMind GeoLite2 (free account). Both are files on your server, read by the module itself. If your store is behind Cloudflare, its country header is used as well.

How fast is it?

The rules are compiled into one small file read once per request; a clean visitor costs no database query. Country lookups read a few bytes of the database file. Only blocked, challenged or logged requests write a log row.

Does it work with page caches?

Block, challenge and checkout answers are sent with Cache-Control: no-store and X-LiteSpeed-Cache-Control: no-cache, so a cache never stores them, and clean pages get no cookie and no header from the module. Pages that a cache in front of PrestaShop serves (Cloudflare, LiteSpeed, Varnish) never reach PHP: use the Cloudflare export for the edge.

Does it stop fake registrations and contact form spam?

Most spam comes from scripts, hosting networks and a few countries. The bot list, the hosting preset, browser impostors, the form rate limit and country rules stop them before the form is shown. Keep a captcha module if you want a second layer.

Can I close only the checkout for some countries?

Yes: a Country rule with the action Checkout only. Visitors can browse and use the cart; the order page and the order validation of payment modules show the restriction page. It works with the standard and the one-page checkout.

What about my payment provider, the web service and cron?

Payment module callbacks and notifications are never checked (only their order validation step, for "Checkout only"), the PrestaShop web service (/api/) and the back office are never touched. Add your own integrations (feeds, other modules' cron URLs) to the exempt paths in the settings.

Does it work in a multistore installation?

Yes. One rule set, one log and one dashboard protect every shop.

What happens when the license is not active? (own-site edition) After the 14-day start period without a key, rules only log, as in learning mode. The dashboard, rules, log and tools keep working. The PrestaShop Addons edition needs no key.

Which data is stored?

For blocked, challenged or logged requests: time, IP address, country, network, user agent, method, path and the rule. Entries are deleted after the retention period (30 days by default). Clean visitors are not logged.