Allowlists
3 min read
Pro adds explicit allowlists for Card-Testing Defense — surfaces for telling TrustLens “this fingerprint or this IP range is known-good, don’t apply velocity rules to it.” Allowlists complement the VIP customer bypass: VIP bypass is automatic per-customer, while allowlists are explicit per-device or per-network. This page covers both fingerprint allowlists and IP CIDR allowlists, including per-fingerprint threshold overrides.
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 make many sequential requests.
- Internal tools. Subscription renewals, admin-side order creation, custom scripts.
- Known-good monitoring traffic. Uptime checkers, synthetic transaction monitors.
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 at TrustLens → Card-Testing Defense → Allowlists → Fingerprints. Stores explicit fingerprint hashes that should bypass velocity rules entirely.
Adding a Fingerprint #
- Find the fingerprint hash in the Card Testing event log or Attack History tab (top-attacking fingerprints often turn out to be legitimate QA bots)
- Copy the hash
- Open the allowlist UI and click “Add Fingerprint”
- Paste the hash, add an optional label (e.g. “QA bot — automated tests”), and save
Behavior #
- Allowlisted fingerprints skip velocity checks
- They’re not subject to per-fingerprint lockouts
- They’re still recorded in the event log for auditing
- They do contribute to the auto-escalation distinct-fingerprint count? — No. Allowlisted fingerprints are excluded from auto-escalation counters.
Limits #
No hard limit on number of fingerprints. Each entry is one row in a database table — performance is fine into the thousands. Keep the list reviewed; orphaned QA fingerprints from years ago should be removed periodically.
IP CIDR Allowlist #
Located at TrustLens → Card-Testing Defense → Allowlists → IP Ranges. Stores IPv4 and IPv6 CIDR ranges that should bypass velocity rules.
Format #
| Example | Meaning |
|---|---|
192.0.2.42/32 |
Single IPv4 address |
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/128 |
Single IPv6 address |
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 proxy, configure TrustLens to use the forwarded client IP instead.
- 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 adds per-fingerprint overrides. Located in the same allowlists UI.
| 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 preserve the velocity tracking — you still see counts and events — but with custom thresholds. This 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 Card-Testing checks:
- VIP customer bypass (if enabled and customer is VIP) — skip all checks
- IP CIDR allowlist — skip velocity checks
- Fingerprint allowlist — skip velocity checks
- Per-fingerprint override — apply custom thresholds
- Standard velocity rules — apply defaults
The first match wins. A customer who is both VIP and on the IP allowlist gets bypassed via the VIP path; the IP allowlist isn’t consulted.
Audit Trail #
Every allowlist match is recorded in the event log with the allowlist source (IP / fingerprint / override) and the entry label. This makes it easy to audit:
- Whether allowlists are being hit (validating they’re configured correctly)
- Whether allowlists are being abused (a once-legitimate fingerprint now showing attack patterns)
- Operational health of integration partners
Removing Entries #
Entries can be removed at any time. When removed, the next request from that fingerprint or IP is subject to normal velocity rules. Existing velocity counters for the fingerprint aren’t reset — if a partner had been hammering counters under bypass, removing the allowlist 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 UI submissions are nonce-protected and capability-checked. Allowlist changes are logged in the WordPress action log for audit purposes.
