Allowlists

Pro adds explicit allowlists for Card-Testing Defense — lists that tell TrustLens “this fingerprint or this IP range is known-good, let it through.” Allowlists complement the VIP customer bypass: VIP bypass is automatic per-customer and covers the velocity rule only, while allowlists are explicit per-device or per-network and skip every checkout check. This page covers both fingerprint allowlists and IP / CIDR allowlists.

---

Why Allowlists Exist #

Some traffic legitimately produces high velocity that velocity rules would otherwise treat as attack:

• QA testing. Your team runs automated checkout tests with various card scenarios. Each run hammers velocity counters.
• Integration partners. Marketplaces, ERP systems, or order-import tools that submit orders through the checkout.
• Internal tools. Custom scripts that place orders through the storefront checkout.
• Known-good monitoring traffic. Synthetic transaction monitors that run test checkouts.

Without allowlists, you’d have to either tune velocity thresholds high enough to never catch these (which weakens defense against real attacks), or accept that these legitimate use cases get periodically locked out.

---

Fingerprint Allowlist #

Located in the Allowlists card on TrustLens → Card-Testing Defense, under Fingerprints. Stores exact fingerprint hashes that should pass the checkout gate.

Adding a Fingerprint #

1. Find the fingerprint hash in the Targeted now list, the 24-hour intelligence card’s top attacking fingerprints, or the CSV export (top-attacking fingerprints sometimes turn out to be legitimate QA bots)
2. Copy the hash
3. In the Allowlists card, paste it into the Fingerprints field
4. Click Add

Entries have no label field — keep a note elsewhere of what each hash belongs to.

Behavior #

• Allowlisted fingerprints pass the Request Gate without any checks — velocity rules, lockouts, Panic Freeze, the Browser Challenge, and the blocked-customer check are all skipped
• Their submissions and declines are still recorded, so they appear in the 24-hour figures and the CSV export
• They never trip a lockout, so they never count toward auto-escalation

The match is on the exact hash the request carries — the browser fingerprint, or the server fingerprint when the browser didn’t send one.

Limits #

No hard limit on number of fingerprints. The list is stored as a single WordPress option and checked on every checkout submission, so keep it short and reviewed; orphaned QA fingerprints from years ago should be removed periodically.

---

IP CIDR Allowlist #

Located in the same card, under IP ranges. Stores IPv4 and IPv6 addresses or CIDR ranges whose checkout requests should pass the gate.

Format #

Example	Meaning
203.0.113.55	Single IPv4 address (stored as /32)
192.0.2.0/24	IPv4 range of 256 addresses
10.0.0.0/8	Large private IPv4 range
2001:db8::/32	IPv6 range
2001:db8::1	Single IPv6 address (stored as /128)

Common Use Cases #

• Office IP ranges where QA and dev work happens
• CI/CD runners that test checkout
• Integration partner static IP ranges
• Internal admin IPs for testing

What Not to Add #

• Cloudflare / CloudFront / proxy IPs. Allowlisting your CDN’s IPs allowlists effectively all traffic, defeating the defense. If you’re behind a trusted proxy, have a developer enable the trustlens/trust_proxy_headers filter so TrustLens uses the forwarded client IP instead of the proxy’s.
• Mobile carrier IPs. Way too broad — would allowlist millions of customers and attackers.
• Country-wide CIDRs. Same issue, too broad.

---

Per-Fingerprint Threshold Overrides #

For fingerprints that need different thresholds rather than full bypass, Pro can apply per-fingerprint overrides.

Override	Example Use
Tighter than default	A specific device you trust less; force 2 declines / 60s
Looser than default	An integration partner; raise to 20 declines / 60s without full bypass

Overrides have no screen in this version, including in the Allowlists card. They are read from the trustlens_card_testing_fp_overrides option — a map of fingerprint hash to threshold values — which a developer can set. Overrides keep the velocity rule in force (counts, lockouts, Panic Freeze) with custom thresholds, which is useful when full bypass is too permissive but you need tolerance for a specific device.

---

How Allowlists Are Evaluated #

At the Request Gate, the evaluation order for a checkout submission is:

1. Users who can manage WooCommerce — skip all checks
2. Fingerprint allowlist, then IP allowlist — skip all checks
3. Browser Challenge, when turned on
4. Card-testing velocity rule: Panic Freeze, then VIP customer bypass, then held-fingerprint check, then thresholds (with any per-fingerprint override applied)
5. Blocked-customer check, when Enable Blocking is on

The first rule that rejects the submission wins. Because the allowlists come first, an allowlisted device passes even during a Panic Freeze and even if the customer is blocked.

---

Audit Trail #

Allowlist matches aren’t recorded separately — there’s no log of which entry let a request through. The allowlisted traffic’s submissions and declines still appear in the 24-hour figures and the CSV export under its fingerprint hash, which is how you can check:

• Whether an allowlisted device is active (validating it’s configured correctly)
• Whether an allowlisted device is producing unusual declines (a once-legitimate fingerprint now showing attack patterns)
• Operational health of integration partners

---

Removing Entries #

Each entry has a Remove button. When removed, the next request from that fingerprint or IP is subject to normal checks. Existing velocity events for the fingerprint aren’t reset — if a partner had been hammering counters under the allowlist, removing it may produce an immediate lockout.

---

Allowlist vs Block List #

TrustLens’s allowlists are for known-good entities. Block lists (the inverse — explicit “always block this” entries) are not a built-in feature; the blocking surface for customers operates at the customer level, not at fingerprint or IP level. If you need IP-level blocking, do it at the web server / firewall layer above WordPress.

---

Security of the Allowlist UI #

Modifying allowlists requires the manage_woocommerce capability. All submissions are nonce-protected and capability-checked. Allowlist changes aren’t logged, so restrict who has shop-manager access.