Geo Diversity
The Geographic-Diversity Safeguard is the Pro feature that prevents auto-escalation from misfiring on legitimate viral or flash-sale traffic. It runs as a precondition before Panic Freeze auto-activates, checking whether the locked-out fingerprints look like a coordinated attack or like natural customer diversity. This page explains exactly what it checks and why.
The Problem It Solves #
Auto-escalation fires when 3 distinct fingerprints trip velocity lockouts within 10 minutes. Most of the time, that means an attack. But occasionally:
- Black Friday sale launches and thousands of customers hammer checkout, some producing legitimate decline bursts
- A product goes viral on TikTok and traffic spikes 50× in minutes
- A flash promotion drops and customers race to use a limited coupon
In these cases the velocity counters genuinely cross thresholds — but the customers behind those fingerprints are real, geographically diverse, and the whole store shouldn’t be frozen.
The Check #
Before auto-escalation fires, the safeguard looks up the country of the IP address behind each locked-out fingerprint in the window and asks: are these spread across several countries, with no single country dominating?
| Condition | Value | Verdict |
|---|---|---|
| Distinct countries among the locked-out fingerprints | ≥ 3 | Looks distributed |
| Largest single-country share | ≤ 50% | No dominating country |
If both conditions hold, the pattern looks legitimate — likely a viral or flash-sale event — and the safeguard blocks auto-escalation. Panic Freeze does not activate; the individual fingerprint lockouts remain in effect.
If either condition fails (fewer than 3 countries, or one country with more than half), the pattern looks more like a botnet operating from a concentrated set of compromised hosts, and auto-escalation proceeds.
Why These Specific Thresholds #
The safeguard only ever runs at the moment escalation would fire, when the window holds as few as 3 fingerprints — so the country floor has to be 3 for the check to be able to say “natural” at all. A higher floor would make every verdict “attack”.
- Attack patterns: Botnets typically operate from a concentrated geographic footprint — even when “global,” they cluster in regions with the most compromised hosts. Distributed attacks are usually dominated by one or a few countries.
- Legitimate viral / flash-sale patterns: Customer-driven traffic spikes are organically diverse — your customer base lives where it lives.
The safeguard favors false negatives (occasionally letting per-fingerprint lockouts handle an attack without a freeze) over false positives (freezing the store during a legitimate spike). Auto-escalation false positives are much more visible — and costly — than letting per-fingerprint lockouts handle a marginal attack.
Configuration #
The safeguard has no settings in this version. The minimum of 3 countries and the 50% maximum share are fixed, and the safeguard is always on whenever auto-escalation runs (Pro license active and Card-Testing Defense enabled).
How Country Is Determined #
Country detection uses WooCommerce’s geolocation (WC_Geolocation) on the IP address recorded when each fingerprint was locked out. It relies on a local geolocation database, such as WooCommerce’s MaxMind integration; TrustLens doesn’t fall back to an external lookup service. An IP whose country can’t be determined doesn’t contribute to the check.
Without a working geolocation database, every country lookup comes back empty, the safeguard can never call a burst “natural”, and auto-escalation fires whenever its fingerprint threshold is hit. If you want the safeguard to protect flash-sale traffic, make sure WooCommerce geolocation is set up.
When the Safeguard Gets It Wrong #
| Situation | What to do |
|---|---|
| Auto-escalation fired during a legitimate viral spike | Deactivate the freeze; check that WooCommerce geolocation is working; consider loosening the velocity thresholds for the duration of the event |
| Attack slipped through because it was geographically distributed | Engage Panic Freeze manually; tighten the velocity thresholds; set up the Browser Challenge |
| Your store sells in a single country only | Legitimate traffic will rarely span 3 countries, so expect escalations to proceed during spikes |
| Your store is truly global | No action needed; even attacks tend to be more concentrated than your customer base |
Turning the Safeguard Off #
The safeguard can’t be turned off on its own. Without a geolocation database it has no effect, which in practice means auto-escalation fires whenever its fingerprint threshold is hit.
Logging #
Safeguard decisions aren’t logged. When it blocks an escalation, nothing is sent and the per-fingerprint lockouts simply continue; when it lets an escalation through, the Panic Freeze and the auto_escalated alert (if configured) are the record. To review an attack afterwards, use the 24-hour intelligence card and its CSV export on the Card-Testing Defense page.
Updated on October 18, 2026
