---
title: Geo Diversity
description: "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…"
url: "https://webstepper.io/docs/trustlens/card-testing-defense/geo-diversity/"
updated: "2026-10-18"
category: Card Testing Defense
---

# 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.