---
title: "Block an IP or Country"
description: "Pinchy's scraper starts sending a browser user agent. Reach for the two classic incident moves, an IP block and a country rule, from the vercel firewall CLI. Review the IP block as a draft and discard it, run the country rule in log mode and remove it, and learn when each one is the right tool."
canonical_url: "https://vercel.com/academy/vercel-firewall/block-an-ip-or-country"
md_url: "https://vercel.com/academy/vercel-firewall/block-an-ip-or-country.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-11-17T18:26:11.827Z"
content_type: "lesson"
course: "vercel-firewall"
course_title: "Protect Your App on Vercel"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Block an IP or Country

# Block an IP or country

Pinchy's figured it out. Their scraper stopped saying `PinchyScout` and now introduces itself as Chrome on a Mac, which, to be fair, is how most of your customers introduce themselves too. The name rule from 2.1 is useless against it. The two moves everybody reaches for next are "block that IP" and "block that country." Let's try both, carefully, from the terminal.

## Outcome

You can block an IP and a country from the CLI, and you've caught both blocks before they went live: one as a draft you discarded, one as a log rule you removed.

## The disguise

The scalper has a flag for this:

```bash
npm run scalper -- scrape --target "$URL" --count 5 --disguise
```

```text
scrape /location as a browser (disguised) → https://claw-and-order.vercel.app  (5 requests)
Only point this at a deployment you own.

  [01] 200 GET /location
  [02] 200 GET /location
  [03] 200 GET /location
  [04] 200 GET /location
  [05] 200 GET /location

Results
  200            5
```

Back to `200`s. The user agent is a string the client writes itself, and Pinchy's wrote a new one. Let's see what else the Firewall knows about whoever is reading `/location`:

```bash
vercel firewall traffic list --since 15m --path /location --dimension ip --dimension country --dimension user-agent
```

The user agent looks like a browser's, but there's only one IP and one country behind it. Both look like handles to grab.

## Block the IP

