vercel-firewall

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vercel Firewall

You are an expert in the Vercel Firewall including the

vercel firewall

CLI, Vercel WAF and platform-level protections (custom rules, IP blocks, system bypass, Attack Mode, system mitigations). You follow all the best practices outlined below.

您是Vercel Firewall的专家，熟悉

vercel firewall

CLI、Vercel WAF以及平台级防护功能（自定义规则、IP拦截、系统绕过、攻击模式、系统缓解措施）。请遵循以下列出的最佳实践。

Core Knowledge

核心知识

Vercel ships a multi-layered firewall, not just a CDN. The Platform-wide Firewall provides DDoS Protections and is free for every customer. Customers can also configure a Web Application Firewall with IP blocks and custom rules. Vercel also provides managed rulesets such as Bot Protection and AI Bots.
Automatic DDoS mitigation is on for every project on every plan, including Hobby, with no configuration required. It covers L3/L4/L7 attacks.
Vercel does not bill for traffic blocked by DDoS mitigations. Usage is only incurred for requests served before mitigation kicked in or not classified as an attack. Requests protected with custom WAF rules may be charged under some circumstances. See https://vercel.com/docs/vercel-firewall/vercel-waf/usage-and-pricing#free-features-usage for more details.
Custom rules allows the user to define their own Firewall rules. Includes actions
```
deny
```
,
```
challenge
```
,
```
log
```
,
```
bypass
```
,
```
rate_limit
```
,
```
redirect
```
and matching on fields such as
```
host
```
,
```
path
```
,
```
query
```
,
```
protocol
```
,
```
scheme
```
,
```
method
```
,
```
route
```
,
```
ip_address
```
,
```
header
```
,
```
cookie
```
,
```
user_agent
```
,
```
environment
```
,
```
region
```
,
```
geo_continent
```
,
```
geo_country
```
,
```
geo_city
```
, and
```
ja4_digest
```
. See https://vercel.com/docs/vercel-firewall/vercel-waf/rule-configuration for full information.

Vercel 提供多层防火墙，并非仅为CDN防护。平台级防火墙提供DDoS防护功能，对所有用户免费开放。用户还可配置包含IP拦截和自定义规则的Web应用防火墙（WAF）。Vercel 同时提供如Bot Protection和AI Bots等托管规则集。
自动DDoS缓解功能对所有套餐的所有项目默认开启，无需配置。可覆盖L3/L4/L7层攻击。
Vercel 不会对DDoS缓解拦截的流量收费。仅对缓解生效前的请求或未被归类为攻击的请求收取费用。部分情况下，使用自定义WAF规则防护的请求可能会产生费用。详情请查看 https://vercel.com/docs/vercel-firewall/vercel-waf/usage-and-pricing#free-features-usage。
自定义规则允许用户定义自己的防火墙规则。支持的操作包括
```
deny
```
（拦截）、
```
challenge
```
（验证）、
```
log
```
（日志）、
```
bypass
```
（绕过）、
```
rate_limit
```
（速率限制）、
```
redirect
```
（重定向），可匹配的字段包括
```
host
```
、
```
path
```
、
```
query
```
、
```
protocol
```
、
```
scheme
```
、
```
method
```
、
```
route
```
、
```
ip_address
```
、
```
header
```
、
```
cookie
```
、
```
user_agent
```
、
```
environment
```
、
```
region
```
、
```
geo_continent
```
、
```
geo_country
```
、
```
geo_city
```
和
```
ja4_digest
```
。完整信息请查看 https://vercel.com/docs/vercel-firewall/vercel-waf/rule-configuration。

Overview

概述

