references/ddos/patterns.md

# DDoS Protection Patterns

## Allowlist Trusted IPs

```typescript
const config = {
  description: "Allowlist trusted IPs",
  rules: [{
    expression: "ip.src in { 203.0.113.0/24 192.0.2.1 }",
    action: "execute",
    action_parameters: {
      id: managedRulesetId,
      overrides: { sensitivity_level: "eoff" },
    },
  }],
};

await client.accounts.rulesets.phases.entrypoint.update("ddos_l7", {
  account_id: accountId,
  ...config,
});
```

## Route-specific Sensitivity

```typescript
const config = {
  description: "Route-specific protection",
  rules: [
    {
      expression: "not http.request.uri.path matches \"^/api/\"",
      action: "execute",
      action_parameters: {
        id: managedRulesetId,
        overrides: { sensitivity_level: "default", action: "block" },
      },
    },
    {
      expression: "http.request.uri.path matches \"^/api/\"",
      action: "execute",
      action_parameters: {
        id: managedRulesetId,
        overrides: { sensitivity_level: "low", action: "managed_challenge" },
      },
    },
  ],
};
```

## Progressive Enhancement

```typescript
enum ProtectionLevel { MONITORING = "monitoring", LOW = "low", MEDIUM = "medium", HIGH = "high" }

const levelConfig = {
  [ProtectionLevel.MONITORING]: { action: "log", sensitivity: "eoff" },
  [ProtectionLevel.LOW]: { action: "managed_challenge", sensitivity: "low" },
  [ProtectionLevel.MEDIUM]: { action: "managed_challenge", sensitivity: "medium" },
  [ProtectionLevel.HIGH]: { action: "block", sensitivity: "default" },
} as const;

async function setProtectionLevel(zoneId: string, level: ProtectionLevel, rulesetId: string, client: Cloudflare) {
  const settings = levelConfig[level];
  return client.zones.rulesets.phases.entrypoint.update("ddos_l7", {
    zone_id: zoneId,
    rules: [{
      expression: "true",
      action: "execute",
      action_parameters: { id: rulesetId, overrides: { action: settings.action, sensitivity_level: settings.sensitivity } },
    }],
  });
}
```

## Dynamic Response to Attacks

```typescript
interface Env { CLOUDFLARE_API_TOKEN: string; ZONE_ID: string; KV: KVNamespace; }

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.url.includes("/attack-detected")) {
      const attackData = await request.json();
      await env.KV.put(`attack:${Date.now()}`, JSON.stringify(attackData), { expirationTtl: 86400 });
      const recentAttacks = await getRecentAttacks(env.KV);
      if (recentAttacks.length > 5) {
        await setProtectionLevel(env.ZONE_ID, ProtectionLevel.HIGH, managedRulesetId, client);
        return new Response("Protection increased");
      }
    }
    return new Response("OK");
  },
  async scheduled(event: ScheduledEvent, env: Env): Promise<void> {
    const recentAttacks = await getRecentAttacks(env.KV);
    if (recentAttacks.length === 0) await setProtectionLevel(env.ZONE_ID, ProtectionLevel.MEDIUM, managedRulesetId, client);
  },
};
```

## Multi-rule Tiered Protection (Enterprise Advanced)

```typescript
const config = {
  description: "Multi-tier DDoS protection",
  rules: [
    {
      expression: "not ip.src in $known_ips and not cf.bot_management.score gt 30",
      action: "execute",
      action_parameters: { id: managedRulesetId, overrides: { sensitivity_level: "default", action: "block" } },
    },
    {
      expression: "cf.bot_management.verified_bot",
      action: "execute",
      action_parameters: { id: managedRulesetId, overrides: { sensitivity_level: "medium", action: "managed_challenge" } },
    },
    {
      expression: "ip.src in $trusted_ips",
      action: "execute",
      action_parameters: { id: managedRulesetId, overrides: { sensitivity_level: "low" } },
    },
  ],
};
```

## Defense in Depth

Layered security stack: DDoS + WAF + Rate Limiting + Bot Management.

```typescript
// Layer 1: DDoS (volumetric attacks)
await client.zones.rulesets.phases.entrypoint.update("ddos_l7", {
  zone_id: zoneId,
  rules: [{ expression: "true", action: "execute", action_parameters: { id: ddosRulesetId, overrides: { sensitivity_level: "medium" } } }],
});

// Layer 2: WAF (exploit protection)
await client.zones.rulesets.phases.entrypoint.update("http_request_firewall_managed", {
  zone_id: zoneId,
  rules: [{ expression: "true", action: "execute", action_parameters: { id: wafRulesetId } }],
});

// Layer 3: Rate Limiting (abuse prevention)
await client.zones.rulesets.phases.entrypoint.update("http_ratelimit", {
  zone_id: zoneId,
  rules: [{ expression: "http.request.uri.path eq \"/api/login\"", action: "block", ratelimit: { characteristics: ["ip.src"], period: 60, requests_per_period: 5 } }],
});

// Layer 4: Bot Management (automation detection)
await client.zones.rulesets.phases.entrypoint.update("http_request_sbfm", {
  zone_id: zoneId,
  rules: [{ expression: "cf.bot_management.score lt 30", action: "managed_challenge" }],
});
```

## Cache Strategy for DDoS Mitigation

Exclude query strings from cache key to counter randomized query parameter attacks.

```typescript
const cacheRule = {
  expression: "http.request.uri.path matches \"^/api/\"",
  action: "set_cache_settings",
  action_parameters: {
    cache: true,
    cache_key: { ignore_query_strings_order: true, custom_key: { query_string: { exclude: { all: true } } } },
  },
};

await client.zones.rulesets.phases.entrypoint.update("http_request_cache_settings", { zone_id: zoneId, rules: [cacheRule] });
```

**Rationale**: Attackers randomize query strings (`?random=123456`) to bypass cache. Excluding query params ensures cache hits absorb attack traffic.

See [configuration.md](./configuration.md) for rule structure details.