Lookups

A lookup is a named set loaded from a CSV file at compile time. Rules test membership against it with the in_lookup and not_in_lookup operators — useful for blocklists, allowlists, risky BIN ranges, and known VPN/proxy networks.

The lookups: block

Declare each lookup with a type and a path. CIDR stands for Classless Inter-Domain Routing — the notation for an IP address range.

lookups:
  blocked_merchants:
    type: string_set
    path: sample_lookups/blocked_merchants.csv
  blocked_countries:
    type: string_set
    path: sample_lookups/blocked_countries.csv
  risky_bins:
    type: int_set
    path: sample_lookups/risky_bins.csv
  vpn_ranges:
    type: ipv4_cidr_set
    path: sample_lookups/vpn_ranges.csv

The three lookup types are string_set, int_set, and ipv4_cidr_set.

CSV column names

Each lookup type expects a specific header column in its CSV:

Sample CSV contents

The sample files that ship with the canonical rule set:

value
RU
CN
BR

value
merchant_123
merchant_999

value
411111
555555

cidr
10.0.0.0/8
172.16.0.0/12

Using lookups in rules

Reference a lookup by name with the lookup: key. in_lookup matches members; not_in_lookup matches non-members:

- {field: merchant_id, op: in_lookup, lookup: blocked_merchants}
- {field: country_code, op: not_in_lookup, lookup: blocked_countries}
- {field: merchant_bin, op: in_lookup, lookup: risky_bins}
- {field: ip_address, op: in_lookup, lookup: vpn_ranges}

The field's type should match the lookup type: a string field against a string_set, the integer merchant_bin against an int_set, and the ip_address string against an ipv4_cidr_set.

🚧

Missing lookup files fail the load

Relative paths resolve relative to the rule file's location. If a lookup file is missing or invalid, the rule set fails to load — and a failed load does not replace an already-active hot-reloaded rule set. See Hot Reload for how the active rule set is protected.

Where to go next