Back to Details

vercel-firewall

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vercel Firewall

Vercel Firewall

You are an expert in the Vercel Firewall — a multi-layered security solution with automatic DDoS protection, a customizable Web Application Firewall (WAF), bot management, and rate limiting.
您是Vercel Firewall方面的专家——这是一款多层安全解决方案，具备自动DDoS防护、可自定义的Web应用防火墙（WAF）、机器人管理和速率限制功能。

Architecture & Rule Execution Order

架构与规则执行顺序

  1. DDoS mitigation rules (automatic, platform-wide)
  2. WAF IP blocking rules
  3. WAF custom rules (in priority order)
  4. WAF Managed Rulesets (OWASP, Bot Protection, AI Bots)
Changes propagate globally in under 300ms. No redeployment required.
  1. DDoS缓解规则（自动生效，全平台覆盖）
  2. WAF IP阻止规则
  3. WAF自定义规则（按优先级排序）
  4. WAF托管规则集（OWASP、机器人防护、AI机器人）
配置变更会在300毫秒内全球同步生效，无需重新部署。

DDoS Protection (Automatic, All Plans)

DDoS防护（自动生效，所有套餐均包含）

  • Layer 3/4 mitigation (automatic, always on)
  • Layer 7 protection (proprietary, tailored to web apps)
  • Protectd: Vercel's DoS mitigation infrastructure analyzes ~550K events/sec globally with median mitigation time of 2.5 seconds
  • 40x faster detection with real-time stream processing
  • Handles 1B+ suspicious TCP connections per week
  • Proven to mitigate 1.37 Tbps attacks with zero downtime
No configuration needed — DDoS protection is always active.
  • 第3/4层缓解（自动启用，始终生效）
  • 第7层防护（专有技术，针对Web应用定制）
  • Protectd：Vercel的DoS缓解基础设施全球每秒分析约55万次事件，平均缓解时间仅2.5秒
  • 实时流处理技术使检测速度提升40倍
  • 每周处理超过10亿次可疑TCP连接
  • 已验证可缓解1.37 Tbps的攻击，且实现零停机
无需任何配置——DDoS防护始终处于激活状态。

WAF Custom Rules

WAF自定义规则

Rule JSON Structure

规则JSON结构

json
{
  "name": "Block WordPress scanners",
  "description": "Block common WordPress probe paths",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "path",
          "op": "re",
          "value": "^/wp-(admin|login|content|includes)/"
        }
      ]
    }
  ],
  "action": {
    "mitigate": {
      "action": "deny"
    }
  }
}
Logic: Each object in 
conditionGroup
is an OR group. Conditions within a single group are ANDed. Multiple groups are ORed.
json
{
  "name": "Block WordPress scanners",
  "description": "Block common WordPress probe paths",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "path",
          "op": "re",
          "value": "^/wp-(admin|login|content|includes)/"
        }
      ]
    }
  ],
  "action": {
    "mitigate": {
      "action": "deny"
    }
  }
}
逻辑：
conditionGroup
中的每个对象是一个OR组，单个组内的条件为AND关系，多个组之间为OR关系。

Condition Types (25 available)

条件类型（共25种）

TypeDescriptionExtra Fields
path
URL path
method
HTTP method
host
Hostname
ip_address
Client IP (supports CIDR)
user_agent
User-Agent string
header
Request header value
key
(header name)
query
Query string parameter
key
(param name)
cookie
Cookie value
key
(cookie name)
geo_country
ISO country code (e.g., 
US
)
geo_continent
Continent code (e.g., 
NA
)
geo_country_region
State/province code
geo_city
City name
geo_as_number
ASN
ja4_digest
JA4 TLS fingerprint
ja3_digest
JA3 TLS fingerprint
target_path
Resolved path after routing
route
Matched route pattern
raw_path
Raw unparsed path
region
Vercel edge region code
protocol
http/https
scheme
URL scheme
environment
Deployment environment
bot_name
Specific bot name
bot_category
Bot category
server_action
Next.js Server Action ID
类型描述额外字段
path
URL路径
method
HTTP方法
host
主机名
ip_address
客户端IP（支持CIDR格式）
user_agent
User-Agent字符串
header
请求头值
key
（请求头名称）
query
查询字符串参数
key
（参数名称）
cookie
Cookie值
key
（Cookie名称）
geo_country
ISO国家代码（例如：
US
）
geo_continent
大洲代码（例如：
NA
）
geo_country_region
州/省代码
geo_city
城市名称
geo_as_number
ASN（自治系统号）
ja4_digest
JA4 TLS指纹
ja3_digest
JA3 TLS指纹
target_path
路由解析后的路径
route
匹配的路由模式
raw_path
原始未解析路径
region
Vercel边缘区域代码
protocol
http/https
scheme
URL协议
environment
部署环境
bot_name
特定机器人名称
bot_category
机器人类别
server_action
Next.js Server Action ID

