Firewall

Manage firewall rules, access rules, and WAF settings

The Firewall resource provides methods to manage firewall rules, access rules, lockdowns, user agent rules, and Web Application Firewall (WAF) settings.

Firewall rules

create

Create one or more firewall rules.

const rules = await client.firewall.rules.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  rules: [
    {
      filter: {
        expression: '(http.request.uri.path contains "/api/")'
      },
      action: 'block',
      description: 'Block API requests'
    }
  ]
});

zone_id · string · required

Zone identifier

rules · array · required

Array of firewall rules to create

rules[].filter · object · required

Filter expression

rules[].filter.expression · string · required

Firewall filter expression (e.g., ‘(http.request.uri.path contains “/api/”)’)

rules[].action · 'block' | 'challenge' | 'js_challenge' | 'managed_challenge' | 'allow' | 'log' | 'bypass' · required

Action to perform when the rule matches

rules[].description · string

Description of the rule

rules[].priority · number

Rule priority (lower numbers execute first)

rules[].paused · boolean

Whether the rule is paused

id · string

Firewall rule identifier

filter · object

Filter configuration

action · string

Action to perform

description · string

Rule description

priority · number

Rule priority

paused · boolean

Whether the rule is paused

update

Update a firewall rule.

const rule = await client.firewall.rules.update(
  'rule_123',
  {
    zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
    action: 'managed_challenge',
    description: 'Updated rule'
  }
);

rule_id · string · required

Firewall rule identifier (first parameter)

zone_id · string · required

Zone identifier

list

List all firewall rules for a zone.

for await (const rule of client.firewall.rules.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353'
})) {
  console.log(`${rule.description}: ${rule.action}`);
}

zone_id · string · required

Zone identifier

delete

Delete a firewall rule.

const result = await client.firewall.rules.delete(
  'rule_123',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

rule_id · string · required

Firewall rule identifier (first parameter)

zone_id · string · required

Zone identifier

get

Get details for a specific firewall rule.

const rule = await client.firewall.rules.get(
  'rule_123',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Access rules

Access rules allow you to block, challenge, or allow traffic based on IP address, IP range, country, or ASN.

create

Create an access rule.

// Block an IP address
const rule = await client.firewall.accessRules.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  mode: 'block',
  configuration: {
    target: 'ip',
    value: '192.0.2.1'
  },
  notes: 'Block malicious IP'
});

// Block a country
const countryRule = await client.firewall.accessRules.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  mode: 'challenge',
  configuration: {
    target: 'country',
    value: 'CN'
  }
});

account_id · string

Account identifier (use either account_id or zone_id)

zone_id · string

Zone identifier (use either account_id or zone_id)

mode · 'block' | 'challenge' | 'whitelist' | 'js_challenge' | 'managed_challenge' · required

Action to apply to matching traffic

configuration · object · required

Rule configuration

configuration.target · 'ip' | 'ip_range' | 'country' | 'asn' | 'ip6' · required

Target type

configuration.value · string · required

Target value (IP address, country code, ASN number, etc.)

notes · string

Description or notes about the rule

list

List access rules.

for await (const rule of client.firewall.accessRules.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  mode: 'block'
})) {
  console.log(rule);
}

mode · string

Filter by mode

configuration.target · string

Filter by target type

Lockdowns

Lockdowns restrict access to URLs to specific IP addresses or ranges.

create

Create a zone lockdown rule.

const lockdown = await client.firewall.lockdowns.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  urls: ['example.com/admin/*'],
  configurations: [
    {
      target: 'ip',
      value: '192.0.2.1'
    }
  ],
  description: 'Restrict admin panel to office IP'
});

zone_id · string · required

Zone identifier

urls · string[] · required

URLs to apply the lockdown to (supports wildcards)

configurations · array · required

IP addresses or ranges to allow

configurations[].target · 'ip' | 'ip_range' · required

Configuration type

configurations[].value · string · required

IP address or CIDR range

description · string

Description of the lockdown

paused · boolean

Whether the lockdown is paused

list

List zone lockdown rules.

for await (const lockdown of client.firewall.lockdowns.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353'
})) {
  console.log(`${lockdown.description}: ${lockdown.urls.join(', ')}`);
}

User agent rules

User agent rules allow you to block or challenge requests based on the User-Agent header.

create

Create a user agent blocking rule.

const uaRule = await client.firewall.uaRules.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  mode: 'block',
  configuration: {
    target: 'ua',
    value: 'BadBot/1.0'
  },
  description: 'Block BadBot'
});

zone_id · string · required

Zone identifier

mode · 'block' | 'challenge' | 'js_challenge' | 'managed_challenge' · required

Action to apply

configuration · object · required

Configuration

configuration.target · 'ua' · required

Must be ‘ua’

configuration.value · string · required

User agent string to match

Firewall actions

Available actions for firewall rules:

• block - Block the request
• challenge - Present a CAPTCHA challenge
• js_challenge - Present a JavaScript challenge
• managed_challenge - Present a Cloudflare-managed challenge
• allow - Allow the request
• log - Log the request but take no action
• bypass - Bypass subsequent firewall rules

Example usage

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN
});

const zoneId = '023e105f4ecef8ad9ca31a8372d0c353';

// Create a firewall rule to block specific paths
const firewallRule = await client.firewall.rules.create({
  zone_id: zoneId,
  rules: [
    {
      filter: {
        expression: '(http.request.uri.path contains "/wp-admin/" and ip.geoip.country ne "US")'
      },
      action: 'block',
      description: 'Block non-US access to WordPress admin'
    }
  ]
});

// Create an access rule to block an IP
const accessRule = await client.firewall.accessRules.create({
  zone_id: zoneId,
  mode: 'block',
  configuration: {
    target: 'ip',
    value: '192.0.2.100'
  },
  notes: 'Blocked for abuse'
});

// Create a lockdown for admin area
const lockdown = await client.firewall.lockdowns.create({
  zone_id: zoneId,
  urls: ['example.com/admin/*', 'example.com/dashboard/*'],
  configurations: [
    { target: 'ip', value: '192.0.2.1' },
    { target: 'ip_range', value: '198.51.100.0/24' }
  ],
  description: 'Office IP lockdown for admin'
});

// Block a bad bot
const uaRule = await client.firewall.uaRules.create({
  zone_id: zoneId,
  mode: 'block',
  configuration: {
    target: 'ua',
    value: 'BadBot'
  },
  description: 'Block BadBot crawler'
});

// List all firewall rules
for await (const rule of client.firewall.rules.list({ zone_id: zoneId })) {
  console.log(`Rule: ${rule.description}`);
  console.log(`  Action: ${rule.action}`);
  console.log(`  Paused: ${rule.paused}`);
}