Ruleset

A ruleset is an ordered set of rules that you can apply to traffic on the Cloudflare global network. Rulesets belong to a phase and can only execute in the same phase. To deploy a ruleset to a phase, add a rule that executes the ruleset to the [phase entry point ruleset](phase entry point ruleset).

Custom Firewall Rules

Create custom firewall rules to block malicious traffic and challenge suspicious requests.

const firewall = await Ruleset("custom-firewall", {
  zone: "example.com",
  phase: "http_request_firewall_custom",
  rules: [
    {
      description: "Block bad IPs",
      expression: "ip.src in {1.2.3.4 1.2.3.5}",
      action: "block"
    },
    {
      description: "Challenge suspicious requests",
      expression: "cf.threat_score > 50",
      action: "challenge"
    }
  ]
});

Rate Limiting

Configure sophisticated rate limiting with multiple characteristics and custom timeouts.

const advancedRateLimit = await Ruleset("advanced-rate-limit", {
  zone: "example.com",
  phase: "http_ratelimit",
  name: "Advanced API Protection",
  description: "Multi-tier rate limiting for different endpoints",
  rules: [
    {
      description: "Strict rate limit for auth endpoints",
      expression: '(http.request.uri.path wildcard r"/auth/*")',
      action: "block",
      ratelimit: {
        characteristics: ["ip.src", "http.request.headers[\"user-agent\"]"],
        period: 300,
        requests_per_period: 5,
        mitigation_timeout: 3600
      }
    },
    {
      description: "General API rate limit",
      expression: '(http.request.uri.path wildcard r"/api/*")',
      action: "block",
      ratelimit: {
        characteristics: ["ip.src"],
        period: 60,
        requests_per_period: 1000,
        mitigation_timeout: 60
      }
    }
  ]
});

Request Transforms

Transform incoming requests by modifying headers, URLs, or other request properties.

const transforms = await Ruleset("header-transforms", {
  zone: "example.com",
  phase: "http_request_transform",
  rules: [
    {
      description: "Add custom header",
      expression: "true",
      action: "rewrite",
      action_parameters: {
        headers: {
          "X-Custom-Header": { value: "my-value" }
        }
      }
    },
    {
      description: "Rewrite API paths",
      expression: 'http.request.uri.path matches "^/v1/"',
      action: "rewrite",
      action_parameters: {
        uri: {
          path: {
            expression: 'regex_replace(http.request.uri.path, "^/v1/", "/api/v1/")'
          }
        }
      }
    }
  ]
});

Response Transforms

Modify outgoing responses using response phase rulesets.

const responseTransforms = await Ruleset("response-transforms", {
  zone: "example.com",
  phase: "http_response_headers_transform",
  rules: [
    {
      description: "Add security headers",
      expression: "true",
      action: "rewrite",
      action_parameters: {
        headers: {
          "X-Frame-Options": { value: "DENY" },
          "X-Content-Type-Options": { value: "nosniff" },
          "Strict-Transport-Security": {
            value: "max-age=31536000; includeSubDomains"
          }
        }
      }
    }
  ]
});

Using Zone Resource

Reference an existing zone resource instead of using a zone name.

import { Ruleset, Zone } from "alchemy/cloudflare";

const zone = await Zone("my-zone", {
  name: "example.com",
  type: "full"
});

const ruleset = await Ruleset("zone-ruleset", {
  zone: zone,
  phase: "http_request_firewall_custom",
  rules: [
    {
      description: "Custom protection",
      expression: "http.request.uri.path eq \"/admin\"",
      action: "block"
    }
  ]
});

Configuration Options

Option	Type	Description
`zone`	`string \| Zone`	The zone to apply the ruleset to
`phase`	`RulePhase`	The phase of the ruleset (defaults to “http_ratelimit”)
`rules`	`Array<Rule>`	Rules to apply in the ruleset
`name`	`string`	Human-readable name for the ruleset
`description`	`string`	Description of the ruleset

Common Rule Phases

http_ratelimit - Rate limiting rules
http_request_firewall_custom - Custom firewall rules
http_request_transform - Request transformation rules
http_response_headers_transform - Response header modification
http_request_redirect - URL redirect rules
http_request_cache_settings - Cache configuration rules