Condition Operators

条件运算符

OpMeaning
eq
Equals
neq
Not equals
re
Regex match
pre
Starts with
suf
Ends with
sub
Contains
inc
In array
ninc
Not in array
ex
Exists
nex
Not exists
gt
/ 
gte
Greater than (or equal)
lt
/ 
lte
Less than (or equal)
Additional optional fields: 
neg: true
negates the condition, 
key
required for 
header
/
query
/
cookie
types.
运算符含义
eq
等于
neq
不等于
re
正则匹配
pre
以...开头
suf
以...结尾
sub
包含
inc
在数组中
ninc
不在数组中
ex
存在
nex
不存在
gt
/ 
gte
大于（或等于）
lt
/ 
lte
小于（或等于）
额外可选字段：
neg: true
表示对条件取反，
header
/
query
/
cookie
类型需要指定
key
字段。

Mitigation Actions

缓解动作

ActionDescription
log
Log only, allow traffic
deny
Block request (403)
challenge
JavaScript browser challenge
bypass
Skip all subsequent WAF rules
rate_limit
Apply rate limiting (requires 
rateLimit
config)
redirect
Redirect (requires 
redirect
config)
动作描述
log
仅记录日志，允许流量通过
deny
阻止请求（返回403）
challenge
发起JavaScript浏览器验证挑战
bypass
跳过后续所有WAF规则
rate_limit
应用速率限制（需要
rateLimit
配置）
redirect
重定向（需要
redirect
配置）

Persistent Actions

持久化动作

By default each request is evaluated individually. With persistent actions, rules are applied to all matching requests for a customizable duration (
actionDuration
), allowing the firewall to remember malicious behavior and block it earlier in the lifecycle.
默认情况下，每个请求会被单独评估。启用持久化动作后，规则会在自定义时长（
actionDuration
）内应用于所有匹配的请求，使防火墙能够记住恶意行为并在生命周期早期阻止。

Action Options

动作选项

json
{
  "action": {
    "mitigate": {
      "action": "deny",
      "actionDuration": "1h",
      "bypassSystem": false,
      "logHeaders": ["user-agent", "x-forwarded-for"],
      "redirect": {
        "location": "https://example.com/blocked",
        "permanent": false
      }
    }
  }
}
json
{
  "action": {
    "mitigate": {
      "action": "deny",
      "actionDuration": "1h",
      "bypassSystem": false,
      "logHeaders": ["user-agent", "x-forwarded-for"],
      "redirect": {
        "location": "https://example.com/blocked",
        "permanent": false
      }
    }
  }
}

Practical Rule Examples

实用规则示例

Block Sanctioned Countries

阻止受制裁国家的访问

json
{
  "name": "Block OFAC Sanctioned Countries",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "geo_country",
          "op": "inc",
          "value": ["CU", "IR", "KP", "RU", "SY"]
        }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "deny" }
  }
}
json
{
  "name": "Block OFAC Sanctioned Countries",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "geo_country",
          "op": "inc",
          "value": ["CU", "IR", "KP", "RU", "SY"]
        }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "deny" }
  }
}

Require API Key Header on /api/ Routes

/api/路由要求携带API Key请求头

json
{
  "name": "Require API Key",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "header",
          "op": "nex",
          "key": "x-api-key"
        },
        {
          "type": "path",
          "op": "pre",
          "value": "/api/"
        }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "deny" }
  }
}
json
{
  "name": "Require API Key",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "header",
          "op": "nex",
          "key": "x-api-key"
        },
        {
          "type": "path",
          "op": "pre",
          "value": "/api/"
        }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "deny" }
  }
}

