Guide for the Bot Blocker Extension for Magento

Magefan Bot Blocker for Magento 2 protects your store from any kind of bot traffic, search spam, DDoS attacks, and suspicious server requests to save your server resources and improve user experiences.

It combines multiple features like automatic rate limiting, IP whitelisting/blacklisting, user agent blocking, country blocking, bot page restrictions, reCAPTCHA verification and detailed traffic reports to help you block bot traffic.

In this guide, you'll learn how to configure every bot protection feature of this extension, enable CAPTCHA verification, and get notifications whenever your store is under bot attack.

Installation and Updates

Navigate to your Magefan account and the Magefan extensions management guide to learn how to install Bot Blocker for Magento 2.

General Settings

Navigate to Stores > Configuration > Magefan Extensions > Bot Blocker to configure the extension.

The extension comes with some general settings that apply across the entire extension.

• Enable Bots Blocker — turns the extension on or off.
• Init Point — a read-only confirmation that the extension's early-load hook has been added to pub/index.php. This ensures blocking rules run before Magento starts processing the request.
• Trusted Proxy IP Header — tells the bot blocker which intermediate servers (e.g., NGINX, Cloudflare, or CDN) are allowed to report the true client IP in HTTP headers. You can enter multiple headers separated by commas, e.g. HTTP_CF_CONNECTING_IP,HTTP_X_REAL_IP.

Leave blank to rely on REMOTE_ADDR only, which is recommended if your store isn't behind a proxy or CDN. If it is, set this to the $_SERVER key your infrastructure uses to pass the real visitor IP.

• Notification Email and Email Sender — define a list of addresses that receive DDoS alerts and auto reCAPTCHA notifications. and a sender of those notifications correspondingly.

If left blank, the General contact email is used for notification email.

DDoS Protection

DDoS section settings allow you to automatically block IPs that send too many requests in a specified short time.

• Action When Limit Is Reached — defines what happens when a certain IP crosses a certain number of requests: 

1. Send Email Notification (with ability to block via email) — you receive a notification about a malicious IP and decide whether to block it via email.
2. Block Immediately — the IP is blocked immediately.
3. Block Immediately and Notify via Email — the IP is blocked immediately and you're notified about it via email.
4. Require reCAPTCHA — requires CAPTCHA verification.

• Max Requests per IP — defines the number of requests a single IP can send within the Monitoring Window before the configured action (above) is triggered.
• Subnet Block Threshold (× IP limit) — specifies how many times higher the combined request limit is for an entire /24 subnet compared to a single IP. This catches distributed attacks that spread requests across several IPs.

• Monitoring Window (seconds) — defines the time window used to count requests. The minimum allowed value is 300 seconds, which amounts to 5 minutes.
• Block Duration (seconds) — specifies how long a temporary block stays active once a certain IP exceeds the max requests limit. Default value is 3600 seconds, which amounts to 1 hour.
• Request Log Retention (days) — defines the lifetime of the request log data in the Traffic Monitor before cron automatically removes older entries.

Access Lists

This section allows you to control which IPs and user agents to block or allow.

Blacklist/whitelist IPs

• Allowed IPs — defines IP addresses or CIDR ranges that are never blocked on your store. Use this for trusted partners, internal tools or remote offices.
• Blocked IPs — defines IP addresses or CIDR ranges that are permanently blocked from accessing your store.

Block/allow user agents

• Allowed User-Agents — defines user agents that bypass every bot blocking rule, including DDoS protection and URL restrictions (configured below). 

• Blocked User-Agents — defines user agents that should always be blocked.

Both settings support regular expressions and exact strings.

Country Blocking

Here you can restrict store access from entire countries using Geo IP detection. 

The extension comes with two Geo IP databases to ensure proper tracking and a location simulator that allows you to test the blocking without VPN.

• Enable Country Blocking — turns geo-blocking on or off.
• Blocked Countries — selects countries whose visitors should be blocked from accessing your store.

Bot Page Restrictions

This section allows you to block unnecessary URL generation (e.g. filtered category or search URLs) by specific bots trying to request specific pages, independently of DDoS protection.

The extension returns 410 Gone response for specified bots and keeps your store fully accessible for real visitors and trusted crawlers.

Bot user-agents

This defines regex patterns to be treated as bots for page restrictions. 

This list is independent from the global Allowed User-Agents list (Access List section) since an allowed user agent can still be restricted from accessing these specific pages.

Restricted URL patterns

This defines regex or plain-text patterns matched against the REQUEST_URL. Matching bots will receive a 410 Gone response while trying to access these URLs.

Bad Request Blocker

These settings detect and block requests that match known exploit and scanner patterns, before they reach Magento.

Once you enable the bad request blocker, it checks the banned body patterns against POST and PUT request bodies only, and banned URL patterns against the request URL for all HTTP methods.

• Email Notification — if set to Yes, sends an hourly email summary whenever new bad requests are blocked (at most one notification per hour).
• Notification Email Template — defines the template of the bad requests blocked email send by the extension.

Banned body patterns

