---
title: "When the Truck Is a Chain"
description: "An optional lesson for the team that inherits the Firewall once one truck becomes six. Describe Claw & Order's rules in Terraform so git is the source of truth, preview changes with terraform plan, and see where alerts, log drains, and the OWASP ruleset fit."
canonical_url: "https://vercel.com/academy/vercel-firewall/when-the-truck-is-a-chain"
md_url: "https://vercel.com/academy/vercel-firewall/when-the-truck-is-a-chain.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-11-17T18:26:12.115Z"
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>

# When the Truck Is a Chain

# When the truck is a chain

\*\*Note: Advanced and optional\*\*

This lesson is for platform and security teams running the Firewall across several projects. Some features here need Pro or Enterprise, and each one is marked. Nothing else in the course depends on it.

Claw & Order has six trucks now, plus a commissary kitchen and a person named Priya whose job title includes the word "platform." Priya has found six projects with six slightly different `Pinchy's scraper` rules. One of them forgot the home page shows today's spot too. Another blocks `PinchyScout` and also, for reasons nobody remembers, Googlebot. Clicking through six dashboards every time Pinchy's changes tactics is how that happened.

## Outcome

Claw & Order's three custom rules and its Bot Protection setting are described in Terraform, `terraform plan` shows the difference between the code and the live Firewall, and you know where alerts, drains, and managed rulesets fit for a team.

## The snapshot was a photo

Since 2.1 we've committed `firewall/rules.json` after every change. It records what the rules were, and `git log` tells you when they changed. Someone can still change the live Firewall without touching git, and a second truck gets nothing from it.