Block by JA4 TLS Fingerprint

通过JA4 TLS指纹阻止访问

json
{
  "name": "Block Known Malicious JA4",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "ja4_digest",
          "op": "eq",
          "value": "t13d1516h2_8daaf6152771_b0da82dd1658"
        }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "deny", "actionDuration": "1h" }
  }
}
json
{
  "name": "Block Known Malicious JA4",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "ja4_digest",
          "op": "eq",
          "value": "t13d1516h2_8daaf6152771_b0da82dd1658"
        }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "deny", "actionDuration": "1h" }
  }
}

Block Datacenter ASNs

阻止数据中心ASN的访问

json
{
  "name": "Block Known Datacenter ASNs",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "geo_as_number",
          "op": "inc",
          "value": ["14618", "16509", "15169"]
        }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "deny" }
  }
}
json
{
  "name": "Block Known Datacenter ASNs",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "geo_as_number",
          "op": "inc",
          "value": ["14618", "16509", "15169"]
        }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "deny" }
  }
}

Challenge cURL Requests

对cURL请求发起验证挑战

json
{
  "name": "Challenge cURL",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        { "type": "user_agent", "op": "re", "value": "^curl/" }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "challenge" }
  }
}
json
{
  "name": "Challenge cURL",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        { "type": "user_agent", "op": "re", "value": "^curl/" }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "challenge" }
  }
}

Rate Limiting

速率限制

Rate Limit Rule

速率限制规则

json
{
  "name": "API Rate Limit - 100 req/min",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        { "type": "path", "op": "pre", "value": "/api/" }
      ]
    }
  ],
  "action": {
    "mitigate": {
      "action": "rate_limit",
      "rateLimit": {
        "algo": "fixed_window",
        "window": 60,
        "limit": 100,
        "keys": ["ip"],
        "action": "deny"
      }
    }
  }
}
json
{
  "name": "API Rate Limit - 100 req/min",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        { "type": "path", "op": "pre", "value": "/api/" }
      ]
    }
  ],
  "action": {
    "mitigate": {
      "action": "rate_limit",
      "rateLimit": {
        "algo": "fixed_window",
        "window": 60,
        "limit": 100,
        "keys": ["ip"],
        "action": "deny"
      }
    }
  }
}

Login Endpoint Protection

登录端点防护

json
{
  "name": "Login Rate Limit",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        { "type": "path", "op": "eq", "value": "/api/auth/login" },
        { "type": "method", "op": "eq", "value": "POST" }
      ]
    }
  ],
  "action": {
    "mitigate": {
      "action": "rate_limit",
      "rateLimit": {
        "algo": "fixed_window",
        "window": 60,
        "limit": 10,
        "keys": ["ip"],
        "action": "challenge"
      }
    }
  }
}
json
{
  "name": "Login Rate Limit",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        { "type": "path", "op": "eq", "value": "/api/auth/login" },
        { "type": "method", "op": "eq", "value": "POST" }
      ]
    }
  ],
  "action": {
    "mitigate": {
      "action": "rate_limit",
      "rateLimit": {
        "algo": "fixed_window",
        "window": 60,
        "limit": 10,
        "keys": ["ip"],
        "action": "challenge"
      }
    }
  }
}

Rate Limit Configuration Options

速率限制配置选项

FieldTypeDescription
algo
string
"fixed_window"
(all plans) or 
"token_bucket"
(Enterprise)
window
numberSeconds. Min 10, max 600 (Pro), max 3600 (Enterprise)
limit
numberMax requests per window
keys
arrayCount per: 
"ip"
, 
"ja4"
, 
"user_agent"
, custom headers (Enterprise)
action
stringWhen exceeded: 
"deny"
, 
"log"
, 
"challenge"
When exceeded with 
deny
, returns HTTP 429 with 
X-RateLimit-Limit
and 
X-RateLimit-Remaining
headers.
字段类型描述
algo
字符串
"fixed_window"
（所有套餐）或
"token_bucket"
（企业版）
window
数字时间窗口（秒）。最低10秒，专业版最高600秒，企业版最高3600秒
limit
数字时间窗口内的最大请求数
keys
数组统计维度：
"ip"
、
"ja4"
、
"user_agent"
、自定义请求头（企业版）
action
字符串超出限制时的动作：
"deny"
、
"log"
、
"challenge"
当触发
deny
动作时，会返回HTTP 429状态码，并携带
X-RateLimit-Limit
和
X-RateLimit-Remaining
响应头。

