Cloudflare Docs
Cloudflare Zero Trust
Edit this page on GitHub
Set theme to dark (⇧+D)

Lists

With Cloudflare Zero Trust, you can create lists of URLs, hostnames, or other entries to reference when creating Gateway policies or Access policies. This allows you to quickly create rules that match and take actions against several items at once.

Before creating a list, make note of the limitations.

​​ List types

Lists can contain a single type of data each. Supported data types include:

  • URLs
  • Hostnames
  • Serial numbers
  • User email addresses
  • IP addresses
  • Device ID numbers

​​ Create a list from a CSV file

Here is a sample CSV file of URLs that you can use for testing. When formatting the CSV:

  • Each line should be a single entry.
  • Trailing whitespaces are not allowed.
  • CRLF (Windows) and LF (Unix) line endings are valid.

To upload the list to Zero Trust:

  1. In Zero Trust, go to My Team > Lists.
  2. Select Upload CSV.
  3. Next, specify a List name, enter an optional description, and choose a List type.
  4. Drag and drop a file into the CSV file window, or select a file.
  5. Select Create.

You can now use this list in the policy builder by choosing the in list operator.

​​ Create a list manually

  1. In Zero Trust, go to My Team > Lists.
  2. Select Create manual list.
  3. Next, specify a List name, enter an optional description, and choose a List type.
  4. Enter your list element manually into the Add entry field and select Add.
  5. Select Save.
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/lists \
--header 'Content-Type: application/json' \
--header 'X-Auth-Email: <EMAIL>' \
--header 'X-Auth-Key: <API_KEY>' \
--data '{
"description": "Private application IPs",
"items": [{"value": "10.226.0.177/32"},{"value": "10.226.1.177/32"}],
"name": "Corporate IP list",
"type": "IP"
}'

You can now use this list in the policy builder by choosing the in list operator.

​​ Edit a list

  1. In the Lists page, locate the list you want to edit.

  2. Select Edit. This will allow you to:

    • Edit list name and description by selecting on the three-dots menu to the right of your list’s name.
    • Delete the list by selecting the three-dots menu to the right of your list’s name.
    • Delete individual entries.
    • Manually add entries to your list.
  3. Once you have edited your list, select Save.

​​ Limitations

​​ List size

Your lists can include up to 1,000 entries for Standard plans and 5,000 for Enterprise plans. An uploaded CSV file must be smaller than 2 MB.

​​ Duplicate entries

Lists cannot have duplicate entries. Because hostnames are converted to Punycode, multiple list entries that convert to the same string will count as duplicates. For example, éxàmple.com converts to xn—xmple-rqa5d.com, so including both éxàmple.com and xn—xmple-rqa5d.com in a list will result in an error.

​​ URL slashes

Gateway ignores trailing forward slashes (/) in URLs. For example, https://example.com and https://example.com/ will count as the same URL and may return a duplicate error.

​​ Extended email addresses

Extended email addresses (also known as plus addresses) are variants of an existing email address with + or . modifiers. Many email providers, such as Gmail and Outlook, deliver emails intended for an extended address to its original address. For example, providers will deliver emails sent to contact+123@example.com or con.tact@example.com to contact@example.com.

By default, Gateway will either filter only exact matches or all extended variants depending on the type of policy and action used:

DNS policies
ActionBehavior
AllowMatch exact address only
BlockMatch exact address and all variants
OverrideMatch exact address and all variants
Safe SearchMatch exact address and all variants
YouTube RestrictedMatch exact address and all variants
Network policies
ActionBehavior
AllowMatch exact address only
Audit SSHMatch exact address and all variants
BlockMatch exact address and all variants
Network OverrideMatch exact address only
HTTP policies
ActionBehavior
AllowMatch exact address only
BlockMatch exact address and all variants
Do Not InspectMatch exact address only
Do Not IsolateMatch exact address only
Do Not ScanMatch exact address only
IsolateMatch exact address and all variants
Other policies
Policy typeBehavior
Egress policyMatch exact address only
Resolver policyMatch exact address only

To force Gateway to match all email address variants, go to Settings > Network > Firewall and turn on Match extended email addresses. This setting applies to all firewall, egress, and resolver policies.