400-cloudflare

Cloudflare Ruleset Engineering Guide

Goal: Build secure, performant, maintainable Cloudflare rulesets that protect applications while maintaining excellent user experience.

Cloudflare Ruleset Philosophy

Guiding Principles:

• Naming Consistency: Never use CloudFlare anywhere (code/documentation). If any existing docs contain it, flag and fix to Cloudflare
• Terminology Consistency: Do not use the word Domain for Cloudflare. Always use Zone. If any existing docs mention “Cloudflare Domain”, flag and fix to “Cloudflare Zone”
• Environment Variable Prefixing: Never use CF_ for Cloudflare-related environment variables, secret names, or examples. Always use CLOUDFLARE_ (for example CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID, CLOUDFLARE_RULESET_ID)
• Performance First: Order conditions from fast to slow (IP/host/method → path/headers → body/regex)
• Security by Default: Assume hostile intent; validate and sanitize all inputs
• Fail Securely: Block by default, allow explicitly; log everything
• User Experience: Use challenges before blocks; provide clear error messages
• Operational Excellence: Test thoroughly, deploy gradually, monitor continuously
• Cost Awareness: Minimize expensive operations (body inspection, regex); use Workers for complex logic

Core Tenets:

1. Fast Evaluation Order: Cheap checks (IP, host, method) before expensive ones (body, regex)
2. Defense in Depth: Multiple layers of protection (WAF → Rate Limiting → Bot Management)
3. Zero Trust: Never trust user input; validate and sanitize everything
4. Observability: Log all actions; monitor effectiveness; alert on anomalies
5. Iterative Improvement: Start with log-only, refine based on data, then enforce

Applying Cloudflare Philosophy:

// BAD: Expensive operations first
(http.request.body.raw contains "malicious" and http.host eq "api.acme.com")

// GOOD: Fast checks first, short-circuit early
(http.host eq "api.acme.com" and http.request.body.raw contains "malicious")

// BAD: Trusting user input
http.request.uri.path contains "/admin"

// GOOD: Zero trust - validate and sanitize
(
  lower(http.request.uri.path) contains "/admin" or
  lower(urldecode(http.request.uri.path)) contains "/admin" or
  lower(urldecode(urldecode(http.request.uri.path))) contains "/admin"
)

// BAD: Block immediately (poor UX)
(http.request.uri.path contains "/api/" and rate(ip.src, 1m) > 100)
# Action: Block

// GOOD: Challenge first, then block (better UX)
(http.request.uri.path contains "/api/" and rate(ip.src, 1m) > 100)
# Action: Managed Challenge
# If challenge fails → Block