Bot Management

机器人管理

Bot Protection (GA — Free on All Plans)

机器人防护（正式版——所有套餐免费）

Heuristics-based detection that challenges non-browser bot traffic without disrupting verified webhook providers. Formerly "Bot Filter" during beta — renamed to Bot Protection at GA. Enable in log-only mode first to preview traffic impact:
json
{
  "action": "managedRules.update",
  "id": "bot_protection",
  "value": { "active": true, "action": "challenge" }
}
Note: The older 
bot_filter
ID is deprecated. Use 
bot_protection
in new configurations.
基于启发式算法的检测机制，会对非浏览器机器人流量发起验证挑战，但不会影响已验证的Webhook提供商。测试阶段名为“Bot Filter”，正式发布时更名为Bot Protection。建议先启用日志模式预览对流量的影响：
json
{
  "action": "managedRules.update",
  "id": "bot_protection",
  "value": { "active": true, "action": "challenge" }
}
注意：旧版
bot_filter
ID已被弃用，新配置请使用
bot_protection
。

AI Bot Blocking

AI机器人阻止

Block known AI crawlers (GPTBot, ClaudeBot, etc.):
json
{
  "action": "managedRules.update",
  "id": "ai_bots",
  "value": { "active": true, "action": "deny" }
}
阻止已知的AI爬虫（如GPTBot、ClaudeBot等）：
json
{
  "action": "managedRules.update",
  "id": "ai_bots",
  "value": { "active": true, "action": "deny" }
}

Allow a Specific Bot (Bypass Rule)

允许特定机器人（绕过规则）

Place this higher in priority than Bot Protection managed rules:
json
{
  "name": "Allow My Monitoring Bot",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        { "type": "user_agent", "op": "eq", "value": "MyMonitorBot/1.0" }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "bypass" }
  }
}
请将此规则的优先级设置为高于Bot Protection托管规则：
json
{
  "name": "Allow My Monitoring Bot",
  "active": true,
  "conditionGroup": [
    {
      "conditions": [
        { "type": "user_agent", "op": "eq", "value": "MyMonitorBot/1.0" }
      ]
    }
  ],
  "action": {
    "mitigate": { "action": "bypass" }
  }
}

Enable BotID (Traffic Visibility)

启用BotID（流量可见性）

json
{ "botIdEnabled": true }
json
{ "botIdEnabled": true }

IP Allow/Block Lists

IP允许/阻止列表

Block an IP

阻止单个IP

json
{
  "action": "ip.insert",
  "value": {
    "hostname": "my-site.com",
    "ip": "203.0.113.45",
    "action": "deny",
    "notes": "Malicious scraper"
  }
}
json
{
  "action": "ip.insert",
  "value": {
    "hostname": "my-site.com",
    "ip": "203.0.113.45",
    "action": "deny",
    "notes": "Malicious scraper"
  }
}

Block a CIDR Range

阻止CIDR网段

json
{
  "action": "ip.insert",
  "value": {
    "hostname": "my-site.com",
    "ip": "203.0.113.0/24",
    "action": "deny",
    "notes": "Bad actor CIDR block"
  }
}
json
{
  "action": "ip.insert",
  "value": {
    "hostname": "my-site.com",
    "ip": "203.0.113.0/24",
    "action": "deny",
    "notes": "Bad actor CIDR block"
  }
}

Allow an IP (Bypass All Rules)

允许单个IP（绕过所有规则）

json
{
  "action": "ip.insert",
  "value": {
    "hostname": "my-site.com",
    "ip": "198.51.100.1",
    "action": "bypass",
    "notes": "Internal monitoring IP"
  }
}
json
{
  "action": "ip.insert",
  "value": {
    "hostname": "my-site.com",
    "ip": "198.51.100.1",
    "action": "bypass",
    "notes": "Internal monitoring IP"
  }
}

IP Rule Actions

IP规则动作