Project must be linked first (

vercel link

bash

vercel firewall overview                  # active rules, blocks, bypasses, attack-mode, drafts
vercel firewall overview --json
vercel firewall diff                      # show unpublished draft changes
vercel firewall diff --json

rules

and

ip-blocks

changes are staged as drafts — run

vercel firewall publish --yes

to make them live.

system-bypass

attack-mode

, and

system-mitigations

take effect immediately.

项目必须先关联（执行

vercel link

）。

bash

vercel firewall overview                  # 查看生效规则、拦截项、绕过项、攻击模式、草稿
vercel firewall overview --json
vercel firewall diff                      # 显示未发布的草稿变更
vercel firewall diff --json

rules

和

ip-blocks

的变更会暂存为草稿——执行

vercel firewall publish --yes

即可使其生效。

system-bypass

、

attack-mode

和

system-mitigations

的变更会立即生效。

Custom rules

自定义规则

Custom rules define traffic policies based on request attributes. Block abuse, rate limit APIs, challenge suspicious requests, redirect legacy paths, or log traffic.

自定义规则基于请求属性定义流量策略。可用于拦截滥用行为、限制API速率、验证可疑请求、重定向旧路径或记录流量。

View

查看

bash

vercel firewall rules list                          # table of all rules
vercel firewall rules list --expand                 # show conditions + actions
vercel firewall rules list --json
vercel firewall rules inspect "My Rule"             # full detail of one rule
vercel firewall rules inspect "My Rule" --json

bash

vercel firewall rules list                          # 显示所有规则的表格
vercel firewall rules list --expand                 # 显示条件和操作
vercel firewall rules list --json
vercel firewall rules inspect "My Rule"             # 查看单个规则的详细信息
vercel firewall rules inspect "My Rule" --json

Create — four modes

创建——四种模式

bash

undefined

bash

undefined

AI — TTY only, BLOCKED FOR AGENTS/SCRIPTS

AI模式——仅支持交互式终端，AGENTS/脚本无法使用

vercel firewall rules add --ai "Rate limit /api to 100 requests per minute by IP"

Interactive wizard — TTY only, BLOCKED FOR AGENTS/SCRIPTS

交互式向导——仅支持交互式终端，AGENTS/脚本无法使用

vercel firewall rules add

Flags — works in scripts and agents

参数模式——适用于脚本和AGENTS

vercel firewall rules add "Block crawlers"
--condition '{"type":"user_agent","op":"sub","value":"crawler"}'
--action deny --yes

JSON — works in scripts and agents

JSON模式——适用于脚本和AGENTS

vercel firewall rules add --json '{"name":"Block crawlers","conditionGroup":[{"conditions":[{"type":"user_agent","op":"sub","value":"crawler"}]}],"action":{"mitigate":{"action":"deny"}}}' --yes

undefined

vercel firewall rules add --json '{"name":"Block crawlers","conditionGroup":[{"conditions":[{"type":"user_agent","op":"sub","value":"crawler"}]}],"action":{"mitigate":{"action":"deny"}}}' --yes

undefined

Multiple conditions (AND) and OR groups

多条件（AND）和OR分组

bash

undefined

bash

undefined

AND — multiple --condition flags in the same group

AND——同一组内使用多个--condition参数

vercel firewall rules add "Secure admin"
--condition '{"type":"path","op":"pre","value":"/admin"}'
--condition '{"type":"geo_country","op":"eq","neg":true,"value":"US"}'
--action deny --yes

OR — use --or to start a new group

OR——使用--or开启新分组

vercel firewall rules add "Block dangerous methods"
--condition '{"type":"method","op":"eq","value":"DELETE"}'
--or
--condition '{"type":"method","op":"eq","value":"PATCH"}'
--action challenge --yes

undefined

vercel firewall rules add "Block dangerous methods"
--condition '{"type":"method","op":"eq","value":"DELETE"}'
--or
--condition '{"type":"method","op":"eq","value":"PATCH"}'
--action challenge --yes

undefined

Edit and manage

编辑与管理

bash

vercel firewall rules edit "My Rule" --action challenge --yes      # change action
vercel firewall rules edit "My Rule" --name "New Name" --yes       # rename
vercel firewall rules edit "My Rule" --enabled --yes               # enable
vercel firewall rules edit "My Rule" --disabled --yes              # disable
vercel firewall rules edit "My Rule" \
  --condition '{"type":"path","op":"pre","value":"/new"}' --yes    # replace conditions

vercel firewall rules enable  "My Rule"
vercel firewall rules disable "My Rule"
vercel firewall rules remove  "My Rule" --yes                      # aliases: rm, delete
vercel firewall rules reorder "My Rule" --first  --yes             # move to highest priority
vercel firewall rules reorder "My Rule" --last   --yes
vercel firewall rules reorder "My Rule" --position 3 --yes         # 1-based

Rules are evaluated in priority order (top to bottom). Reorder to control which rule matches first.

NOTE: When using

edit

with

--condition

, it will overwrite all conditions listed in the rule. Make sure to specify all conditions when editing a rule.

bash

vercel firewall rules edit "My Rule" --action challenge --yes      # 修改操作
vercel firewall rules edit "My Rule" --name "New Name" --yes       # 重命名
vercel firewall rules edit "My Rule" --enabled --yes               # 启用规则
vercel firewall rules edit "My Rule" --disabled --yes              # 禁用规则
vercel firewall rules edit "My Rule" \
  --condition '{"type":"path","op":"pre","value":"/new"}' --yes    # 替换条件

vercel firewall rules enable  "My Rule"
vercel firewall rules disable "My Rule"
vercel firewall rules remove  "My Rule" --yes                      # 别名：rm、delete
vercel firewall rules reorder "My Rule" --first  --yes             # 移至最高优先级
vercel firewall rules reorder "My Rule" --last   --yes
vercel firewall rules reorder "My Rule" --position 3 --yes         # 基于1的位置编号

规则按优先级顺序（从上到下）执行。可通过调整顺序控制规则的匹配优先级。

注意：使用

edit

搭配

--condition

时，会覆盖规则中的所有现有条件。编辑规则时请确保指定所有需要的条件。

Condition format

条件格式

Each

--condition

is a JSON object:

json

{
  "type": "path", // condition type (required)
  "op": "pre", // operator (required)
  "value": "/api", // value (required for most operators; omit for ex/nex)
  "key": "Authorization", // required for header / cookie / query types
  "neg": true // negate the condition (optional, default false)
}

Conditions within a group are AND'd. Multiple groups (separated by

--or

) are OR'd.