Here you define patterns checked against POST/PUT bodies. Plain text is matched as a case-insensitive substring. Wrap a pattern in / delimiters to use it as a regular expression, e.g. /eval\s*\(/i. 

The default list already blocks common template-injection calls, dangerous PHP functions (eval, exec, shell_exec, phpinfo, etc.), shell commands like wget/rm -rf, inline <script> injections, and base64/atob payloads. 

Banned URL patterns

Here you define patterns checked against the request URL for every HTTP method, using the same substring/regex rules.

The default pattern blocks common scanner targets such as .env, .git, .htaccess, /wp-admin, /wp-login, xmlrpc.php, phpinfo and XDEBUG_SESSION. 

Search Filter

This section prevents bots from using search and generating thousands of spam search result pages. Default settings already block most common bot-generated search queries.

• Keywords — defines search queries that are blocked. Add any keywords you see repeatedly hitting your /catalogsearch/ paths in the Traffic Monitor.

reCAPTCHA

Magefan Bot Blocker allows you to enable CAPTCHA challenges for suspected bots with a verification step instead of blocking them instantly.

Keys

In this section, you configure the preferred CAPTCHA method. This is required if you want to require reCAPTCHA as a DDoS Protection action or if you want to enable Wholesite reCAPTCHA Mode for the entire site instantly or automatically. 

• CAPTCHA Provider — choose between Google reCAPTCHA v2 (the "I'm not a robot" checkbox) or Cloudflare Turnstile (a privacy-friendly alternative).
• Site Key and Secret Key — settings used to authorise using a corresponding CAPTCHA mode on your store. You generate these while registering a Google reCAPTCHA or Cloudflare services. 

• Verification Passphrase — auto-generated the first time you save the configuration. You can override it with your own value if needed.

Wholesite reCAPTCHA

In this section you define whether you want to use reCAPTCHA for the entire website and how to use it.

• Mode — controls when the CAPTCHA challenge is enabled on your entire website:

1. Disabled —  the CAPTCHA is always off.
2. Always On — every visitor sees a verification challenge.
3. Auto (enable on high load) — the CAPTCHA challenge activates automatically once CPU usage or request rate crosses the configured thresholds (described below), then deactivates again once traffic returns to normal.

• Email Notification — defines when you are notified about the CAPTCHA if you use the Auto mode: when reCAPTCHA is Both (Enabled and Disabled), Only When Enabled, or never (Don't send).
• Notify After — only sends the "reCAPTCHA enabled" email once the challenge has stayed continuously active for this long (e.g. After 5 Minutes). This avoids inbox spam from brief traffic spikes.

• CPU Threshold (%) — activates reCAPTCHA in Auto mode once average CPU load exceeds this percentage.
• Requests / Minute Threshold — activates reCAPTCHA in Auto mode once total requests in the last minute exceed this value.
• Excluded URL Patterns — defines what matching requests should always bypass the CAPTCHA challenge. Use this for API and webhook endpoints that can't solve a CAPTCHA, such as payment IPN callbacks.

Verification Page Appearance

Here you can configure the page visitors see when they're asked to complete a CAPTCHA challenge.

• Show Logo — displays your store logo above the heading on the verification page.
• HTML Language Code — sets the language used in the page <html lang="..."> attribute.
• Page Title — the heading shown on the verification page.
• Page Description — the text shown below the heading, explaining why verification is required.
• Button Text — the label on the submit button. 
• Error Heading — the text shown above error messages if verification fails.

Traffic Monitor and Reports

Once the Magefan Bot Blocker starts blocking bots and malicious requests you can review exactly what's hitting your store from the Traffic Monitor dashboard. Navigate to System > Bot Blocker > Traffic Monitor to open it.

Dashboard overview

At the top of the page, you can find five summary cards that give you an overview of your store traffic:

• Temporarily Blocked — IPs blocked temporarily.
• Unique IPs — the number of unique IPs seen within a selected chart date range.
• Total Requests — the total number of requests logged in a selected range.
• Permanently Blocked — IPs blocked permanently, through a blocking rule (e.g. DDoS protection) or manually (e.g. via IP overview panel, Access Lists).
• Permanently Allowed — IPs on your permanent allow list.

Charts

The traffics monitor section shows the extended charts section covering different traffic trends:

• Requests per Hour — total request volume, with a selectable interval (1m, 5m, 10m, 30m, 1h) so you can detect bot traffic spikes.
• Server Load per Hour — average CPU usage over the same intervals. This allows you to correlate traffic spikes with server load.
• Top User Agents — the user agents generating the most requests.

• Top Countries — the countries sending the most requests.
• Top Paths — the most-requested URLs on your store. This helps to identify pages hit with unusual request volume.
• Top IPs — individual IPs generating the most requests, with their location.
• Top /24 Subnets and Top /16 Subnets — request volume grouped by subnet range.

IP Overview grid

Below the traffic and request charts in the Magefan Traffic Monitor there is a tabbed grid with the full request history. It allows you to review and take action on any IP, country or user agent:

• IP Overview — every unique IP seen in the logs, with the following data:

• Temp Blocked — IPs under a temporary block, with the remaining block duration.
• Perm Blocked — IPs, countries and user agents permanently blocked, either manually or by a rule with an Unblock option.
• Blocked Bad Requests — requests and IPs denied by the Bad Request Blocker.
• Raw Log — the unfiltered request log, useful for investigating a specific IP or path in detail.

Grid actions

Except for viewing the IP data in the  overview grid, you can take different actions for a specific IP, its country, or its user agent, in the Actions column  or perform these actions for multiple IPs (raws) via the mass actions:

• View in Raw Log — see the IP's full request history.
• Block IP Permanently / Temporarily — add the IP to blocked IPs, or apply a temporary block using your configured block duration.
• Unblock IP / Allow IP — remove an existing block, or add the IP to allowed IPs so it's never blocked again.
• Block Country Permanently or Temporarily / Unblock Country — apply or remove a block for the IP's entire country.
• Block User Agent Permanently or Temporarily / Unblock User Agent — add or remove a user agent from the Blocked User-Agents list.