Geo Diversity
4 min read
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 pattern of declining fingerprints looks 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 hit velocity thresholds 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
- An email blast goes out and email clients prefetch checkout links
In these cases the velocity counters genuinely cross thresholds — but the customers behind those fingerprints are real, geographically diverse, and shouldn’t be locked out.
The Check #
Before auto-escalation fires, the safeguard looks at the contributing fingerprints and asks: are these distributed across many countries, with no single country dominating?
| Condition | Default | Verdict |
|---|---|---|
| Distinct countries among declining fingerprints | ≥ 10 | Looks distributed |
| Single-country share of declines | < 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 countries, or one country dominating), the pattern looks more like a botnet operating from a concentrated set of compromised hosts, and auto-escalation proceeds.
Why These Specific Thresholds #
The 10-country and 50%-single-country defaults were chosen against observed attack and legitimate-burst patterns:
- Attack patterns: Botnets typically operate from a concentrated geographic footprint — even when “global,” they cluster in regions with the most compromised hosts (often Eastern Europe, parts of Asia). Real-world distributed attacks see 1–5 dominant countries representing 80%+ of attacking IPs.
- Legitimate viral / flash-sale patterns: Customer-driven traffic spikes are organically diverse — your customer base lives where it lives. A US-focused store will see most legitimate decline traffic from the US, so the 50% single-country threshold is calibrated to that reality.
The thresholds intentionally favor false negatives (occasionally letting an attack through) 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 #
Settings: TrustLens → Settings → Modules → Card Testing → Auto-Escalation.
| Setting | Default | Description |
|---|---|---|
| Geo-diversity safeguard | On | Master toggle |
| Minimum distinct countries | 10 | Below this, attack pattern is suspected |
| Max single-country share | 50% | Above this, one country dominates → attack pattern suspected |
How Country Is Determined #
Country detection runs against the IP address of each declining request. TrustLens uses WordPress’s GeoIP integration if available (WooCommerce’s MaxMind data, for example), or falls back to network-aware regional inference. If neither is available, the safeguard defaults to “country unknown” and the request doesn’t contribute to the diversity check.
If you’re seeing the safeguard fire when it shouldn’t, check whether your store has a working GeoIP source — without one, every request looks like “unknown” and the diversity check degrades.
When to Tune the Safeguard #
| Situation | Adjustment |
|---|---|
| Auto-escalation fired during a legitimate viral spike | Lower min countries to 7 or raise max single-country share to 60% |
| Attack slipped through because it was geographically distributed | Raise min countries to 12 or lower max single-country share to 40% |
| Your store sells in a single country only | Consider lowering min countries significantly (3–5), since most of your legitimate traffic will be domestic |
| Your store is truly global | Defaults are fine; even attacks tend to be more concentrated than 10 countries |
Turning the Safeguard Off #
The safeguard can be disabled. When off:
- Auto-escalation fires whenever the fingerprint threshold is hit, regardless of geography
- You’re more exposed to false-positive freezes during legitimate spikes
- You’re more aggressively protected against attacks
Disabling makes sense only if you’ve observed real false-negative attacks slipping through the safeguard. For most stores, leave it on.
Logging #
Every safeguard decision is logged with:
- Trigger time
- Number of contributing fingerprints
- Country distribution
- Single-country dominance percentage
- Verdict (escalated / safeguard blocked)
Reviewing these logs after a suspected attack tells you whether the safeguard helped or hurt — useful for post-incident tuning.