For that, the code has to be the source of truth and the Firewall has to follow it. The [Vercel Terraform provider](https://registry.terraform.io/providers/vercel/vercel/latest) has a `vercel_firewall_config` resource for exactly this. The [REST API](https://vercel.com/docs/vercel-firewall/firewall-api) does the same thing if you'd rather script it yourself.

## Set up Terraform

You'll need the [Terraform CLI](https://developer.hashicorp.com/terraform/install) and a [Vercel access token](https://vercel.com/docs/accounts/access-tokens). Keep the token out of git:

```bash
mkdir -p terraform
cd terraform
export VERCEL_API_TOKEN="<your-token>"
```

Create `terraform/main.tf`. Use the current provider version from the [registry page](https://registry.terraform.io/providers/vercel/vercel/latest):

```hcl title="terraform/main.tf"
terraform {
  required_providers {
    vercel = {
      source = "vercel/vercel"
    }
  }
}

provider "vercel" {
  team = var.team_id
}

variable "team_id" {
  description = "The team that owns the trucks, from your team's Settings page."
  type        = string
}

variable "project_id" {
  description = "The claw-and-order project's ID, from its Settings page."
  type        = string
}
```

Then initialize:

```bash
terraform init
```

## Describe the rules

Here are the three rules from the main path, as code. Compare each one to the CLI commands you ran:

```hcl title="terraform/firewall.tf"
resource "vercel_firewall_config" "claw_and_order" {
  project_id = var.project_id

  # vercel_firewall_config manages the whole config, so the managed ruleset
  # settings from 4.1 have to live here too, or applying turns them off.
  # An AI Bots category set to allow is `active = false`, and it still
  # needs an action. Set both categories: one left out defaults to
  # active with action log.
  managed_rulesets {
    bot_protection {
      action = "challenge"
      active = true
    }
    ai_bots {
      active        = true
      ai_crawlers   = { action = "deny" }
      ai_assistants = { action = "log", active = false }
    }
  }

  rules {
    rule {
      name        = "TidePay webhook"
      description = "Server-to-server payment events; the route checks the signature"
      condition_group = [{
        conditions = [
          { type = "path", op = "eq", value = "/api/webhooks/payment" },
          { type = "method", op = "eq", value = "POST" },
        ]
      }]
      action = { action = "bypass" }
    }

    rule {
      name = "Pinchy's scraper"
      condition_group = [{
        conditions = [
          { type = "user_agent", op = "sub", value = "PinchyScout" },
          { type = "path", op = "inc", values = ["/", "/location"] },
        ]
      }]
      action = { action = "deny" }
    }

    rule {
      name = "Preorder rush"
      condition_group = [{
        conditions = [
          { type = "path", op = "eq", value = "/api/preorder" },
          { type = "method", op = "eq", value = "POST" },
        ]
      }]
      action = {
        action = "rate_limit"
        rate_limit = {
          limit  = 40
          window = 600
          keys   = ["ip"]
          algo   = "fixed_window"
          action = "rate_limit"
        }
      }
    }
  }
}
```

Each `condition_group` entry is an OR group, and the conditions inside a group are ANDed, the same way `--condition` and `--or` work on the CLI. Rule order in the file is the order the Firewall runs them, so `TidePay webhook` goes first, where `rules move --first` put it in 4.2.

## Import, then plan

`vercel_firewall_config` manages the project's whole configuration. Applying it replaces whatever is live with what's in the file. Before Terraform can compare the two, it needs to know the live config exists. Import it:

```bash
terraform import -var team_id=<team_id> -var project_id=<prj_id> \
  vercel_firewall_config.claw_and_order <team_id>/<prj_id>
```

Plan first:

```bash
terraform plan -var team_id=<team_id> -var project_id=<prj_id>
```

If the file matches what you built in the course, the plan reports no changes, or only small ones like a description. Any difference is something the dashboard has and the file doesn't, or the reverse. On a real team, that difference is the drift Priya found. There's no reference copy of these files to compare against, so the check is the plan itself, next to the final rule set from 5.3's `vercel firewall status`. Once the plan says what you expect:

```bash
terraform apply -var team_id=<team_id> -var project_id=<prj_id>
```

A second truck is a second `vercel_firewall_config` with a different `project_id` and the same rules. The [KB guide](https://vercel.com/kb/guide/firewall-terraform-configuration) shows how to share rule definitions as variables across projects. If every truck should get the same rule no matter what, the CLI can also manage team-level rules with `--team-level`; check the [CLI docs](https://vercel.com/docs/cli/firewall) for what's available on your plan.

## What else a team needs

**Alerts.** [Firewall alerts](https://vercel.com/docs/vercel-firewall/firewall-observability#firewall-alerts) are on all plans. Send the attack-detected event to a [webhook](https://vercel.com/docs/webhooks) your on-call tooling reads (Pro and Enterprise), or to Slack with the Vercel app's `/vercel subscribe {team_id} firewall_attack`.

**Logs in your SIEM.** [Log Drains](https://vercel.com/docs/drains) forward your deployments' logs to your own storage or security tooling. Check the drains docs for plan availability and for which fields, including firewall data, come through.

\*\*Note: Enterprise: OWASP core ruleset\*\*

The [OWASP core ruleset](https://vercel.com/docs/vercel-firewall/vercel-waf/managed-rulesets#configure-owasp-core-ruleset) is a managed set of rules for common attack patterns from the OWASP Top Ten, like injection attempts. Start each rule on **Log**, watch the traffic, then move the ones you trust to **Deny**, the same order you've followed since 2.1.

\*\*Note: Pro and Enterprise: more room\*\*

Hobby's custom rule allowance shaped this whole course. Pro and Enterprise allow many more, plus persistent actions, system bypass, and BotID Deep Analysis from earlier lessons. See the [WAF limits](https://vercel.com/docs/vercel-firewall/vercel-waf#limits) for current numbers.

## Hands-on exercise 5.4

Move the truck's rules into code.

**Requirements:**

1. Install Terraform and export a Vercel token.
2. Write `terraform/main.tf` and `terraform/firewall.tf` for the three main-path rules.
3. Import the live config.
4. Run `terraform plan` and explain every difference it reports.
5. Apply only when the plan matches what you expect.
6. Commit the Terraform files and the lock file, and never the token or state file.

**Implementation hints:**

- Your project ID is on the project's **Settings** page, and it starts with `prj_`.
- Add `.terraform/`, `*.tfstate`, and `*.tfstate.backup` to `.gitignore`. State can hold sensitive values.
- If you did the Advanced lesson 3.2, add the `Preorder per phone` rule too, with a `rate_limit_api_id` condition.

## Try It

After `terraform apply`, change the rate limit in the file from 40 to 41 and plan again:

```bash
terraform plan -var team_id=<team_id> -var project_id=<prj_id>
```

One in-place update, one field. Set it back to 40. That's the loop for every future change: edit, plan, review, apply, commit.

## Commit

```bash
cd ..
printf '.terraform/\n*.tfstate\n*.tfstate.backup\n' >> .gitignore
git add .gitignore terraform/main.tf terraform/firewall.tf terraform/.terraform.lock.hcl
git commit -m "feat(firewall): manage Claw & Order rules with Terraform"
```

From here on, the Terraform files are the source of truth, so you can retire `firewall/rules.json`. Keep it if you want a quick record of what's live; `terraform plan` is still what tells you the two have drifted.

## Done-When

- [ ] The live config is imported and `terraform plan` runs against it
- [ ] Bot Protection is in `managed_rulesets` with the challenge action
- [ ] The three main-path rules are described in `terraform/firewall.tf`
- [ ] Changing a value in the file shows up as a one-field update in the plan
- [ ] The Terraform files are committed and the state and token aren't

## Troubleshooting

**`terraform plan` wants to delete a rule you didn't put in the file.** That rule exists in the live Firewall but not in your code. Add it to the file, or delete it on purpose. Don't apply until you've decided which.

**The provider rejects a condition.** Field names can change between provider versions. Check the [`vercel_firewall_config` docs](https://registry.terraform.io/providers/vercel/vercel/latest/docs/resources/firewall_config) for the version `terraform init` installed.

## Solution

The two files above, `terraform/main.tf` and `terraform/firewall.tf`, plus:

```bash
cd terraform
terraform init
terraform import -var team_id=<team_id> -var project_id=<prj_id> \
  vercel_firewall_config.claw_and_order <team_id>/<prj_id>
terraform plan -var team_id=<team_id> -var project_id=<prj_id>
terraform apply -var team_id=<team_id> -var project_id=<prj_id>
```

Priya can sleep now. Every truck runs the same rules, and the rules live in git.


---

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