---
name: vercel-firewall
description: Vercel Firewall expert guidance — automatic DDoS mitigation, the Vercel WAF (custom rules, IP blocking, managed rulesets, rate limiting), Attack Mode, system bypass, bot management, and the `vercel firewall` CLI. Use when configuring platform-level security, responding to attacks, or staging firewall rules.
metadata:
  priority: 7
  docs:
    - 'https://vercel.com/docs/vercel-firewall'
    - 'https://vercel.com/docs/cli/firewall'
  bashPatterns:
    - '\bvercel\s+firewall\b'
  promptSignals:
    phrases:
      - 'vercel firewall'
      - 'vercel waf'
      - 'attack mode'
      - 'ddos protection'
      - 'ip block'
      - 'managed ruleset'
      - 'bot protection'
      - 'system bypass'
      - 'rate limit rule'
      - 'ai bots'
      - 'ai crawler'
      - 'verified bot'
    allOf:
      - [ firewall, vercel ]
      - [ waf, vercel ]
      - [ ddos, vercel ]
      - [ challenge, vercel ]
      - [ 'rate limit', vercel ]
      - [ 'system bypass', vercel ]
      - [ 'ip block', vercel ]
    noneOf: []
    minScore: 6
retrieval:
  aliases:
    - ddos protection
    - waf rules
    - bot protection
    - rate limiting
    - attack mode
    - ip allowlist
    - traffic filtering
    - verified bots
  intents:
    - protect from ddos
    - block malicious traffic
    - configure firewall
    - rate limit api
    - allow bot through firewall
    - enable attack mode
    - publish firewall rule
  entities:
    - Vercel Firewall
    - Vercel WAF
    - DDoS
    - Attack Mode
    - Bot Protection
    - Managed Rulesets
    - System Bypass
    - JA3
    - JA4
