AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cloudflare-deploy

Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--cloudflare-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 309

references/waf/gotchas.md

Gotchas & Troubleshooting

Execution Order

Problem: Rules execute in unexpected order Cause: Misunderstanding phase execution Solution:

Phases execute sequentially (can't be changed):

  1. http_request_firewall_custom - Custom rules
  2. http_request_firewall_managed - Managed rulesets
  3. http_ratelimit - Rate limiting

Within phase: top-to-bottom, first match wins (unless skip)

// WRONG: Can't mix phase-specific actions
await client.rulesets.create({
  phase: 'http_request_firewall_custom',
  rules: [
    { action: 'block', expression: 'cf.waf.score gt 50' },
    { action: 'execute', action_parameters: { id: 'managed_id' } }, // WRONG
  ],
});

// CORRECT: Separate rulesets per phase
await client.rulesets.create({ phase: 'http_request_firewall_custom', rules: [...] });
await client.rulesets.create({ phase: 'http_request_firewall_managed', rules: [...] });

Expression Errors

Problem: Syntax errors prevent deployment Cause: Invalid field/operator/syntax Solution:

// Common mistakes
'http.request.path' → 'http.request.uri.path' // Correct field
'ip.geoip.country eq US' → 'ip.geoip.country eq "US"' // Quote strings
'http.user_agent eq "Mozilla"' → 'lower(http.user_agent) contains "mozilla"' // Case sensitivity
'matches ".*[.jpg"' → 'matches ".*\\.jpg$"' // Valid regex

Test expressions in Security Events before deploying.

Skip Rule Pitfalls

Problem: Skip rules don't work as expected Cause: Misunderstanding skip scope Solution:

Skip types:

  • ruleset: 'current' - Skip remaining rules in current ruleset only
  • phases: ['phase_name'] - Skip entire phases
// WRONG: Trying to skip managed rules from custom phase
// In http_request_firewall_custom:
{
  action: 'skip',
  action_parameters: { ruleset: 'current' },
  expression: 'ip.src in {192.0.2.0/24}',
}
// This only skips remaining custom rules, not managed rules

// CORRECT: Skip specific phases
{
  action: 'skip',
  action_parameters: {
    phases: ['http_request_firewall_managed', 'http_ratelimit'],
  },
  expression: 'ip.src in {192.0.2.0/24}',
}

Update Replaces All Rules

Problem: Updating ruleset deletes other rules Cause: update() replaces entire rule list Solution:

// WRONG: This deletes all existing rules!
await client.rulesets.update({
  zone_id: 'zone_id',
  ruleset_id: 'ruleset_id',
  rules: [{ action: 'block', expression: 'cf.waf.score gt 50' }],
});

// CORRECT: Get existing rules first
const ruleset = await client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });
await client.rulesets.update({
  zone_id: 'zone_id',
  ruleset_id: 'ruleset_id',
  rules: [...ruleset.rules, { action: 'block', expression: 'cf.waf.score gt 50' }],
});

Override Conflicts

Problem: Managed ruleset overrides don't apply Cause: Rule ID doesn't exist or category name incorrect Solution:

// List managed ruleset rules to find IDs
const ruleset = await client.rulesets.get({
  zone_id: 'zone_id',
  ruleset_id: 'efb7b8c949ac4650a09736fc376e9aee',
});
console.log(ruleset.rules.map(r => ({ id: r.id, description: r.description })));

// Use correct IDs in overrides
{ action: 'execute', action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee', 
  overrides: { rules: [{ id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log' }] } } }

False Positives

Problem: Legitimate traffic blocked Cause: Aggressive rules/thresholds Solution:

  1. Start with log mode: overrides: { action: 'log' }
  2. Review Security Events to identify false positives
  3. Override specific rules: overrides: { rules: [{ id: 'rule_id', action: 'log' }] }

Rate Limiting NAT Issues

Problem: Users behind NAT hit rate limits too quickly Cause: Multiple users sharing single IP Solution:

Add more characteristics: User-Agent, session cookie, or authorization header

{
  action: 'block',
  expression: 'http.request.uri.path starts_with "/api"',
  action_parameters: {
    ratelimit: {
      characteristics: ['cf.colo.id', 'ip.src', 'http.request.cookies["session"][0]'],
      period: 60,
      requests_per_period: 100,
    },
  },
}

Performance Issues

Problem: Increased latency Cause: Complex expressions, excessive rules Solution:

  1. Skip static assets early: action: 'skip' for \\.(jpg|css|js)$
  2. Path-based deployment: Only run managed on /api or /admin
  3. Disable unused categories: { category: 'wordpress', enabled: false }
  4. Prefer string operators over regex: starts_with vs matches

Limits & Quotas

| Resource | Free | Pro | Business | Enterprise | |----------|------|-----|----------|------------| | Custom rules | 5 | 20 | 100 | 1000 | | Rate limiting rules | 1 | 10 | 25 | 100 | | Rule expression length | 4096 chars | 4096 chars | 4096 chars | 4096 chars | | Rules per ruleset | 75 | 75 | 400 | 1000 | | Managed rulesets | Yes | Yes | Yes | Yes | | Rate limit characteristics | 2 | 3 | 5 | 5 |

Important Notes:

  • Rules execute in order; first match wins (except skip rules)
  • Expression evaluation stops at first false in AND chains
  • matches regex operator is slower than string operators
  • Rate limit counting happens before mitigation

API Errors

Problem: API calls fail with cryptic errors Cause: Invalid parameters or permissions Solution:

// Error: "Invalid phase" → Use exact phase name
phase: 'http_request_firewall_custom'

// Error: "Ruleset already exists" → Use update() or list first
const rulesets = await client.rulesets.list({ zone_id, phase: 'http_request_firewall_custom' });
if (rulesets.result.length > 0) {
  await client.rulesets.update({ zone_id, ruleset_id: rulesets.result[0].id, rules: [...] });
}

// Error: "Action not supported" → Check phase/action compatibility
// 'execute' only in http_request_firewall_managed
// Rate limit config only in http_ratelimit phase

// Error: "Expression parse error" → Common fixes:
'ip.geoip.country eq "US"'   // Quote strings
'cf.waf.score gt 40'         // Use 'gt' not '>'
'http.request.uri.path'      // Not 'http.request.path'

Tip: Test expressions in dashboard Security Events before deploying.