Cloudflare Email Security integration

The Block senders in Cloudflare Email Security rule response adds each IOC domain a matched rule cites to the blocked senders of your Cloudflare account. Email Security gives mail from a blocked sender a malicious disposition. Entries do not expire: a domain stays blocked until newer IOCs push it out of Have I Been Squatted’s queue or an administrator removes it. The rule decides which alerts trigger the response. Connecting a token alone blocks nothing.

Prerequisites

• A Cloudflare account with Email Security enabled.
• A Cloudflare user who can create account API tokens for that account.
• The network enforcement add-on on the Have I Been Squatted organization, and an organization admin to configure it.

Create an API token

1. In the Cloudflare dashboard, create an account API token for Have I Been Squatted.
2. Give it one permission, Cloud Email Security: Write. Cloudflare has no narrower permission that can add blocked senders.
3. Limit the token to the account that runs Email Security. Copy the token value; Cloudflare shows it once.
4. Copy the Account ID from the account overview page.

Cloudflare has one blocked senders list per account, and the token can change any entry in it. The token cannot be scoped to some entries. Have I Been Squatted therefore limits itself: it changes and removes only entries whose comment carries its own owner tag.

Connect

1. In the app, open Connectors > Cloudflare Email Security.
2. Paste the account ID and the token value.
3. Set IOCs to keep, between 100 and 5,000. The default is 1,000.
4. Select Connect.

Connecting reads the account’s blocked domain entries with the token and counts the entries Have I Been Squatted already holds for your organization. It creates nothing in Cloudflare. The connection is saved only when the read passes. The token is stored server-side and never returned to the browser.

To use a new token, account or number of IOCs, fill in the form again and select Reconnect. Rule responses are kept.

Connection check

Test connection repeats the read and recounts your organization’s entries. It changes nothing. A failing check pauses blocking until a later check passes.

Result	Meaning
Authentication	Cloudflare rejected the token. It may be wrong, expired or rolled.
Permission missing	The token lacks Cloud Email Security: Write for the account.
Not found	The account does not exist for this token, or Email Security is not enabled.
Too many entries	The list holds more than 20,000 domain entries, more than a delivery reads.
Rate limited	Cloudflare throttled the check. Test again in a minute.
Unreachable	Cloudflare timed out or returned an unusable response. Test again later.

Add the response to a rule

1. Create or edit a rule and open the Response tab.
2. Select Add action > Block senders in Cloudflare Email Security.
3. Select the blocked senders destination.
4. Save the rule.

The destination is listed only while the connection’s last check passed. The response needs at least one domain condition in the rule, because only cited domain records produce entries.

What is sent

For each active rule alert that cites domain records, Have I Been Squatted reads every domain entry in the blocked senders list, then for each distinct cited domain, up to 10 per alert:

• No entry for the domain: adds one.
• A Have I Been Squatted entry for your organization: moves it to the head of the queue by rewriting its comment (see the queue).
• An entry of yours that already blocks the domain: leaves it and records the domain as already blocked.

Each added entry is:

Field	Value
pattern	The cited IOC domain
pattern_type	DOMAIN
is_regex	false
expires_at	Not set: the entry never expires
comments	Marks the entry as Have I Been Squatted’s, names your organization’s owner tag

Additions, moves and removals go to Cloudflare as one batch, which Cloudflare applies whole or not at all. Have I Been Squatted then reads the list back and checks each added or moved entry is there with its new comment.

• Only domains from cited domain (permutation) records are sent.
• The monitored domain and its subdomains are never sent.
• Email and canary evidence never produce entries.

Ownership

Every entry Have I Been Squatted adds carries a comment such as:

haveibeensquatted:1;list=haveibeensquatted-<organization id>-iocs;rule=<rule id>;seen=<unix seconds> | IOC blocked by a Have I Been Squatted rule

The comment is the only thing that marks an entry as Have I Been Squatted’s. An entry is your organization’s when the comment starts with haveibeensquatted: and its list is your organization’s owner tag. The organization id is Have I Been Squatted’s identifier for your organization, so several organizations, or several Have I Been Squatted deployments, can share one Cloudflare account without touching each other’s entries. seen is when a rule last cited the domain, in Unix seconds. A response dispatched by hand records dispatch=<dispatch id> in place of the rule.

Leave comments in place. An entry without the prefix is treated as yours: it is never changed or removed, and it does not count toward the cap. Entries with another owner tag are never changed, removed or counted either.

The queue

Entries never expire, because an expiring block could lift just before a malicious domain is used again. Instead, Have I Been Squatted keeps at most the number of IOCs you set, 1,000 by default, as a queue ordered by seen:

• A new domain joins the head of the queue.
• When the queue is full, each new domain removes the least recently cited Have I Been Squatted entry for your organization. An entry whose comment has no readable seen counts as the oldest.
• A domain cited again moves back to the head, so an IOC that rules keep citing is not the one removed. The move rewrites the comment in place, so the domain is never unlisted.

To avoid a settings change on every alert, an entry is moved only when it was last cited more than a day ago, or when it is among the next 100 entries the queue would remove. If the queue is full and every entry in it is cited by the same alert, the remaining domains are left out and the delivery is recorded as failed.

Cloudflare documents no limit on blocked senders, so the default is a conservative 1,000.

What is recorded

Have I Been Squatted stores the account ID, the token, the number of IOCs to keep, the count of your organization’s entries at the last check, and the time and outcome of the last connection check. For each alert and response, it records the delivery status, the domains added, moved to the head, already current, already blocked by an entry of yours, left out, or removed from the tail, and, when a delivery fails, a short error code. The token and Cloudflare response bodies are not stored in delivery records.

Disable and disconnect

Disable stops new entries and keeps the connection and rule responses. A passing connection test turns blocking back on.

Disconnect deletes the stored token and removes the Block senders in Cloudflare Email Security response from every rule, along with those responses’ delivery records.

Neither action deletes entries, and entries do not expire, so they keep blocking. When you no longer want them, delete the blocked sender entries whose comment starts with haveibeensquatted: and names your organization’s owner tag in the Cloudflare dashboard. To revoke access, delete the API token there.

Limits

• Entries block sender domains only. They are not regular expressions.
• A delivery reads at most 20 pages of 1,000 domain entries. A list with more domain entries, yours included, is not changed.
• Cloudflare does not document an entry limit for blocked senders, whether a domain entry also matches its subdomains, or whether it matches the From header or the envelope sender.
• An entry cited again within a day of its last move keeps its place in the queue, unless it is among the next 100 the queue would remove.

Note

Only organization admins can view or change the Cloudflare Email Security connection.