Update to Vercel

{
  "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 113
    }
  ],
  "name": "vercel-firewall",
  "skill_md_contents": "---\nname: vercel-firewall\ndescription: 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.\nmetadata:\n  priority: 7\n  docs:\n    - 'https://vercel.com/docs/vercel-firewall'\n    - 'https://vercel.com/docs/cli/firewall'\n  bashPatterns:\n    - '\\bvercel\\s+firewall\\b'\n  promptSignals:\n    phrases:\n      - 'vercel firewall'\n      - 'vercel waf'\n      - 'attack mode'\n      - 'ddos protection'\n      - 'ip block'\n      - 'managed ruleset'\n      - 'bot protection'\n      - 'system bypass'\n      - 'rate limit rule'\n    allOf:\n      - [firewall, vercel]\n      - [waf, vercel]\n      - [ddos, vercel]\n      - [challenge, vercel]\n      - ['rate limit', vercel]\n      - ['system bypass', vercel]\n      - ['ip block', vercel]\n    noneOf: []\n    minScore: 6\nretrieval:\n  aliases:\n    - ddos protection\n    - waf rules\n    - bot protection\n    - rate limiting\n    - attack mode\n    - ip allowlist\n    - traffic filtering\n    - verified bots\n  intents:\n    - protect from ddos\n    - block malicious traffic\n    - configure firewall\n    - rate limit api\n    - allow bot through firewall\n    - enable attack mode\n    - publish firewall rule\n  entities:\n    - Vercel Firewall\n    - Vercel WAF\n    - DDoS\n    - Attack Mode\n    - Bot Protection\n    - Managed Rulesets\n    - System Bypass\n    - JA3\n    - JA4\n---\n\n# Vercel Firewall\n\nYou 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.\n\n## Core Knowledge\n\n- **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.\n- **Automatic DDoS mitigation is on for every project on every plan, including Hobby**, with no configuration required. It covers L3/L4/L7 attacks.\n- **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.\n- **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.\n\n## Overview\n\nProject must be linked first (`vercel link`).\n\n```bash\nvercel firewall overview                  # active rules, blocks, bypasses, attack-mode, drafts\nvercel firewall overview --json\nvercel firewall diff                      # show unpublished draft changes\nvercel firewall diff --json\n```\n\n`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**.\n\n## Custom rules\n\n[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`.\n\n### View\n\n```bash\nvercel firewall rules list                          # table of all rules\nvercel firewall rules list --expand                 # show conditions + actions\nvercel firewall rules list --json\nvercel firewall rules inspect \"My Rule\"             # full detail of one rule\nvercel firewall rules inspect \"My Rule\" --json\n```\n\n### Create — four modes\n\n```bash\n# AI — TTY only, BLOCKED FOR AGENTS/SCRIPTS\nvercel firewall rules add --ai \"Rate limit /api to 100 requests per minute by IP\"\n\n# Interactive wizard — TTY only, BLOCKED FOR AGENTS/SCRIPTS\nvercel firewall rules add\n\n# Flags — works in scripts and agents\nvercel firewall rules add \"Block crawlers\" \\\n  --condition '{\"type\":\"user_agent\",\"op\":\"sub\",\"value\":\"crawler\"}' \\\n  --action deny --yes\n\n# JSON — works in scripts and agents\nvercel firewall rules add --json '{\"name\":\"Block crawlers\",\"conditionGroup\":[{\"conditions\":[{\"type\":\"user_agent\",\"op\":\"sub\",\"value\":\"crawler\"}]}],\"action\":{\"mitigate\":{\"action\":\"deny\"}}}' --yes\n```\n\n### Multiple conditions (AND) and OR groups\n\n```bash\n# AND — multiple --condition flags in the same group\nvercel firewall rules add \"Secure admin\" \\\n  --condition '{\"type\":\"path\",\"op\":\"pre\",\"value\":\"/admin\"}' \\\n  --condition '{\"type\":\"geo_country\",\"op\":\"eq\",\"neg\":true,\"value\":\"US\"}' \\\n  --action deny --yes\n\n# OR — use --or to start a new group\nvercel firewall rules add \"Block dangerous methods\" \\\n  --condition '{\"type\":\"method\",\"op\":\"eq\",\"value\":\"DELETE\"}' \\\n  --or \\\n  --condition '{\"type\":\"method\",\"op\":\"eq\",\"value\":\"PATCH\"}' \\\n  --action challenge --yes\n```\n\n### Edit and manage\n\n```bash\nvercel firewall rules edit \"My Rule\" --action challenge --yes      # change action\nvercel firewall rules edit \"My Rule\" --name \"New Name\" --yes       # rename\nvercel firewall rules edit \"My Rule\" --enabled --yes               # enable\nvercel firewall rules edit \"My Rule\" --disabled --yes              # disable\nvercel firewall rules edit \"My Rule\" \\\n  --condition '{\"type\":\"path\",\"op\":\"pre\",\"value\":\"/new\"}' --yes    # replace conditions\n\nvercel firewall rules enable  \"My Rule\"\nvercel firewall rules disable \"My Rule\"\nvercel firewall rules remove  \"My Rule\" --yes                      # aliases: rm, delete\nvercel firewall rules reorder \"My Rule\" --first  --yes             # move to highest priority\nvercel firewall rules reorder \"My Rule\" --last   --yes\nvercel firewall rules reorder \"My Rule\" --position 3 --yes         # 1-based\n```\n\nRules are evaluated in priority order (top to bottom). Reorder to control which rule matches first.\n\nNOTE: When using `edit` with `--condition`, it will overwrite all conditions listed in the rule. Make sure to specify all conditions when editing a rule.\n\n### Condition format\n\nEach `--condition` is a JSON object:\n\n```json\n{\n  \"type\": \"path\", // condition type (required)\n  \"op\": \"pre\", // operator (required)\n  \"value\": \"/api\", // value (required for most operators; omit for ex/nex)\n  \"key\": \"Authorization\", // required for header / cookie / query types\n  \"neg\": true // negate the condition (optional, default false)\n}\n```\n\nConditions within a group are **AND'd**. Multiple groups (separated by `--or`) are **OR'd**.\n\n### Operators\n\n`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.\n\n### Condition types\n\n- **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`\n- **Client**: `ip_address` (IP or CIDR), `user_agent`, `geo_country`, `geo_continent`, `geo_country_region`, `geo_city`, `geo_as_number`\n- **Headers / cookies / queries** — require `key`: `header`, `cookie`, `query`\n- **TLS fingerprints**: `ja4_digest` (all plans), `ja3_digest` (Enterprise only)\n- **Rate limit grouping**: `rate_limit_api_id`\n\n### Actions\n\n- `deny` — block (403)\n- `challenge` — show verification page\n- `log` — log without blocking (use to tune before enforcing)\n- `bypass` — skip remaining WAF custom rules and managed rulesets (does not bypass system-level mitigations — use System bypass for that)\n- `rate_limit` — throttle by counting key (see Rate limit example for flags)\n- `redirect` — redirect to a URL or path; use `--redirect-url <URL>` and optionally `--redirect-permanent` (301; default is a temporary 307 redirect)\n\n`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.\n\n### Rate limit example\n\n```bash\nvercel firewall rules add \"Rate limit API\" \\\n  --condition '{\"type\":\"path\",\"op\":\"pre\",\"value\":\"/api\"}' \\\n  --action rate_limit \\\n  --rate-limit-window 60 \\\n  --rate-limit-requests 100 \\\n  --rate-limit-keys ip \\\n  --rate-limit-action deny \\\n  --yes\n```\n\n- `--rate-limit-window` — seconds, 10–3600 (over 600 Enterprise only)\n- `--rate-limit-requests` — max per window, 1–10,000,000\n- `--rate-limit-keys` — count by `ip` (default) or `ja4`. `header:<name>` Enterprise only. Repeatable.\n- `--rate-limit-algo` — `fixed_window` (default), `token_bucket` (Enterprise only)\n- `--rate-limit-action` — when limit exceeded: `rate_limit` returns 429 (default), `deny` 403, `challenge`, `log`\n- Counters are **per region** — N regions can collectively exceed your configured limit by ~N×.\n\nWhen 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.\n\nMethod 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.\n\nFor 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.\n\n## IP blocks\n\n[IP blocking](https://vercel.com/docs/vercel-firewall/vercel-waf/ip-blocking) blocks IPs or CIDRs entirely. Staged — requires `publish`.\n\n```bash\nvercel firewall ip-blocks list\nvercel firewall ip-blocks list --json\nvercel firewall ip-blocks block 1.2.3.4 --yes\nvercel firewall ip-blocks block 10.0.0.0/24 --hostname example.com --yes   # scoped to a host\nvercel firewall ip-blocks block 1.2.3.4 --notes \"Abuse report #123\" --yes\nvercel firewall ip-blocks unblock 1.2.3.4 --yes\nvercel firewall ip-blocks unblock 1.2.3.4 --hostname example.com --yes     # disambiguate when blocked on multiple hosts\nvercel firewall ip-blocks unblock ip_abc123 --yes                          # by rule ID\n```\n\n## System bypass\n\n[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.\n\n```bash\nvercel firewall system-bypass list\nvercel firewall system-bypass list --json\nvercel firewall system-bypass add 10.0.0.1 --yes\nvercel firewall system-bypass add 10.0.0.0/24 --yes\nvercel firewall system-bypass add 10.0.0.1 --domain example.com --yes\nvercel firewall system-bypass add 10.0.0.1 --domain \"*.example.com\" --yes  # wildcard domain\nvercel firewall system-bypass add 10.0.0.1 --notes \"Office IP\" --yes\nvercel firewall system-bypass remove 10.0.0.1 --yes\n```\n\nSystem bypass does **not** override your own custom rules — for that, use a custom rule with `--action bypass`.\n\n## Attack mode\n\n[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.**\n\n```bash\nvercel firewall attack-mode enable --duration 1h --yes    # 1h (default)\nvercel firewall attack-mode enable --duration 6h --yes\nvercel firewall attack-mode enable --duration 24h --yes\nvercel firewall attack-mode disable --yes\n```\n\n## System mitigations\n\nVercel 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.**\n\n```bash\nvercel firewall system-mitigations pause  --yes    # 24h, auto-resume\nvercel firewall system-mitigations resume --yes\n```\n\n## Publishing\n\n```bash\nvercel firewall diff                      # review staged changes\nvercel firewall publish --yes             # push drafts to production\nvercel firewall discard --yes             # throw away drafts\n```\n\n## Querying firewall traffic from the CLI\n\n`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 plan for the last 24 hours; **Observability Plus** only extends the retention window to 30 days.\n\n```bash\nvercel firewall traffic list --since 3d --json\nvercel firewall traffic list --action deny --dimension rule --json\n```\n\n- `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.\n- `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.\n- `--since`/`--until` accept `1h`, `24h`, `3d`, `7d`, etc., or an ISO date; `--json` is best for programmatic review.\n- A window entirely before your plan's retention returns an error asking you to shorten it or add Observability Plus.\n\nFor an **active-attack triage** lens — \"is something happening right now?\" — narrow the window:\n\n```bash\nvercel firewall traffic list --since 1h --json\nvercel firewall alerts list --since 1h --json   # DDoS mitigation and other anomaly episodes\n```\n\nAlso 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.\n\n## Best practices\n\nThe 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.\n\n- **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.\n  1. **Log everywhere.** Add the rule with `--action log` so it records hits to the Firewall dashboard but blocks nothing.\n\n     ```bash\n     vercel firewall rules add \"Block exploit probes\" \\\n       --condition '{\"type\":\"path\",\"op\":\"inc\",\"value\":[\"/wp-admin\",\"/.env\",\"/.git/config\",\"/phpmyadmin\"]}' \\\n       --action log --yes\n     ```\n\n  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:\n\n     ```\n     https://vercel.com/<team>/<project>/firewall/traffic?filter=<ruleId>\n     ```\n\n     Have them confirm only the intended traffic is matching (no real users, no SEO crawlers, no internal tools) before moving on.\n\n  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:\n\n     ```bash\n     vercel firewall rules edit \"Block exploit probes\" \\\n       --action deny \\\n       --condition '{\"type\":\"path\",\"op\":\"inc\",\"value\":[\"/wp-admin\",\"/.env\",\"/.git/config\",\"/phpmyadmin\"]}' \\\n       --condition '{\"type\":\"environment\",\"op\":\"eq\",\"value\":\"preview\"}' \\\n       --yes\n     ```\n\n     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.\n\n  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`.\n\n- **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.\n\n- **Don't run commands the CLI blocks for agents.** Surface what the user needs to do instead:\n  - `vercel firewall rules add --ai \"...\"` and `vercel firewall rules add` (wizard) — TTY-only. Use `--condition` flags or `--json`.\n  - `vercel firewall attack-mode enable` — requires explicit interactive confirmation; have the user run it.\n  - `vercel firewall system-mitigations pause` — pauses platform DDoS protection across the project; have the user run it and resume ASAP.\n\n- **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.\n\n- **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`.\n\n- **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).\n\n- **Don't over-block.** User agents, JA4, and IP addresses may collide with real users far more than they look like they will:\n  - **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.\"\n  - **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.\n  - **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.\"\n\n## External reverse proxies\n\nExternal 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\n\n## Official Documentation\n\n- [Vercel Firewall](https://vercel.com/docs/vercel-firewall)\n- [Bot management](https://vercel.com/docs/bot-management)\n- [Vercel CLI](https://vercel.com/docs/cli/firewall)\n"
}