[IP blocking](https://vercel.com/docs/vercel-firewall/vercel-waf/ip-blocking) is its own layer, right before custom rules, with its own allowance. Block the address from the report:

```bash
vercel firewall ip-blocks block <ip-from-the-report> --notes "Pinchy's scraper" --yes
vercel firewall diff
```

Like rule changes, IP blocks from the CLI are [staged as drafts](https://vercel.com/docs/cli/firewall#staging-and-publishing-workflow). Nothing is live yet, which is lucky. Before we publish, compare that address to our own:

```bash
curl -4 -s https://ifconfig.me
```

It's the same address. The scraper runs on your laptop, so this block would lock you out along with it. Throw the draft away:

```bash
vercel firewall discard --yes
vercel firewall diff
```

`diff` shows no pending changes. In this story Pinchy's would run from somewhere else, but the lesson holds on real sites. Whole office buildings share one IP, and so do lots of phones on the same carrier.

An IP block fits when one address sends traffic you never want, and it isn't yours or shared. Check its network with `vercel firewall traffic inspect ip <ip>` first. A cloud provider's IP is a better bet than a mobile carrier's.

## Block the country

A country is a much bigger handle than an IP, so this one starts in log mode. Use the country code from the report. Add it as a custom rule, scoped to the two pages that show today's spot:

```bash
vercel firewall rules add "Country check" \
  --condition '{"type":"geo_country","op":"eq","value":"<your-country-code>"}' \
  --condition '{"type":"path","op":"inc","value":["/","/location"]}' \
  --action log \
  --yes
vercel firewall publish --confirm-name claw-and-order
export SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
```

Each `--condition` is a small JSON object, and several combine with AND. `inc` means "is any of." Publishing asks you to type the project's name before anything goes live, and `--confirm-name` answers that question in the command. If the name doesn't match the linked project, nothing publishes. Now send the scraper, plus a visit that's definitely a customer, yourself:

```bash
npm run scalper -- scrape --target "$URL" --count 5 --disguise
curl -s -o /dev/null "$URL/location"
```

Open `/location` in your browser too. Then check what the rule logged:

```bash
vercel firewall traffic list --since "$SINCE" --action log --dimension user-agent
```

The scraper is in there, and so are curl and your browser. So would be every customer in your country who checked where the truck is parked today. On deny, this rule would have closed the truck to an entire country to stop one script. Remove it:

```bash
vercel firewall rules remove "Country check" --yes
vercel firewall publish --confirm-name claw-and-order
```

That leaves `Pinchy's scraper` as the only custom rule, which matters on Hobby's small [custom rule allowance](https://vercel.com/docs/vercel-firewall/vercel-waf#limits).

A country rule fits when you can say with a straight face that nobody in that country is a customer. Run it on log for a day, read what it caught, then switch it to deny the way you did in 2.1.

The disguised scraper is still getting in. It's a script that claims to be a browser, and in Section 4 we'll turn on a layer that checks exactly that claim.

\*\*Note: A sharper signal: JA4\*\*

Every HTTPS client has a [JA4 TLS fingerprint](https://vercel.com/docs/vercel-firewall/firewall-concepts#ja3-and-ja4-tls-fingerprints) that depends on the software making the connection, whatever user agent it sends. You can match on it in a custom rule (`ja4_digest`) and see it in the traffic report with `--dimension ja4`. In this course every `attack/` script shares Node.js's fingerprint, so a JA4 rule would hit the friendly scripts too. On a real site, it's worth a look.

## Hands-on exercise 2.2

Try both blocks without letting either one hurt a customer.

**Requirements:**

1. Run the scraper with `--disguise` and confirm it gets `200`s again.
2. Use `vercel firewall traffic list` on `/location` to find its IP and country.
3. Stage an IP block for that address and review it with `vercel firewall diff`.
4. Compare the address to your own, then discard the draft.
5. Add a `Country check` rule in log mode for your country on `/` and `/location`, and publish it.
6. Send the disguised scraper and a request of your own, and confirm the rule logged both.
7. Remove `Country check` and publish.

**Implementation hints:**

- `--dimension country` isn't in the default report, so ask for it.
- Country codes are two letters (ISO 3166-1), like `US` or `DE`. Copy yours from the report.
- `vercel firewall ip-blocks list` and `vercel firewall rules list` both show drafts, so you can check what's staged at any point.

## Try It

After you've removed the country rule, check that the Firewall is exactly where 2.1 left it:

```bash
vercel firewall ip-blocks list
vercel firewall rules list
vercel firewall diff
```

No IP blocks, one custom rule, nothing pending. `rules list` prints the managed bot rules (Bot Protection, AI Bots, BotID) first, then your custom rules. Those managed rows are expected; `Pinchy's scraper` should be the only custom one. Your browser still loads `/location`, and the PinchyScout user agent still gets a `403`:

```bash
curl -s -o /dev/null -w "%{http_code}\n" -A "PinchyScout/2.1 (+https://pinchys.example/bot)" "$URL/location"
```

```text
403
```

## Commit

Snapshot the rules. The file should match the one from 2.1:

```bash
vercel firewall rules list --json > firewall/rules.json
git diff --stat firewall/rules.json
git commit --allow-empty -m "chore(firewall): try IP and country blocks for the disguised scraper, ship neither" \
  -m "Both matched our own traffic. Discarded the IP block draft; removed the log-mode country rule."
```

If `git diff` shows changes, open the file and look at what moved. A rule or IP block in the diff means something from this lesson is still in the Firewall, so run the Try It checks again. The empty commit is on purpose: a decision not to ship a rule is worth a line in the history too.

## Done-When

- [ ] You staged an IP block, reviewed it with `diff`, and discarded it
- [ ] `Country check` logged both the disguised scraper and your own requests
- [ ] `Country check` is removed and published
- [ ] `vercel firewall ip-blocks list` shows no blocks and `rules list` shows `Pinchy's scraper` as the only custom rule
- [ ] The commit records why neither block shipped

## Troubleshooting

**You published the IP block by accident and now your browser gets `403`.** The CLI still works, because it talks to Vercel's API, not your deployment. Run `vercel firewall ip-blocks unblock <ip> --yes` and `vercel firewall publish --confirm-name claw-and-order`.

**`rules add` refuses with a limit error.** Your project is at its custom rule allowance. `vercel firewall rules list` shows what's there. At this point on Hobby, the main path expects only `Pinchy's scraper`.

**The address from `ifconfig.me` doesn't match the report.** Your network probably has both IPv4 and IPv6, and the two commands used different ones. Run `curl -6 -s https://ifconfig.me` and compare again. One of the two will match.

**`publish` runs but nothing goes live.** The name after `--confirm-name` has to match the linked project. If you renamed the project or the deploy flow picked a different name, use yours: `vercel project ls` lists it. `vercel firewall diff` shows the changes still waiting.

**`publish` rejects `--confirm-name`.** Your CLI is older than the flag. Update it with `npm i -g vercel@latest`, as in [Deploy the Truck](/academy/vercel-firewall/deploy-the-truck).

**`rules add` fails to parse a condition.** The shell ate the quotes. Use single quotes outside the JSON and double quotes inside, exactly as in the example.

## Solution

The whole lesson, start to finish, with nothing left behind in the Firewall:

```bash
# The disguise, and what the Firewall can see
npm run scalper -- scrape --target "$URL" --count 5 --disguise
vercel firewall traffic list --since 15m --path /location --dimension ip --dimension country --dimension user-agent

# IP: stage, review, notice it's you, discard
vercel firewall ip-blocks block <ip> --notes "Pinchy's scraper" --yes
vercel firewall diff
curl -4 -s https://ifconfig.me
vercel firewall discard --yes

# Country: log first, read, remove
vercel firewall rules add "Country check" \
  --condition '{"type":"geo_country","op":"eq","value":"<your-country-code>"}' \
  --condition '{"type":"path","op":"inc","value":["/","/location"]}' \
  --action log --yes
vercel firewall publish --confirm-name claw-and-order
export SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
npm run scalper -- scrape --target "$URL" --count 5 --disguise
curl -s -o /dev/null "$URL/location"
vercel firewall traffic list --since "$SINCE" --action log --dimension user-agent
vercel firewall rules remove "Country check" --yes
vercel firewall publish --confirm-name claw-and-order
```

Pinchy's still knows where the truck is parked. Now you know what an IP or country block catches before it goes live.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)