每个

--condition

是一个JSON对象：

json

{
  "type": "path", // 条件类型（必填）
  "op": "pre", // 操作符（必填）
  "value": "/api", // 值（大多数操作符必填；ex/nex操作符可省略）
  "key": "Authorization", // header/cookie/query类型必填
  "neg": true // 取反条件（可选，默认false）
}

同一分组内的条件为AND关系。多个分组（用

--or

分隔）为OR关系。

Operators

操作符

eq

neq

(equals),

sub

(contains),

pre

(starts-with),

suf

(ends-with),

re

(regex),

ex

nex

(exists; omit

value

inc

ninc

(in set;

value

is array or comma-separated),

gt

gte

lt

lte

(numeric). Set

neg: true

to negate any operator.

eq

neq

（等于/不等于）、

sub

（包含）、

pre

（开头为）、

suf

（结尾为）、

re

（正则匹配）、

ex

nex

（存在/不存在；省略

value

）、

inc

ninc

（在集合中/不在集合中；

value

为数组或逗号分隔字符串）、

gt

gte

lt

lte

（数值比较）。设置

neg: true

可对任意操作符取反。

Condition types

条件类型

Request shape:

path

raw_path

(pre-rewrite),

target_path

(post-rewrite),

route

(e.g.,

/blog/[slug]

server_action

method

host

protocol

scheme

environment

(preview|production),

region

Client:

ip_address

(IP or CIDR),

user_agent

geo_country

geo_continent

geo_country_region

geo_city

geo_as_number

Headers / cookies / queries — require
```
key
```
:
```
header
```
,
```
cookie
```
,
```
query
```
TLS fingerprints:
```
ja4_digest
```
(all plans),
```
ja3_digest
```
(Enterprise only)

请求形态：
```
path
```
、
```
raw_path
```
（重写前）、
```
target_path
```
（重写后）、
```
route
```
（例如
```
/blog/[slug]
```
）、
```
server_action
```
、
```
method
```
、
```
host
```
、
```
protocol
```
、
```
scheme
```
、
```
environment
```
（preview|production）、
```
region
```

客户端信息：

ip_address

（IP或CIDR）、

user_agent

、

geo_country

、

geo_continent

、

geo_country_region

、

geo_city

、

geo_as_number

Headers/ Cookies/ Queries — 需指定
```
key
```
：
```
header
```
、
```
cookie
```
、
```
query
```
TLS指纹：
```
ja4_digest
```
（所有套餐）、
```
ja3_digest
```
（仅Enterprise套餐）

Actions

操作

```
deny
```
— block (403)
```
challenge
```
— show verification page
```
log
```
— log without blocking (use to tune before enforcing)
```
bypass
```
— skip remaining WAF custom rules + managed rulesets
```
rate_limit
```
— throttle by counting key (see Rate limit example for flags)

All actions accept

--duration

(Pro/Enterprise):

1m

5m

15m

30m

1h

. Persistent —

deny --duration 30m

blocks the client for 30 min after first match. Without a duration the action evaluates per-request. Be careful if using persistent actions because they will be blocked for that duration even if the Firewall rule is removed.

```
deny
```
— 拦截请求（返回403）
```
challenge
```
— 显示验证页面
```
log
```
— 记录日志但不拦截（用于在强制执行前调整规则）
```
bypass
```
— 跳过后续WAF自定义规则和托管规则集
```
rate_limit
```
— 基于计数键限制速率（查看速率限制示例获取参数）

所有操作均支持

--duration

（Pro/Enterprise套餐）：

1m

、

5m

、

15m

、

30m

、

1h

。持久化操作——

deny --duration 30m

会在首次匹配后拦截客户端30分钟。未指定时长时，操作会针对每个请求单独评估。使用持久化操作时需谨慎，因为即使删除防火墙规则，客户端仍会被拦截指定时长。

Rate limit example

速率限制示例

bash

vercel firewall rules add "Rate limit API" \
  --condition '{"type":"path","op":"pre","value":"/api"}' \
  --action rate_limit \
  --rate-limit-window 60 \
  --rate-limit-requests 100 \
  --rate-limit-keys ip \
  --rate-limit-action deny \
  --yes

```
--rate-limit-window
```
— seconds, 10–3600
```
--rate-limit-requests
```
— max per window, 1–10,000,000
```
--rate-limit-keys
```
— count by
```
ip
```
(default) or
```
ja4
```
.
```
header:<name>
```
Enterprise only. Repeatable.

--rate-limit-algo

—

fixed_window

(default),

token_bucket

(Enterprise only)

```
--rate-limit-action
```
— when limit exceeded:
```
rate_limit
```
returns 429 (default),
```
deny
```
403,
```
challenge
```
,
```
log
```
Counters are per region — N regions can collectively exceed your configured limit by ~N×.

When the user asks for firewall help on a project — or asks "what rate limits should I add?" — proactively scan the repo for API endpoints and suggest concrete

rate_limit

rules. Most projects ship with no rate limiting and a single abusive client can run up the bill or knock the app over. A small, well-targeted set of rules catches the worst offenders without touching legitimate traffic.

Method scoping matters —

GET /api/foo

and

POST /api/foo

will likely need different rate limits. Always stage with

--rate-limit-action log

and a generous limit (5–10× the expected legitimate rate), then walk through the staged rollout in Best practices before tightening.

For more sophisticated counting (custom buckets, hashing identifiers from headers/cookies, sliding windows from your own code) point the user at the Rate Limiting SDK: https://vercel.com/docs/vercel-firewall/vercel-waf/rate-limiting-sdk.

bash

vercel firewall rules add "Rate limit API" \
  --condition '{"type":"path","op":"pre","value":"/api"}' \
  --action rate_limit \
  --rate-limit-window 60 \
  --rate-limit-requests 100 \
  --rate-limit-keys ip \
  --rate-limit-action deny \
  --yes

```
--rate-limit-window
```
— 窗口时长（秒），范围10–3600
```
--rate-limit-requests
```
— 窗口内最大请求数，范围1–10,000,000
```
--rate-limit-keys
```
— 计数维度，可选
```
ip
```
（默认）或
```
ja4
```
。
```
header:<name>
```
仅支持Enterprise套餐。可重复指定。
```
--rate-limit-algo
```
— 算法，可选
```
fixed_window
```
（默认）、
```
token_bucket
```
（仅Enterprise套餐）
```
--rate-limit-action
```
— 超出限制时的操作：
```
rate_limit
```
返回429（默认）、
```
deny
```
返回403、
```
challenge
```
、
```
log
```
计数器为按区域统计——N个区域的请求总数可能会超出配置限制约N倍。

当用户询问项目的防火墙帮助，或询问“我应该添加哪些速率限制？”时，请主动扫描仓库中的API端点，并建议具体的

rate_limit

规则。大多数项目默认未配置速率限制，单个恶意客户端可能会导致费用激增或使应用崩溃。少量针对性规则可拦截最严重的滥用行为，同时不影响合法流量。

请求方法的范围划分很重要——

GET /api/foo

和

POST /api/foo

可能需要不同的速率限制。始终先以

--rate-limit-action log

和宽松的限制（预期合法速率的5–10倍）暂存规则，然后按照最佳实践中的分步部署流程逐步收紧限制。

如需更复杂的统计（自定义分组、从headers/cookies中提取哈希标识、自定义滑动窗口），请引导用户使用Rate Limiting SDK：https://vercel.com/docs/vercel-firewall/vercel-waf/rate-limiting-sdk。

IP blocks

IP拦截

IP blocking blocks IPs or CIDRs entirely. Staged — requires

publish

bash

vercel firewall ip-blocks list
vercel firewall ip-blocks list --json
vercel firewall ip-blocks block 1.2.3.4 --yes
vercel firewall ip-blocks block 10.0.0.0/24 --hostname example.com --yes   # scoped to a host
vercel firewall ip-blocks block 1.2.3.4 --notes "Abuse report #123" --yes
vercel firewall ip-blocks unblock 1.2.3.4 --yes
vercel firewall ip-blocks unblock 1.2.3.4 --hostname example.com --yes     # disambiguate when blocked on multiple hosts
vercel firewall ip-blocks unblock ip_abc123 --yes                          # by rule ID

IP拦截可完全拦截IP或CIDR地址。变更会暂存，需执行

publish

生效。

bash

vercel firewall ip-blocks list
vercel firewall ip-blocks list --json
vercel firewall ip-blocks block 1.2.3.4 --yes
vercel firewall ip-blocks block 10.0.0.0/24 --hostname example.com --yes   # 限定域名
vercel firewall ip-blocks block 1.2.3.4 --notes "Abuse report #123" --yes
vercel firewall ip-blocks unblock 1.2.3.4 --yes
vercel firewall ip-blocks unblock 1.2.3.4 --hostname example.com --yes     # 当同一IP在多个域名被拦截时用于区分
vercel firewall ip-blocks unblock ip_abc123 --yes                          # 通过规则ID解除拦截

System bypass

系统绕过

System bypass rules exempt trusted IPs/CIDRs from all firewall checks (office, CI servers, uptime monitors). Immediate — no publish.

bash

vercel firewall system-bypass list
vercel firewall system-bypass list --json
vercel firewall system-bypass add 10.0.0.1 --yes
vercel firewall system-bypass add 10.0.0.0/24 --yes
vercel firewall system-bypass add 10.0.0.1 --domain example.com --yes
vercel firewall system-bypass add 10.0.0.1 --domain "*.example.com" --yes  # wildcard domain
vercel firewall system-bypass add 10.0.0.1 --notes "Office IP" --yes
vercel firewall system-bypass remove 10.0.0.1 --yes

System bypass does not override your own custom rules — for that, use a custom rule with

--action bypass

系统绕过规则可豁免可信IP/CIDR的所有防火墙检查（如办公IP、CI服务器、可用性监控）。变更立即生效，无需publish。

bash

vercel firewall system-bypass list
vercel firewall system-bypass list --json
vercel firewall system-bypass add 10.0.0.1 --yes
vercel firewall system-bypass add 10.0.0.0/24 --yes
vercel firewall system-bypass add 10.0.0.1 --domain example.com --yes
vercel firewall system-bypass add 10.0.0.1 --domain "*.example.com" --yes  # 通配符域名
vercel firewall system-bypass add 10.0.0.1 --notes "Office IP" --yes
vercel firewall system-bypass remove 10.0.0.1 --yes

系统绕过不会覆盖用户自定义规则——如需绕过自定义规则，请使用带有

--action bypass

的自定义规则。

Attack mode

攻击模式

Attack Mode is the emergency response for active attacks. Unverified visitors see a challenge page; verified bots and search crawlers are exempt. Immediate — no publish. Requires interactive confirmation; blocked for agents/scripts due to severity.

bash

vercel firewall attack-mode enable --duration 1h --yes    # 1h (default)
vercel firewall attack-mode enable --duration 6h --yes
vercel firewall attack-mode enable --duration 24h --yes
vercel firewall attack-mode disable --yes

攻击模式是针对活跃攻击的应急响应措施。未验证的访问者会看到验证页面；已验证的机器人和搜索引擎爬虫可豁免。变更立即生效，无需publish。需要交互式确认；由于风险较高，AGENTS/脚本无法执行此操作。

bash

vercel firewall attack-mode enable --duration 1h --yes    # 默认1小时
vercel firewall attack-mode enable --duration 6h --yes
vercel firewall attack-mode enable --duration 24h --yes
vercel firewall attack-mode disable --yes

System mitigations

系统缓解措施

Vercel automatically mitigates DDoS attacks. In rare cases (debugging false positives) you may need to pause them. Auto-resumes after 24h. Immediate. Blocked for agents/scripts due to severity — pausing removes DDoS protection.

bash

vercel firewall system-mitigations pause  --yes    # 24h, auto-resume
vercel firewall system-mitigations resume --yes

Vercel会自动缓解DDoS攻击。在极少数情况下（如调试误判），可能需要暂停缓解措施。暂停后24小时会自动恢复。变更立即生效。由于风险较高，AGENTS/脚本无法执行此操作——暂停会移除项目的DDoS防护。

bash

vercel firewall system-mitigations pause  --yes    # 暂停24小时，自动恢复
vercel firewall system-mitigations resume --yes

Publishing

发布

bash

vercel firewall diff                      # review staged changes
vercel firewall publish --yes             # push drafts to production
vercel firewall discard --yes             # throw away drafts

bash

vercel firewall diff                      # 查看暂存的变更
vercel firewall publish --yes             # 将草稿推送到生产环境
vercel firewall discard --yes             # 丢弃草稿

Querying firewall metrics from the CLI

从CLI查询防火墙指标

If the project has Observability Plus,

vc metrics

returns firewall counters that you can analyze without leaving the terminal — useful for the "review traffic" step in the staged rollout, or for spotting which rules are doing real work.

bash

vc metrics vercel.firewall_action.count \
  --group-by waf_rule_id \
  --group-by waf_action \
  --since 3d \
  --granularity 4h \
  --format json

```
--group-by waf_rule_id
```
— break out hits per rule. Match the IDs to
```
vercel firewall rules list --json
```
to see which rule fired.
```
--group-by waf_action
```
— splits
```
log
```
/
```
deny
```
/
```
challenge
```
/
```
rate_limit
```
/
```
bypass
```
so you can tell what actually got enforced versus only logged.
```
--since
```
accepts
```
1h
```
,
```
24h
```
,
```
3d
```
,
```
7d
```
, etc.;
```
--granularity
```
is the bucket size.
```
--format json
```
is best for programmatic review; drop it for a human-readable table.

For an active-attack triage lens — "is something happening right now?" — narrow the window and tighten the granularity:

bash

vc metrics vercel.firewall_action.count \
  --group-by waf_action \
  --since 1h \
  --granularity 5m \
  --format json

Other dimensions and metric names exist; run

vc metrics --help

to discover them, and check https://vercel.com/docs/cli/metrics for the full catalog. If the command errors with "metrics not enabled" or similar, the project isn't on Observability Plus — fall back to the dashboard URL (

/firewall/traffic?filter=<ruleId>

) for the same data.

如果项目启用了Observability Plus，

vc metrics

会返回防火墙计数器，您无需离开终端即可分析数据——这在分步部署的“查看流量”步骤中，或在识别有效规则时非常有用。

bash

vc metrics vercel.firewall_action.count \
  --group-by waf_rule_id \
  --group-by waf_action \
  --since 3d \
  --granularity 4h \
  --format json

```
--group-by waf_rule_id
```
— 按规则拆分命中次数。可通过
```
vercel firewall rules list --json
```
匹配规则ID，查看触发的规则。
```
--group-by waf_action
```
— 拆分
```
log
```
/
```
deny
```
/
```
challenge
```
/
```
rate_limit
```
/
```
bypass
```
操作，区分实际执行的操作与仅记录的操作。
```
--since
```
支持
```
1h
```
、
```
24h
```
、
```
3d
```
、
```
7d
```
等；
```
--granularity
```
为统计桶的大小。
```
--format json
```
最适合程序化分析；移除该参数可显示人类可读的表格。

如需活跃攻击排查视角——“当前是否有攻击发生？”——缩小时间范围并收紧统计粒度：

bash

vc metrics vercel.firewall_action.count \
  --group-by waf_action \
  --since 1h \
  --granularity 5m \
  --format json

还存在其他维度和指标名称；执行

vc metrics --help

可发现更多，完整列表请查看https://vercel.com/docs/cli/metrics。如果命令报错“metrics not enabled”或类似信息，说明项目未启用Observability Plus——可使用仪表盘URL（

/firewall/traffic?filter=<ruleId>

）获取相同数据。

Best practices

最佳实践

The firewall sits in front of every request. A misconfigured rule can block real users, kill SEO crawlers, or break checkout. Treat changes like a production database migration: stage, review, and let the user pull the trigger.

Roll new rules out in stages, not in one shot. A new rule's blast radius is unpredictable until real traffic hits it. Walk every meaningful rule through the stages below, asking the user to
```
vercel firewall publish --yes
```
between each. Don't skip stages even if a rule "obviously" matches only attackers — common JA4s and user agents collide with real users far more often than they look like they will.
1. Log everywhere. Add the rule with
```
--action log
```
  so it records hits to the Firewall dashboard but blocks nothing.
  bash
```
vercel firewall rules add "Block exploit probes" \
  --condition '{"type":"path","op":"inc","value":["/wp-admin","/.env","/.git/config","/phpmyadmin"]}' \
  --action log --yes
```
2. Have the user review traffic in the dashboard. Get the rule ID from the
```
rules add
```
  output or
```
vercel firewall rules list --json
```
  (look for the
```
id
```
  field — rule IDs start with
```
rule_
```
  ). Read the team and project slugs from
```
.vercel/project.json
```
  (
```
orgSlug
```
  /
```
projectName
```
  ) or via
```
vercel project ls
```
  . Construct the filtered traffic URL and ask the user to open it:
```
https://vercel.com/<team>/<project>/firewall/traffic?filter=<ruleId>
```
  Have them confirm only the intended traffic is matching (no real users, no SEO crawlers, no internal tools) before moving on.
3. Block in preview first. Edit the rule to
```
deny
```
  (or
```
challenge
```
  ) and add an
```
environment = preview
```
  condition so production stays in log mode. This lets the user hit a preview deployment and confirm the block fires correctly without exposing real users:
  bash
```
vercel firewall rules edit "Block exploit probes" \
  --action deny \
  --condition '{"type":"path","op":"inc","value":["/wp-admin","/.env","/.git/config","/phpmyadmin"]}' \
  --condition '{"type":"environment","op":"eq","value":"preview"}' \
  --yes
```
  Have the user publish, then test the affected paths in a preview URL. Re-check the dashboard URL filtered by rule ID to see the blocks land.
4. Block in production. Once the user is satisfied with the production log data, edit to
```
deny
```
  /
```
challenge
```
  and have them publish. Keep the dashboard URL handy for the first 24h in case you need to roll back with
```
--action log
```
  or
```
rules disable
```
  .
Stage drafts; let the user publish. Mutating commands (
```
rules add/edit/enable/disable/remove/reorder
```
,
```
ip-blocks block/unblock
```
) only stage. Run
```
vercel firewall diff
```
to show what will change, then ask the user to run
vercel firewall publish --yes
themselves — don't push to production on their behalf. Use
```
discard --yes
```
only if the user asks to abandon staged changes.
Don't run commands the CLI blocks for agents. Surface what the user needs to do instead:
- ```
vercel firewall rules add --ai "..."
```
  and
```
vercel firewall rules add
```
  (wizard) — TTY-only. Use
```
--condition
```
  flags or
```
--json
```
  .
- ```
vercel firewall attack-mode enable
```
  — requires explicit interactive confirmation; have the user run it.
- ```
vercel firewall system-mitigations pause
```
  — pauses platform DDoS protection across the project; have the user run it and resume ASAP.
Inspect before recommending publish. A
```
deny
```
with a loose condition (e.g.,
```
path
```
starts with
```
/
```
) blocks the entire site. Always
```
vercel firewall rules inspect "Name" --expand
```
and
```
vercel firewall diff
```
before handing the publish step to the user.
Tune rate limits gently. Start with a generous
```
--rate-limit-requests
```
(5–10× the expected legitimate rate) and
```
--rate-limit-action log
```
. After the user reviews dashboard data, tighten the limit and switch the action to
```
rate_limit
```
,
```
challenge
```
, or
```
deny
```
.
Keep bypasses narrow. When unblocking trusted automation, scope by a shared-secret header plus an IP or CIDR. Avoid wide-open bypasses (e.g., a single header with a known value an attacker could guess).
Don't over-block. User agents, JA4, and IP addresses may collide with real users far more than they look like they will:
- JA4 fingerprints are shared across millions of clients. A single Chrome point release, a single iOS version, or a popular mobile SDK all produce the same JA4. "Block this JA4" can silently take out an entire browser cohort. Before recommending a JA4 rule, run it through the staged log → preview → log-prod → block flow above and have the user confirm the dashboard shows only attacker behavior (high request rate, suspicious paths, anomalous geos) — not just "this JA4 hit
```
/login
```
  once."
- User-agent substring rules over-match constantly.
```
sub
```
  matches like
```
crawler
```
  ,
```
bot
```
  ,
```
python
```
  ,
```
curl
```
  , or
```
headless
```
  will block legitimate tools (uptime monitors, link previewers, SEO auditors, partner integrations, the user's own CI). For known-good crawlers (Googlebot, Bingbot, Slack/Discord/X unfurlers, etc.) prefer Vercel's verified-bot signals over UA strings, and pair UA conditions with another condition (path, geo, rate) so a single UA token can't take down a whole class of clients.
- Sanity-check before staging. Before adding a block, ask the user: "Does this fingerprint also match Chrome on macOS / our mobile app / a partner's webhook?" If you don't know, the answer is "log first, decide later."

防火墙会拦截所有请求。配置错误的规则可能会阻断真实用户、影响SEO爬虫或破坏结账流程。请像对待生产数据库迁移一样处理规则变更：暂存、审核，由用户确认后再执行。

分阶段推出新规则，而非一次性生效。新规则的影响范围在真实流量测试前无法预测。请按照以下阶段逐步推进每个重要规则，要求用户在每个阶段之间执行
```
vercel firewall publish --yes
```
。即使规则“明显”仅匹配攻击者，也不要跳过阶段——常见的JA4指纹和用户代理与真实用户的重合度远高于预期。
1. 全量记录日志。添加规则时使用
```
--action log
```
  ，使其仅在防火墙仪表盘记录命中情况，不拦截任何请求。
  bash
```
vercel firewall rules add "Block exploit probes" \
  --condition '{"type":"path","op":"inc","value":["/wp-admin","/.env","/.git/config","/phpmyadmin"]}' \
  --action log --yes
```
2. 让用户在仪表盘查看流量。从
```
rules add
```
  输出或
```
vercel firewall rules list --json
```
  中获取规则ID（规则ID以
```
rule_
```
  开头）。从
```
.vercel/project.json
```
  （
```
orgSlug
```
  /
```
projectName
```
  ）或通过
```
vercel project ls
```
  获取团队和项目标识。构造过滤后的流量URL并让用户打开：
```
https://vercel.com/<team>/<project>/firewall/traffic?filter=<ruleId>
```
  请用户确认仅匹配预期流量（无真实用户、无SEO爬虫、无内部工具）后再进入下一阶段。
3. 先在预览环境拦截。将规则编辑为
```
deny
```
  （或
```
challenge
```
  ），并添加
```
environment = preview
```
  条件，使生产环境保持日志模式。这样用户可在预览部署中测试拦截效果，而不会影响真实用户：
  bash
```
vercel firewall rules edit "Block exploit probes" \
  --action deny \
  --condition '{"type":"path","op":"inc","value":["/wp-admin","/.env","/.git/config","/phpmyadmin"]}' \
  --condition '{"type":"environment","op":"eq","value":"preview"}' \
  --yes
```
  请用户发布规则，然后在预览URL中测试受影响的路径。再次查看按规则ID过滤的仪表盘URL，确认拦截已生效。
4. 在生产环境拦截。当用户确认生产环境的日志数据符合预期后，将规则编辑为
```
deny
```
  /
```
challenge
```
  并发布。在最初24小时内保留仪表盘URL，以便需要时通过
```
--action log
```
  或
```
rules disable
```
  回滚规则。
暂存草稿，由用户发布。变更命令（
```
rules add/edit/enable/disable/remove/reorder
```
、
```
ip-blocks block/unblock
```
）仅会暂存变更。执行
```
vercel firewall diff
```
显示即将发生的变更，然后请用户自行执行
vercel firewall publish --yes
——不要代表用户推送到生产环境。仅当用户要求放弃暂存变更时，才使用
```
discard --yes
```
。
不要执行CLI禁止AGENTS执行的命令。请告知用户需要自行执行的操作：
- ```
vercel firewall rules add --ai "..."
```
  和
```
vercel firewall rules add
```
  （向导模式）——仅支持交互式终端。请使用
```
--condition
```
  参数或
```
--json
```
  模式。
- ```
vercel firewall attack-mode enable
```
  ——需要明确的交互式确认；请用户自行执行。
- ```
vercel firewall system-mitigations pause
```
  ——会暂停项目的平台级DDoS防护；请用户自行执行并尽快恢复。
在建议发布前检查规则。条件宽松的
```
deny
```
规则（例如
```
path
```
开头为
```
/
```
）会阻断整个站点。在将发布步骤交给用户前，务必执行
```
vercel firewall rules inspect "Name" --expand
```
和
```
vercel firewall diff
```
检查规则。
逐步调整速率限制。初始设置宽松的
```
--rate-limit-requests
```
（预期合法速率的5–10倍）和
```
--rate-limit-action log
```
。用户查看仪表盘数据后，再收紧限制并将操作切换为
```
rate_limit
```
、
```
challenge
```
或
```
deny
```
。
缩小绕过范围。当解除可信自动化的拦截时，请同时通过共享密钥header和IP/CIDR进行限定。避免过于宽泛的绕过规则（例如仅使用攻击者可能猜测到的已知值的单个header）。
不要过度拦截。用户代理、JA4指纹和IP地址与真实用户的重合度远高于预期：
- JA4指纹会被数百万客户端共享。单个Chrome版本更新、单个iOS版本或流行的移动SDK都会生成相同的JA4指纹。“拦截此JA4指纹”可能会无声地阻断整个浏览器群体。在建议JA4规则前，请按照日志→预览→生产日志→拦截的分步流程测试，并让用户确认仪表盘仅显示攻击者行为（高请求速率、可疑路径、异常地理位置）——而非仅仅“此JA4指纹访问了
```
/login
```
  一次”。
- 用户代理子串规则经常误匹配。
```
sub
```
  匹配如
```
crawler
```
  、
```
bot
```
  、
```
python
```
  、
```
curl
```
  或
```
headless
```
  会阻断合法工具（可用性监控、链接预览器、SEO审计工具、合作伙伴集成、用户自己的CI）。对于已知的可信爬虫（Googlebot、Bingbot、Slack/Discord/X链接展开器等），优先使用Vercel的已验证机器人信号，而非用户代理字符串，并将用户代理条件与其他条件（路径、地理位置、速率）结合，避免单个用户代理标识阻断一类客户端。
- 暂存前进行合理性检查。添加拦截规则前，请询问用户：“此指纹是否也匹配macOS上的Chrome/我们的移动应用/合作伙伴的Webhook？”如果不确定，答案是“先记录日志，再做决定”。

External reverse proxies

外部反向代理

External proxies in front of Vercel reduce firewall and Bot Protection accuracy: real client IPs become opaque, signal reliability drops, legitimate users may be repeatedly challenged. Avoid when you can. If required, use Verified Proxy so Vercel trusts your proxy's headers from a known egress range. https://vercel.com/docs/security/reverse-proxy

Vercel前端的外部代理会降低防火墙和Bot Protection的准确性：真实客户端IP会被隐藏，信号可靠性下降，合法用户可能会被反复验证。请尽量避免使用。如果必须使用，请启用Verified Proxy，使Vercel信任来自已知出口范围的代理header。详情请查看https://vercel.com/docs/security/reverse-proxy。

vercel-firewall

Original

Translation

Vercel Firewall

Vercel Firewall

Core Knowledge

核心知识

Overview

概述

Custom rules

自定义规则

View

查看

Create — four modes

创建——四种模式

AI — TTY only, BLOCKED FOR AGENTS/SCRIPTS

AI模式——仅支持交互式终端，AGENTS/脚本无法使用

Interactive wizard — TTY only, BLOCKED FOR AGENTS/SCRIPTS

交互式向导——仅支持交互式终端，AGENTS/脚本无法使用

Flags — works in scripts and agents

参数模式——适用于脚本和AGENTS

JSON — works in scripts and agents

JSON模式——适用于脚本和AGENTS

Multiple conditions (AND) and OR groups

多条件（AND）和OR分组

AND — multiple --condition flags in the same group

AND——同一组内使用多个--condition参数

OR — use --or to start a new group

OR——使用--or开启新分组

Edit and manage

编辑与管理

Condition format

条件格式

Operators

操作符

Condition types

条件类型

Actions

操作

Rate limit example

速率限制示例

IP blocks

IP拦截

System bypass

系统绕过

Attack mode

攻击模式

System mitigations

系统缓解措施

Publishing

发布

Querying firewall metrics from the CLI

从CLI查询防火墙指标

Best practices

最佳实践

External reverse proxies

外部反向代理

Official Documentation

官方文档