ActionEffect
deny
Block the IP
challenge
Serve JS challenge
log
Log traffic only
bypass
Allow through all rules (allowlist)
Note: 
hostname
must match the exact domain. Add separate entries per subdomain.
动作效果
deny
阻止该IP
challenge
发起JS验证挑战
log
仅记录流量
bypass
允许绕过所有规则（白名单）
注意：
hostname
必须与域名完全匹配，每个子域名需单独添加条目。

OWASP Core Ruleset (CRS)

OWASP核心规则集（CRS）

Individual CRS Rules

单个CRS规则

IDProtection
sqli
SQL Injection
xss
Cross-Site Scripting
rce
Remote Code Execution
lfi
Local File Inclusion
rfi
Remote File Inclusion
sd
Scanner Detection
ma
Multipart Attack
php
PHP-specific exploits
gen
Generic attack patterns
sf
Session Fixation
java
Java-specific exploits
ID防护类型
sqli
SQL注入
xss
跨站脚本攻击
rce
远程代码执行
lfi
本地文件包含
rfi
远程文件包含
sd
扫描器检测
ma
多部分攻击
php
PHP特定漏洞利用
gen
通用攻击模式
sf
会话固定
java
Java特定漏洞利用

Enable OWASP Rules

启用OWASP规则

json
{
  "action": "crs.update",
  "id": "sqli",
  "value": { "active": true, "action": "deny" }
}
json
{
  "action": "crs.update",
  "id": "sqli",
  "value": { "active": true, "action": "deny" }
}

Full OWASP + Bot Configuration (PUT)

完整OWASP + 机器人配置（PUT请求）

json
{
  "firewallEnabled": true,
  "crs": {
    "sqli": { "active": true, "action": "deny" },
    "xss": { "active": true, "action": "deny" },
    "rce": { "active": true, "action": "deny" },
    "lfi": { "active": true, "action": "deny" },
    "rfi": { "active": true, "action": "deny" },
    "sd": { "active": true, "action": "log" },
    "ma": { "active": true, "action": "deny" },
    "gen": { "active": true, "action": "deny" },
    "sf": { "active": true, "action": "deny" },
    "php": { "active": false, "action": "log" },
    "java": { "active": false, "action": "log" }
  },
  "managedRules": {
    "owasp": { "active": true, "action": "deny" },
    "bot_protection": { "active": true, "action": "challenge" },
    "ai_bots": { "active": true, "action": "deny" }
  },
  "botIdEnabled": true
}
json
{
  "firewallEnabled": true,
  "crs": {
    "sqli": { "active": true, "action": "deny" },
    "xss": { "active": true, "action": "deny" },
    "rce": { "active": true, "action": "deny" },
    "lfi": { "active": true, "action": "deny" },
    "rfi": { "active": true, "action": "deny" },
    "sd": { "active": true, "action": "log" },
    "ma": { "active": true, "action": "deny" },
    "gen": { "active": true, "action": "deny" },
    "sf": { "active": true, "action": "deny" },
    "php": { "active": false, "action": "log" },
    "java": { "active": false, "action": "log" }
  },
  "managedRules": {
    "owasp": { "active": true, "action": "deny" },
    "bot_protection": { "active": true, "action": "challenge" },
    "ai_bots": { "active": true, "action": "deny" }
  },
  "botIdEnabled": true
}

Firewall REST API

Firewall REST API

Base URL: 
https://api.vercel.com
Auth: 
Authorization: Bearer <VERCEL_TOKEN>
Query params: 
?projectId=<id>&teamId=<id>
基础URL：
https://api.vercel.com
认证方式：
Authorization: Bearer <VERCEL_TOKEN>
查询参数：
?projectId=<id>&teamId=<id>

Endpoints

端点

MethodPathDescription
GET
/v1/security/firewall/config/active
Read current config
PATCH
/v1/security/firewall/config
Incremental update (add/remove/update rules)
PUT
/v1/security/firewall/config
Full config replacement
POST
/v1/security/firewall/bypass
Create temporary bypass rule
方法路径描述
GET
/v1/security/firewall/config/active
读取当前配置
PATCH
/v1/security/firewall/config
增量更新（添加/删除/更新规则）
PUT
/v1/security/firewall/config
全量替换配置
POST
/v1/security/firewall/bypass
创建临时绕过规则

PATCH Actions

PATCH动作

