Docs

Introduction

Vercel Doorman is a powerful tool for managing Vercel Firewall rules as code. It enables version control and automated deployment of your project's security configuration.

Installation

To install Vercel Doorman, please refer to our Getting Started guide.

Configuration

Vercel Doorman uses a vercel-firewall.config.json config file in your project root to define your firewall rules.

{
  "projectId": "prj_...",
  "teamId": "team_...",
  "rules": [
    {
      "name": "Block API Access",
      "description": "Block access to API endpoints",
      "conditionGroup": [
        {
          "conditions": [
            {
              "type": "path",
              "op": "pre",
              "value": "/api"
            }
          ]
        }
      ],
      "action": {
        "mitigate": {
          "action": "deny",
          "rateLimit": {
            "requests": 100,
            "window": "1m"
          },
          "actionDuration": "1h"
        }
      },
      "active": true
    }
  ],
  "ips": []
}

Replace prj_... and team_... with your actual Vercel project and team IDs. The rules array contains your firewall rules. For more examples, see the Examples section below.

💬 If you have a pre-existing firewall, we recommend using the download command to get started...

Fetches your current rules and creates/updates a local vercel-firewall.config.json file.

Environment Variables

Variables can be provided in any way that makes them available in the current environment, such as through a .env file, shell exports, or CI/CD environment settings.

If you prefer to use a .env file, you can create one in your project's root directory with the following content:

VERCEL_TOKEN=your_vercel_api_token
VERCEL_PROJECT_ID=your_project_id
VERCEL_TEAM_ID=your_team_id

Replace the values with your actual Vercel API token, project ID, and team ID. When these environment variables are set, you don't need to include them in your commands or configuration file.

Note: Make sure to add .env to your .gitignore file to prevent sensitive information from being committed to your repository.

Commands

  • list List firewall rules, either the current active configuration or a specific version
    # List current active rules
npx vercel-doorman list

# List rules from a specific version
npx vercel-doorman list 1

# List specific version in JSON format
npx vercel-doorman list 2 --format json
  • sync Synchronize your local configuration with Vercel
    npx vercel-doorman sync --token YOUR_TOKEN
    Options:
    • --config, -c: Path to config file
    • --projectId, -p: Vercel Project ID
    • --teamId, -t: Vercel Team ID
    • --token: Vercel API token
  • download Download firewall rules from your Vercel project
    # Preview changes without modifying config
npx vercel-doorman download --dry-run

# Download and update config
npx vercel-doorman download

# Download specific version
npx vercel-doorman download 1
    Options:
    • configVersion: Optional version number
    • --dry-run, -d: Preview changes
    • --config, -c: Path to config file
    • --token: Vercel API token
  • template Add predefined rule templates to your configuration
     # List available templates
npx vercel-doorman template

# Add specific template
npx vercel-doorman template wordpress

    Available Templates

    • bad-bots: Block common malicious bot traffic
    • ai-bots: Block AI crawlers and scrapers
    • wordpress: Block WordPress-related URLs
    • block-ofac-sanctioned-countries: OFAC compliance
  • validate Validate your configuration file
    npx vercel-doorman validate

# Show detailed validation results
npx vercel-doorman validate --verbose
    Options:
    • --config, -c: Path to config file
    • --verbose, -v: Show detailed results

Environment Variables

Instead of passing command-line arguments, you can set these environment variables:

  • VERCEL_TOKEN: Your Vercel API token
  • VERCEL_PROJECT_ID: Your Vercel project ID
  • VERCEL_TEAM_ID: Your Vercel team ID

Examples

We provide a variety of example configurations on to help you get started.

Basic Rules

Advanced Rules