Auto Escalation

Auto-escalation is the Pro feature that triggers Panic Freeze automatically when an attack spreads across multiple device fingerprints faster than per-fingerprint lockouts can contain it. It’s the answer to distributed botnet attacks: when one bot trips a lockout, the next bot in the rotation just takes over. Auto-escalation watches for that pattern and freezes the entire checkout until you can intervene.

---

How It Works #

Auto-escalation maintains a separate counter that tracks distinct fingerprints that have hit velocity thresholds within a sliding window. When the counter crosses the trigger threshold, Panic Freeze activates automatically.

Default Setting	Value
Trigger threshold	3 distinct fingerprints
Window	10 minutes
Panic Freeze duration	15 minutes (standard)

So: if 3 different fingerprints all hit velocity lockouts within any 10-minute span, auto-escalation fires. That’s a strong signal of a distributed attack, since legitimate traffic rarely produces 3 simultaneous high-velocity decliners.

---

The Geo-Diversity Safeguard #

Before firing, auto-escalation runs the geo-diversity safeguard to confirm the pattern looks like an attack rather than legitimate viral or flash-sale traffic. See Geo-Diversity Safeguard (Pro) for the full logic. In summary: if the declining fingerprints are spread across ≥10 countries with no single country dominating, the safeguard blocks the escalation.

This prevents the worst-case failure: auto-freezing the store on Black Friday because a viral hit spiked decline counts naturally.

---

What Happens When It Fires #

1. Panic Freeze activates with a 15-minute duration
2. An admin banner shows the freeze with “Auto-escalated” as the trigger
3. Slack and email alerts fire (if configured) with the auto_escalated event type
4. The Card Testing event log records the escalation with the contributing fingerprints
5. The freeze can be cancelled manually like any Panic Freeze

---

Tuning the Threshold #

The 3-fingerprint default is conservative — it triggers on relatively small distributed attacks. Tune up or down depending on your store’s profile:

Threshold	When to Use
2 fingerprints	Very aggressive — recommended only after observed false negatives at default
3 fingerprints (default)	Balanced
5 fingerprints	Loose — recommended if you have high natural decline diversity (e.g. retry-heavy gateway, large geographic customer base)

The window can be adjusted between 5 and 30 minutes; the default of 10 minutes works for most stores.

---

Configuration #

Settings: TrustLens → Settings → Modules → Card Testing → Auto-Escalation.

Setting	Default	Description
Auto-escalation enabled	On	Master toggle
Fingerprint trigger threshold	3	Distinct fingerprints that hit velocity within the window
Window duration	10 minutes	Sliding window for counting fingerprints
Geo-diversity safeguard enabled	On	Block escalation if declines look geographically distributed

---

When Auto-Escalation Won’t Fire #

Even with auto-escalation on, the system won’t fire if:

• Geo-diversity safeguard determines the pattern looks legitimate
• Fewer fingerprints have triggered than the threshold requires
• Panic Freeze is already active (no duplicate freezes)
• Card-Testing Defense module is disabled

---

Alerting #

The auto_escalated event fires Slack and email alerts to all configured recipients. The alert includes:

• Trigger time
• Number of contributing fingerprints
• Top decline codes seen in the window
• Geographic distribution summary
• Direct link to the Card Testing page

This is one of the highest-priority alerts the system produces — if you’re going to wake up for any TrustLens event, this is the one.

---

After the Escalation #

Use the freeze time to:

1. Review the Attack History tab — see the contributing fingerprints, decline codes, hourly chart
2. Check whether the attack continues after the freeze lifts (often it shifts to a different vector)
3. Consider tightening per-fingerprint velocity thresholds if the attack used the slow-paced pattern
4. Document the attack pattern for post-incident review

Auto-escalation is reactive, not preventive. If you’re seeing repeated auto-escalations, the underlying attack pattern is recurring — adjust the per-fingerprint defenses to catch attacks earlier rather than waiting for the distributed signal.

---

Auto-Escalation vs Manual Panic #

Both result in the same Panic Freeze state. The differences:

Aspect	Manual Panic	Auto-Escalation
Trigger	Admin clicks button	System detects distributed attack
Reaction time	Depends on admin presence	Within seconds of pattern detection
Audit reason	Manual / [admin username]	auto-escalation
Geo-diversity safeguard	Doesn’t apply	Required to fire

Best practice: leave auto-escalation on, treat it as a backup. Use manual panic for known-bad situations where you have specific evidence the system hasn’t picked up yet.