ActionDescription
firewallEnabled
Enable/disable firewall (value: boolean)
rules.insert
Add a custom rule
rules.update
Update rule (requires 
id
)
rules.remove
Delete rule (requires 
id
)
rules.priority
Reorder rule (requires 
id
, value = index)
ip.insert
Add IP rule
ip.update
Update IP rule
ip.remove
Delete IP rule
crs.update
Enable/configure OWASP CRS rule
crs.disable
Disable entire CRS
managedRules.update
Configure managed ruleset
动作描述
firewallEnabled
启用/禁用防火墙（值为布尔类型）
rules.insert
添加自定义规则
rules.update
更新规则（需要
id
）
rules.remove
删除规则（需要
id
）
rules.priority
调整规则优先级（需要
id
，值为索引）
ip.insert
添加IP规则
ip.update
更新IP规则
ip.remove
删除IP规则
crs.update
启用/配置OWASP CRS规则
crs.disable
禁用整个CRS规则集
managedRules.update
配置托管规则集

Add a Rule via cURL

通过cURL添加规则

bash
curl -X PATCH "https://api.vercel.com/v1/security/firewall/config?projectId=prj_xxx&teamId=team_xxx" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "rules.insert",
    "value": {
      "name": "Block WordPress scanners",
      "active": true,
      "conditionGroup": [
        {
          "conditions": [
            { "type": "path", "op": "re", "value": "^/wp-(admin|login|content|includes)/" }
          ]
        }
      ],
      "action": { "mitigate": { "action": "deny" } }
    }
  }'
bash
curl -X PATCH "https://api.vercel.com/v1/security/firewall/config?projectId=prj_xxx&teamId=team_xxx" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "rules.insert",
    "value": {
      "name": "Block WordPress scanners",
      "active": true,
      "conditionGroup": [
        {
          "conditions": [
            { "type": "path", "op": "re", "value": "^/wp-(admin|login|content|includes)/" }
          ]
        }
      ],
      "action": { "mitigate": { "action": "deny" } }
    }
  }'

Vercel SDK Usage

Vercel SDK使用示例

ts
import { Vercel } from '@vercel/sdk'

const vercel = new Vercel({ bearerToken: process.env.VERCEL_TOKEN })

// Read current firewall config
const config = await vercel.security.readFirewallConfig({
  configVersion: 'active',
  projectId: 'prj_xxx',
  teamId: 'team_xxx',
})

// Add a rule
await vercel.security.updateFirewallConfig({
  projectId: 'prj_xxx',
  teamId: 'team_xxx',
  requestBody: {
    action: 'rules.insert',
    value: {
      name: 'Rate limit API',
      active: true,
      conditionGroup: [
        { conditions: [{ type: 'path', op: 'pre', value: '/api/' }] },
      ],
      action: {
        mitigate: {
          action: 'rate_limit',
          rateLimit: { algo: 'fixed_window', window: 60, limit: 100, keys: ['ip'], action: 'deny' },
        },
      },
    },
  },
})
ts
import { Vercel } from '@vercel/sdk'

const vercel = new Vercel({ bearerToken: process.env.VERCEL_TOKEN })

// 读取当前防火墙配置
const config = await vercel.security.readFirewallConfig({
  configVersion: 'active',
  projectId: 'prj_xxx',
  teamId: 'team_xxx',
})

// 添加规则
await vercel.security.updateFirewallConfig({
  projectId: 'prj_xxx',
  teamId: 'team_xxx',
  requestBody: {
    action: 'rules.insert',
    value: {
      name: 'Rate limit API',
      active: true,
      conditionGroup: [
        { conditions: [{ type: 'path', op: 'pre', value: '/api/' }] },
      ],
      action: {
        mitigate: {
          action: 'rate_limit',
          rateLimit: { algo: 'fixed_window', window: 60, limit: 100, keys: ['ip'], action: 'deny' },
        },
      },
    },
  },
})

Create Temporary Bypass (Attack Challenge Mode)

创建临时绕过规则（Attack Challenge Mode场景）

bash
curl -X POST "https://api.vercel.com/v1/security/firewall/bypass?projectId=prj_xxx&teamId=team_xxx" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "my-site.com",
    "sourceIp": "198.51.100.42",
    "ttl": 3600000,
    "note": "Temporary bypass for load testing"
  }'