title: vercel-firewall
canonical_url: https://skilld.dev/gh/vercel/vercel-plugin/vercel-firewall
last_updated: 2026-11-18T19:13:53.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [.vercel.approvers](https://skilld.dev/api/skills-raw/vercel/vercel-plugin/vercel-firewall/.vercel.approvers).
>
> If the user asked to install this Skill, run `npx skilld install vercel/vercel-plugin/vercel-firewall`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/vercel-firewall`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/vercel/vercel-plugin/vercel-firewall) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/vercel-firewall`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/vercel-firewall --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/vercel-firewall --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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](#best-practices) outlined below.

## 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 or WAF.** Usage is only incurred for requests served before mitigation kicked in or not classified as an attack. You do not pay for requests or bandwidth for denies, challenges, or rate-limits from WAF custom rules or managed rules.
- **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.

## 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**.

## Custom rules

[Custom rules](https://vercel.com/docs/vercel-firewall/vercel-waf/custom-rules) define traffic policies based on request attributes. Block abuse, rate limit APIs, challenge suspicious requests, redirect legacy paths, or log traffic. Rules can also be defined declaratively in `vercel.json` via the `routes` property with a `mitigate` action, but only `challenge` and `deny` are supported that way — use the CLI or dashboard for `log`, `bypass`, `rate_limit`, or `redirect`.

### 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
```

### Create — four modes

```bash
# AI — TTY only, BLOCKED FOR AGENTS/SCRIPTS
vercel firewall rules add --ai "Rate limit /api to 100 requests per minute by IP"

# Interactive wizard — TTY only, BLOCKED FOR AGENTS/SCRIPTS
vercel firewall rules add

# Flags — works in scripts and agents
vercel firewall rules add "Block crawlers" \
  --condition '{"type":"user_agent","op":"sub","value":"crawler"}' \
  --action deny --yes

# JSON payload — works in scripts and agents (`--data` needs CLI 64.2+; older CLIs use `--json <payload>`)
vercel firewall rules add --data '{"name":"Block crawlers","conditionGroup":[{"conditions":[{"type":"user_agent","op":"sub","value":"crawler"}]}],"action":{"mitigate":{"action":"deny"}}}' --yes
```

### Multiple conditions (AND) and OR groups

```bash
# AND — multiple --condition flags in the same group
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
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
```

### Update and manage

`rules update` needs CLI 64.4+; older CLIs use `rules edit`, which still works as a deprecated alias.

```bash
vercel firewall rules update "My Rule" --action challenge --yes    # change action
vercel firewall rules update "My Rule" --name "New Name" --yes     # rename
vercel firewall rules update "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 move    "My Rule" --first  --yes             # move to highest priority; alias: reorder (deprecated)
vercel firewall rules move    "My Rule" --last   --yes
vercel firewall rules move    "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 `update` with `--condition`, it will overwrite all conditions listed in the rule. Make sure to specify all conditions when editing a rule.

### 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**.

### 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.

### 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)
- **Bots**: `bot_name`, `bot_category` (public beta, priority projects only; see [Bot management](#bot-management))
- **Rate limit grouping**: `rate_limit_api_id`

### Actions

- `deny` — block (403)
- `challenge` — show verification page
- `log` — log without blocking (use to tune before enforcing)
- `bypass` — skip remaining WAF custom rules and managed rulesets (does not bypass system-level mitigations — use System bypass for that)
- `rate_limit` — throttle by counting key (see Rate limit example for flags)
- `redirect` — redirect to a URL or path; use `--redirect-url <URL>` and optionally `--redirect-permanent` (301; default is a temporary 307 redirect)

`deny`, `challenge`, and `rate_limit` 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.

### 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 (over 600 Enterprise only)
- `--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.

## Bot management

| Goal | Use |
| --- | --- |
| Scripts and non-browser clients site-wide | **Bot Protection** managed rule (`off`/`log`/`challenge`, all plans) |
| AI crawlers and assistants | **AI Bots** managed rule; per category on CLI 65.7+: `rules update ai-bots --category ai-crawlers --action deny` |
| A bot category or named bot | Custom rule on `bot_category` / `bot_name` (public beta, priority projects) |
| Signup, checkout, AI routes called by the app's frontend | **BotID** in code — see the `botid` skill |
| Active flood | Attack Mode (user enables it) |

- **Verified bots** (confirmed by IP, reverse DNS or Web Bot Auth) skip Bot Protection and Attack Mode. AI Bots and custom rules still apply. A UA that only claims to be a bot isn't verified
- **`bypass`** custom rules also skip the managed bot rules — keep them narrow
- **Challenge** is a JS check, not a CAPTCHA; for server or mobile API callers it acts like `deny`

```bash
vercel firewall bot-management                              # managed bot rule actions + unknown bot traffic
vercel firewall traffic list --dimension bot --since 24h    # top verified bots
vercel firewall rules update bot-protection --action log --yes   # off | log | challenge
vercel firewall rules update bot-id --action deep-analysis --yes # basic | deep-analysis (billed, Pro+)
```

`bot-protection`, `ai-bots` and `bot-id` are reserved project-level slugs: only `rules update --action` works on them. Start Bot Protection on `log` and review before `challenge`.

### Bot name and category rules

Public beta, priority projects only — the CLI refuses them elsewhere. They match Vercel's verified identity, not the UA. Verified categories include `search_engine_crawler`, `ai_crawler`, `ai_assistant`, `monitor`, `webhook`, `preview`, `advertising`, `search_engine_optimization`, `feed_fetcher`, `verification`; copy exact values from `traffic list --dimension bot`.

```bash
vercel firewall rules add "Throttle feed fetchers" \
  --condition '{"type":"bot_category","op":"eq","value":"feed_fetcher"}' \
  --action rate_limit --rate-limit-window 60 --rate-limit-requests 30 \
  --rate-limit-action log --yes
```

Blocking `search_engine_crawler` removes the site from search; call that out before staging.

## IP blocks

[IP blocking](https://vercel.com/docs/vercel-firewall/vercel-waf/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
```

## System bypass

[System bypass rules](https://vercel.com/docs/vercel-firewall/vercel-waf/system-bypass-rules) exempt trusted IPs/CIDRs from system-level mitigations such as DDoS mitigation (office, CI servers, uptime monitors). Pro/Enterprise only. 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`.

## Attack mode

[Attack Mode](https://vercel.com/docs/vercel-firewall/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
```

## System mitigations

Vercel automatically [mitigates DDoS attacks](https://vercel.com/docs/vercel-firewall/ddos-mitigation). 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
```

## Publishing

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

## Querying firewall traffic from the CLI

`vercel firewall traffic list` and `vercel firewall traffic inspect` are the built-in way to analyze firewall activity without leaving the terminal — useful for the "review traffic" step in the staged rollout, or for spotting which rules are doing real work. Unlike generic `vc metrics` queries, these succeed on every team plan for the last 24 hours; **Observability Plus** only extends the retention window to 30 days.

```bash
vercel firewall traffic list --since 24h --json   # beyond your plan's retention needs Observability Plus
vercel firewall traffic list --action deny --dimension rule --json
```

- `traffic list` reports requests by action plus top lists across 10 dimensions: `ip`, `ja4`, `asn`, `user-agent`, `path`, `rule`, `host`, `bot`, `country`, `action`. Use `--dimension` to choose which top lists to include.
- `traffic inspect <dimension> <value>` (e.g. `vercel firewall traffic inspect rule rule_abc123 --group-by ip`) drills into one value with a breakdown by a second dimension.
- `--since`/`--until` accept `1h`, `24h`, `3d`, `7d`, etc., or an ISO date; `--json` is best for programmatic review.
- `--since` must fall inside your plan's retention, or the query requires Observability Plus. Shortening the window with `--until` does not help if `--since` is already too far back.

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

```bash
vercel firewall traffic list --since 1h --json
vercel firewall alerts list --since 1h --json   # DDoS mitigation and other anomaly episodes
```

Also available: `vercel firewall status` (config in evaluation order), `vercel firewall persistent-actions list/inspect` (clients currently under a persistent deny/challenge), and `vercel firewall bot-management` (Bot Protection, AI Bots, and BotID managed-rule actions plus unknown-bot traffic). Run `vercel firewall <subcommand> --help` for current flags, and check https://vercel.com/docs/cli/firewall for the full reference. The dashboard URL `/firewall/traffic?filter=<ruleId>` shows the same data for a human to review.

## 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 update "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/update/enable/disable/remove/move`, `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 `--data`.
  - `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"` 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 (`bot_name` / `bot_category` on priority projects, otherwise the managed bot rules, which already let verified bots through), 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."

## 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

## Official Documentation

- [Vercel Firewall](https://vercel.com/docs/vercel-firewall)
- [Bot management](https://vercel.com/docs/bot-management)
- [Vercel CLI](https://vercel.com/docs/cli/firewall)
