Cloudflare Integration

Connect Cloudflare’s Web Application Firewall for automated enforcement driven by Response Actions.

Rule pushes are live

Cloudflare retired the legacy Firewall Rules API this integration originally used. WebDecoy has been rebuilt on Cloudflare’s Rulesets API and rule pushes are working again.

One capability is plan-gated rather than code-gated: fingerprint (JA4) rules need Cloudflare Bot Management, which is an Enterprise add-on. See Fingerprint rules need Bot Management below. IP blocks and session clearance do not.

Use the Cloudflare zone check on the Enforcement page to see exactly which of these your zone supports. It creates a harmless canary rule, deletes it, and reports what Cloudflare said.

Prerequisites

• A Cloudflare account
• Your website proxied through Cloudflare
• Either a Cloudflare login you can approve WebDecoy with, or an API token

Connect with Cloudflare (recommended)

You no longer have to mint a token by hand. Go to Integrations → Cloudflare and press Connect with Cloudflare. You approve WebDecoy on Cloudflare’s own consent screen and land back in the app with the integration connected. As the panel puts it: no token to create, no permissions to tick, nothing to paste.

WebDecoy requests exactly these scopes:

Scope	Needed for
zone.read	Listing your zones so you can pick one
firewall-services.write	WAF rule pushes
workers-scripts.write	Uploading the edge sensor Worker
workers-routes.write	Binding the edge sensor to your traffic

There is deliberately no DNS scope. Cloudflare has no OAuth permission that grants read access to DNS records (dns_records.read is rejected at consent; dns.read and dns.write are accepted and then refused by the API), so asking for one only added a scary-looking line to the consent screen and bought nothing. The one thing this costs you is the pre-install proxied check, described under Your zone must be proxied.

If the button is not there, consent is not configured on your instance and the API token path below is the way in.

Connecting by consent on top of an existing API token

Your pasted token is not deleted. WebDecoy stores the OAuth grant alongside it and uses the grant from then on, keeping the token as a fallback: if the grant is later revoked, the integration degrades to what it was rather than to nothing.

The support-relevant consequence is that after connecting by consent, the token’s permissions stop being what determines what works. If a capability disappeared right after someone pressed Connect, look at the scopes above rather than at the token.

One integration per site

A Cloudflare integration belongs to a property (a site), not to your whole organization. Connect a different zone for each site, and switch sites in the header to see or change the one you are working on. An older organization-wide integration keeps working and is used by any site that does not have its own.

Creating a Cloudflare API Token

The token path is still fully supported, and the integration panel says so under the consent button: “You can still connect with an API token instead, the instructions are below.” Use it if you want to scope credentials narrowly yourself, or if consent is not available on your instance.

1. Log into Cloudflare Dashboard

2. Go to My Profile → API Tokens

3. Click Create Token

4. Use Custom Token with these permissions:

   Resource	Permission	Needed for
   Zone > Firewall Services	Edit	WAF rule pushes
   Zone > Zone	Read	Listing your zones so you can pick one
   Zone > Workers Routes	Edit	Binding the edge sensor to your traffic
   Account > Workers Scripts	Edit	Uploading the edge sensor Worker
   Zone > DNS	Read	Checking your hostname is proxied before installing

   DNS > Read is optional. Without it the install still works, but it cannot confirm your record is proxied (orange cloud) first, and a Worker on a DNS-only record never runs, so the sensor would report nothing with no obvious reason why.

   This check is only possible on an API token. Cloudflare’s OAuth permissions do not cover reading DNS records, so a connection made by consent always skips it. See Cloudflare Edge Sensor.

   Then scope the token to both resource types:

   • Zone Resources: Include → Specific Zone → your domain
   • Account Resources: Include → your account

   Account Resources is easy to miss

   Workers Scripts is an account-level permission. A token scoped only to a zone cannot upload the edge sensor even with the permission ticked: the install fails with a message asking you to reconnect with more permissions.

   If you are not using the edge sensor, only the first row is required.

5. Copy the generated token (shown only once)

Setting Up the Integration

1. Go to Integrations → Cloudflare

2. Scroll past the consent card to Enter API Credentials