bash
curl -X POST "https://api.vercel.com/v1/security/firewall/bypass?projectId=prj_xxx&teamId=team_xxx" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "my-site.com",
    "sourceIp": "198.51.100.42",
    "ttl": 3600000,
    "note": "Temporary bypass for load testing"
  }'

vercel.json WAF Rules

vercel.json中的WAF规则

Declaratively define firewall rules in 
vercel.json
using the 
mitigate
key:
json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "routes": [
    {
      "src": "/api/(.*)",
      "missing": [
        { "type": "header", "key": "x-internal-token" }
      ],
      "mitigate": { "action": "deny" }
    },
    {
      "src": "/(.*)",
      "has": [
        { "type": "header", "key": "user-agent", "value": "(?i)^curl/" }
      ],
      "mitigate": { "action": "challenge" }
    }
  ]
}
Supported actions in 
vercel.json
: 
"challenge"
, 
"deny"
only. Rate limiting, 
log
, and 
bypass
require the Vercel Firewall dashboard at 
https://vercel.com/{team}/{project}/firewall
or the REST API.
可以通过
mitigate
字段在
vercel.json
中声明式定义防火墙规则：
json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "routes": [
    {
      "src": "/api/(.*)",
      "missing": [
        { "type": "header", "key": "x-internal-token" }
      ],
      "mitigate": { "action": "deny" }
    },
    {
      "src": "/(.*)",
      "has": [
        { "type": "header", "key": "user-agent", "value": "(?i)^curl/" }
      ],
      "mitigate": { "action": "challenge" }
    }
  ]
}
vercel.json
中仅支持
"challenge"
和
"deny"
动作。速率限制、
log
和
bypass
动作需要通过Vercel Firewall控制台（
https://vercel.com/{team}/{project}/firewall
）或REST API配置。

Attack Challenge Mode

Attack Challenge Mode

  • Available on all plans (free)
  • Shows browser verification challenge to all visitors during active attacks
  • Legitimate bots (Googlebot, webhook providers) automatically pass through
  • Internal Function-to-Function calls within the same account bypass automatically
  • Blocked requests don't count toward CDN/traffic usage
  • Configured via dashboard only: open 
    https://vercel.com/{team}/{project}/firewall
    → Bot Management → Attack Challenge Mode
  • 所有套餐均支持（免费）
  • 在攻击活跃期间，向所有访问者显示浏览器验证挑战
  • 合法机器人（如Googlebot、Webhook提供商）可自动通过验证
  • 同一账户内的函数间调用会自动绕过验证
  • 被阻止的请求不计入CDN/流量使用量
  • 仅可通过控制台配置：打开
    https://vercel.com/{team}/{project}/firewall
    → 机器人管理 → Attack Challenge Mode

Plan Availability

套餐可用性

FeatureHobbyProEnterprise
DDoS ProtectionAllAllAll
Custom Rules5401000
Rate Limiting1 rule40 rules1000 rules
Bot Protection (GA)YesYesYes
OWASP CRS——Yes
Token Bucket algo——Yes
Custom rate limit keys——Yes
功能免费版专业版企业版
DDoS防护✅✅✅
自定义规则5条40条1000条
速率限制1条规则40条规则1000条规则
机器人防护（正式版）✅✅✅
OWASP CRS❌❌✅
Token Bucket算法❌❌✅
自定义速率限制维度❌❌✅

Observability

可观测性

  • Security event logs in the Firewall tab
  • IP enrichment — hover any IP in the Firewall dashboard to see ASN, location, and metadata
  • Create custom WAF rules directly from dashboard traffic charts (select "Create Custom Rule" from the actions menu)
  • Linkable to Monitoring queries for investigations
  • DDoS mitigation notifications (alerts on detection)
  • BotID traffic visibility when enabled
  • 防火墙标签页中的安全事件日志
  • IP增强信息——在防火墙控制台中悬停任意IP，可查看ASN、位置和元数据
  • 可直接从控制台流量图表创建自定义WAF规则（从操作菜单中选择“创建自定义规则”）
  • 可关联到监控查询进行调查
  • DDoS缓解通知（检测到攻击时触发警报）
  • 启用BotID后可查看流量可见性数据

Official Documentation

官方文档