3. Enter your credentials:

   Field	Description
   API Token	Your Cloudflare API token
   Account ID	Your Cloudflare account ID
   Zone ID	The zone (domain) to protect
   Zone Name (Domain)	Domain name (e.g., yoursite.com)

4. Click Connect Cloudflare

5. WebDecoy verifies the connection

Once connected, the panel shows Currently Connected with the Zone and Account it is bound to. Editing an existing integration changes the submit button to Update Integration.

Finding Your Account ID and Zone ID

Account ID:

1. Go to any domain in Cloudflare dashboard
2. Look in the right sidebar under “API”
3. Copy the “Account ID”

Zone ID:

1. Go to the specific domain
2. Look in the right sidebar under “API”
3. Copy the “Zone ID”

How Enforcement Works

The legacy per-decoy blocking rules were retired. Enforcement is now driven by Response Actions on the Enforcement page:

• Block actor at WAF (block_actor): for a confirmed rotating actor, pushes a composite fingerprint rule (the actor’s JA4 and its network anchor, never a bare fingerprint) so the block follows the attacker across every IP it rotates through.
• Block IP (block_ip): blocks the detection’s IP address with an automatic expiry.

Fingerprint rules need Bot Management

Block actor at WAF builds its rule on cf.bot_management.ja4. That field is part of Cloudflare Bot Management, an Enterprise add-on. On Free, Pro and Business zones Cloudflare refuses the rule outright:

not entitled: the use of field cf.bot_management.ja4 is not allowed,
a Bot Management plan is required

This is a plan limit, not a WebDecoy one, and no configuration works around it. If your zone is below Enterprise + Bot Management:

• Block IP still works, because it uses only base fields.
• Session clearance still works, and is the stronger control anyway: it runs in your own Worker, checks a signed token per request, and survives the IP rotation a fingerprint rule is trying to catch. It has no plan requirement.
• AWS WAF has no equivalent gate if you want fingerprint rules specifically.

Run the Cloudflare zone check on the Enforcement page to confirm which applies to your zone rather than inferring it from your plan name. It reports three things separately: whether the integration authenticates, whether the JA4 field is available, and whether the zone accepts a plain rule from WebDecoy at all, so a missing field is never mistaken for a broken connection.

Best Practices

Do’s

• ✅ Use a dedicated API token (not global API key)
• ✅ Review Monitor-mode would-enforce data before flipping to Enforce
• ✅ Set reasonable block durations (24h is a good default)
• ✅ Test with a known IP before production use

Don’ts

• ❌ Use your global Cloudflare API key
• ❌ Set block duration to “forever” (IPs change hands)
• ❌ Block without monitoring results

Troubleshooting

“The Cloudflare connection did not complete”

You see this banner when you come back from Cloudflare’s consent screen without a usable grant, usually because the approval was cancelled or the browser dropped the return trip. A successful return says “Cloudflare connected.” instead. Press Connect with Cloudflare again; nothing is stored from a failed attempt.

“Invalid API Token” Error

1. Verify token was copied correctly (no extra spaces)
2. Check token hasn’t expired
3. Ensure token has required permissions
4. Try creating a new token

“Zone Not Found” Error

1. Verify Zone ID is correct
2. Ensure token has access to that zone
3. Check zone is active in Cloudflare

Rules Not Appearing in Cloudflare

Run the Cloudflare zone check on the Enforcement page first. It reports whether the token authenticates, whether the JA4 field is available, and whether the zone accepts a plain rule from WebDecoy, as three separate results.

• JA4 field fails, rule round-trip passes: expected below Enterprise. See Fingerprint rules need Bot Management. block_ip still works; block_actor cannot.
• Both fail: usually the credential. If you connected with an API token, custom rules moved off the legacy Firewall Rules endpoint, and a token minted for that one is not necessarily authorized for the Rulesets API. Re-create it with permission to edit this zone’s WAF custom rules and save it again. If you connected by consent, the token is not what is being used (see Connecting by consent on top of an existing API token); reconnect to refresh the grant.
• Everything passes but no rules appear: check you have a Response Action configured at all. With none, nothing is ever pushed.

---

Next Steps

• Webhooks - Custom event processing
• Slack - Real-time notifications
• Overview - All integrations