@gfargo/doorman 3.1.0 → 3.2.0

package/skills/doorman/references/rules.md

@@ -0,0 +1,352 @@
+# Rule Authoring Reference
+
+Complete reference for creating and configuring Doorman firewall rules.
+
+## Rule Structure
+
+Every rule in the `rules` array has this shape:
+
+```json
+{
+  "id": "rule_descriptive_name",
+  "name": "Human-Readable Name",
+  "description": "What this rule does and why",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [/* AND — all must match */] },
+    { "conditions": [/* OR — this group is an alternative */] }
+  ],
+  "action": { "mitigate": { "action": "deny" } }
+}
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | No | Unique identifier. Convention: `rule_` prefix, snake_case. Auto-generated if omitted. |
+| `name` | string | Yes | Display name shown in tables and logs. |
+| `description` | string | No | Explains the rule's purpose. Improves health score. |
+| `active` | boolean | Yes | `true` to enforce, `false` to disable without deleting. |
+| `conditionGroup` | array | Yes | Array of condition groups (see below). |
+| `action` | object | Yes | What to do when conditions match (see below). |
+
+## Condition Groups
+
+```json
+"conditionGroup": [
+  { "conditions": [/* AND — all must match */] },
+  { "conditions": [/* OR — this group is an alternative */] }
+]
+```
+
+**Logic**:
+- Conditions **within** a group: AND (all must match)
+- **Between** groups: OR (any group matching triggers the rule)
+
+## Conditions
+
+Each condition has:
+
+```json
+{ "type": "field_type", "op": "operator", "value": "match_value", "key": "header_name", "neg": false }
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | What to match against (see types below). |
+| `op` | string | Yes | How to compare (see operators below). |
+| `value` | string/number/array | Yes | Value to match. Arrays for `inc` operator. |
+| `key` | string | No | Required for `header`, `query`, `cookie` types. |
+| `neg` | boolean | No | `true` to negate the condition (NOT logic). Default: `false`. |
+
+### Condition Types
+
+| Type | Description | Example Value |
+|------|-------------|---------------|
+| `path` | URL path | `"/api/users"` |
+| `method` | HTTP method | `"POST"` |
+| `host` | Hostname | `"example.com"` |
+| `user_agent` | User-Agent header | `"Googlebot"` |
+| `ip_address` | Client IP | `"192.168.1.1"` |
+| `header` | HTTP header (requires `key`) | `"application/json"` |
+| `query` | Query parameter (requires `key`) | `"true"` |
+| `cookie` | Cookie value (requires `key`) | `"session_abc"` |
+| `geo_country` | Country code (ISO 3166-1) | `"US"` or `["US","CA"]` |
+| `geo_city` | City name | `"New York"` |
+| `geo_continent` | Continent code | `"NA"` |
+| `geo_country_region` | Region/state code | `"CA"` |
+| `geo_as_number` | ASN number | `13335` |
+| `scheme` | URL scheme | `"https"` |
+| `protocol` | HTTP protocol version | `"HTTP/2"` |
+
+**Vercel-only types** (not available on Cloudflare):
+- `environment` — deployment environment (`"production"`, `"preview"`)
+- `ja3_digest` — TLS fingerprint
+- `ja4_digest` — TLS fingerprint v4
+- `region` — Vercel edge region
+- `rate_limit_api_id` — rate limit API identifier
+
+### Operators
+
+| Operator | Name | Description | Value Type |
+|----------|------|-------------|------------|
+| `eq` | Equals | Exact match | string/number |
+| `pre` | Prefix | Starts with | string |
+| `suf` | Suffix | Ends with | string |
+| `sub` | Substring | Contains | string |
+| `inc` | Includes | Is any of (array match) | string[] |
+| `re` | Regex | Regular expression match | string (regex pattern) |
+| `ex` | Exists | Field/header exists | `true` |
+| `nex` | Not Exists | Field/header does not exist | `true` |
+
+### Using `key` for Header/Query/Cookie
+
+```json
+{ "type": "header", "op": "eq", "value": "application/json", "key": "Content-Type" }
+{ "type": "query", "op": "eq", "value": "true", "key": "debug" }
+{ "type": "cookie", "op": "ex", "value": true, "key": "session_id" }
+```
+
+### Using `neg` for Negation
+
+```json
+{ "type": "geo_country", "op": "inc", "value": ["US", "CA", "GB"], "neg": true }
+```
+
+This matches requests NOT from US, CA, or GB.
+
+## Actions
+
+### Deny (Block)
+
+```json
+{ "action": { "mitigate": { "action": "deny" } } }
+```
+
+### Deny with Duration
+
+```json
+{ "action": { "mitigate": { "action": "deny", "actionDuration": "1h" } } }
+```
+
+Duration formats: `"30s"`, `"5m"`, `"1h"`, `"1d"`, `"permanent"`
+
+### Challenge (CAPTCHA)
+
+```json
+{ "action": { "mitigate": { "action": "challenge" } } }
+```
+
+### Rate Limit
+
+```json
+{
+  "action": {
+    "mitigate": {
+      "action": "rate_limit",
+      "rateLimit": {
+        "requests": 100,
+        "window": "60s"
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `requests` | number | Yes | Max requests allowed in window. |
+| `window` | string | Yes | Time window: `"10s"`, `"1m"`, `"5m"`, `"1h"` |
+| `characteristics` | string[] | No | What to rate limit by. Default: `["ip.src"]`. Options: `"ip.src"`, `"http.request.uri.path"`, `"http.request.headers[\"user-agent\"]"` |
+| `mitigationTimeout` | number | No | How long (seconds) to block after limit exceeded. Default: 3600. |
+| `countingExpression` | string | No | Cloudflare-specific: expression for what counts toward the limit. |
+
+### Redirect
+
+```json
+{
+  "action": {
+    "mitigate": {
+      "action": "redirect",
+      "redirect": { "location": "https://example.com/blocked", "permanent": false }
+    }
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `location` | string | Redirect URL (absolute or relative path). |
+| `permanent` | boolean | `true` for 301, `false` for 302. |
+
+### Log Only
+
+```json
+{ "action": { "mitigate": { "action": "log" } } }
+```
+
+### Bypass
+
+```json
+{ "action": { "mitigate": { "action": "bypass" } } }
+```
+
+## IP Blocking Rules
+
+IP rules go in the `ips` array, separate from `rules`:
+
+```json
+{
+  "ips": [
+    {
+      "id": "ip_malicious_actor",
+      "ip": "192.168.1.100/32",
+      "hostname": "attacker.example.com",
+      "action": "deny",
+      "notes": "Blocked 2024-01-15: repeated brute force attempts"
+    }
+  ]
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | No | Unique identifier. |
+| `ip` | string | Yes | IP address or CIDR range. Use `/32` for single IPs. |
+| `hostname` | string | No | Associated hostname (documentation only). |
+| `action` | string | Yes | `"deny"` (only supported value currently). |
+| `notes` | string | No | Why this IP was blocked. |
+
+### CIDR Notation
+
+```
+192.168.1.1/32    -> single IP
+192.168.1.0/24    -> 256 IPs (192.168.1.0 - 192.168.1.255)
+10.0.0.0/8        -> class A range
+0.0.0.0/0         -> all IPv4 (use with caution!)
+```
+
+## Common Patterns
+
+### Block multiple countries
+
+```json
+{
+  "name": "OFAC Sanctions Compliance",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [{ "type": "geo_country", "op": "inc", "value": ["CU", "IR", "KP", "SY", "RU"] }] }
+  ],
+  "action": { "mitigate": { "action": "deny" } }
+}
+```
+
+### Allow only specific countries (block everyone else)
+
+```json
+{
+  "name": "Allow Only US/CA/GB",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [{ "type": "geo_country", "op": "inc", "value": ["US", "CA", "GB"], "neg": true }] }
+  ],
+  "action": { "mitigate": { "action": "deny" } }
+}
+```
+
+### Rate limit API with path + method
+
+```json
+{
+  "name": "Rate Limit POST to API",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [
+      { "type": "path", "op": "pre", "value": "/api/" },
+      { "type": "method", "op": "eq", "value": "POST" }
+    ]}
+  ],
+  "action": {
+    "mitigate": {
+      "action": "rate_limit",
+      "rateLimit": { "requests": 50, "window": "1m" },
+      "actionDuration": "5m"
+    }
+  }
+}
+```
+
+### Block by header (missing auth)
+
+```json
+{
+  "name": "Block Missing API Key",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [
+      { "type": "path", "op": "pre", "value": "/api/" },
+      { "type": "header", "op": "nex", "value": true, "key": "X-API-Key" }
+    ]}
+  ],
+  "action": { "mitigate": { "action": "deny" } }
+}
+```
+
+### Challenge suspicious user agents
+
+```json
+{
+  "name": "Challenge Suspicious Bots",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [{ "type": "user_agent", "op": "sub", "value": "curl" }] },
+    { "conditions": [{ "type": "user_agent", "op": "sub", "value": "wget" }] },
+    { "conditions": [{ "type": "user_agent", "op": "sub", "value": "python-requests" }] }
+  ],
+  "action": { "mitigate": { "action": "challenge" } }
+}
+```
+
+### Block WordPress attack paths (regex)
+
+```json
+{
+  "name": "Block WordPress Paths",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [{ "type": "path", "op": "re", "value": "/(wp-admin|wp-login\\.php|xmlrpc\\.php|wp-content)" }] }
+  ],
+  "action": { "mitigate": { "action": "deny" } }
+}
+```
+
+### Redirect old paths
+
+```json
+{
+  "name": "Redirect Legacy API",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [{ "type": "path", "op": "pre", "value": "/v1/api/" }] }
+  ],
+  "action": {
+    "mitigate": {
+      "action": "redirect",
+      "redirect": { "location": "/v2/api/", "permanent": true }
+    }
+  }
+}
+```
+
+## Health Score Tips
+
+To maximize your configuration health score:
+
+- Add `description` to every rule
+- Use `id` fields with `rule_` prefix and snake_case
+- Avoid regex when simpler operators work
+- Remove disabled rules you no longer need
+- Include rate limiting for API endpoints
+- Include bot protection rules
+- Use IP blocking for known threats

package/skills/doorman/references/templates.md

@@ -0,0 +1,191 @@
+# Templates Reference
+
+Pre-built rule templates for common security patterns. Add them to your config with a single command.
+
+## Usage
+
+```bash
+doorman template                    # Browse available templates interactively
+doorman template <name>             # Add a specific template
+doorman template <name> --config ./path/to/config.json  # Add to specific config
+```
+
+Templates append rules to your existing config. Run `doorman validate` after adding to confirm compatibility.
+
+## Available Templates
+
+### ai-bots
+
+**Block AI Bots Firewall Rule**
+
+Detects and logs known AI crawlers and training data scrapers. Default action is `log` — change to `deny` or `challenge` after reviewing traffic.
+
+```bash
+doorman template ai-bots
+```
+
+Detected bots include: GPTBot, ChatGPT-User, ClaudeBot, Claude-Web, Bytespider, CCBot, Google-Extended, GoogleOther, Amazonbot, Applebot-Extended, Meta-ExternalAgent, PerplexityBot, OAI-SearchBot, Diffbot, anthropic-ai, cohere-ai, and many more.
+
+**Rule added:**
+```json
+{
+  "id": "rule_detect_ai_bots",
+  "name": "Detect AI Bots",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [{ "type": "user_agent", "op": "re", "value": "GPTBot|ChatGPT-User|ClaudeBot|..." }] }
+  ],
+  "action": { "mitigate": { "action": "log" } }
+}
+```
+
+**Customization**: Change `"action": "log"` to `"action": "deny"` to block, or `"action": "challenge"` to CAPTCHA.
+
+**Note**: Uses `re` (regex) operator — works on all Vercel plans, but Cloudflare Enterprise only. For Cloudflare non-Enterprise, split into multiple `sub` (contains) conditions instead.
+
+---
+
+### bad-bots
+
+**Block Bad Bots Firewall Rule**
+
+Detects known malicious bots, scrapers, vulnerability scanners, and attack tools. Comprehensive list of 500+ known bad user agents.
+
+```bash
+doorman template bad-bots
+```
+
+Includes: scrapers (HTTrack, WebCopier, SiteRipper), vulnerability scanners (Nikto, Nmap, Acunetix, SQLmap, WPScan, Nuclei), SEO crawlers (AhrefsBot, SemrushBot, MJ12bot, DotBot), and spam/attack tools (Zeus, Havij, Dirbuster).
+
+**Rule added:**
+```json
+{
+  "id": "rule_detect_bad_bots",
+  "name": "Detect Bad Bots",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [{ "type": "user_agent", "op": "re", "value": "AhrefsBot|SemrushBot|MJ12bot|..." }] }
+  ],
+  "action": { "mitigate": { "action": "log" } }
+}
+```
+
+**Customization**: Same as ai-bots — change action to `deny` for production blocking. Consider `challenge` for borderline bots.
+
+---
+
+### block-ofac-sanctioned-countries
+
+**Block OFAC-Sanctioned Countries**
+
+Blocks traffic from countries under US OFAC (Office of Foreign Assets Control) sanctions. Enforces a one-hour persistent block after first violation.
+
+```bash
+doorman template block-ofac-sanctioned-countries
+```
+
+Countries blocked: Syria (SY), Iran (IR), Russia (RU), Cuba (CU), North Korea (KP).
+
+**Rule added:**
+```json
+{
+  "id": "rule_block_traffic_from_ofac_sanctioned_countries",
+  "name": "Block traffic from OFAC-sanctioned countries",
+  "description": "Blocks traffic from OFAC-sanctioned countries and enforces a one-hour persistent block after the first violation.",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [{ "type": "geo_country", "op": "inc", "value": ["SY", "IR", "RU", "CU", "KP"] }] }
+  ],
+  "action": { "mitigate": { "action": "deny", "actionDuration": "1h" } }
+}
+```
+
+**Customization**: Add or remove country codes as sanctions change. Consult https://sanctionssearch.ofac.treas.gov/ for the current list.
+
+---
+
+### wordpress
+
+**Deny Common WordPress URLs Firewall Rule**
+
+Blocks requests to WordPress-specific paths that are common attack vectors on non-WordPress sites. If your site does not run WordPress, these paths should never receive legitimate traffic.
+
+```bash
+doorman template wordpress
+```
+
+Paths blocked: `/wp-admin`, `/wp-login.php`, `/xmlrpc.php`, `/wp-content`, `/wp-includes`, `/wp-signup.php`, `/wp-activate.php`, `/register.php`, `/wp-register.php`
+
+**Rule added:**
+```json
+{
+  "name": "Deny WordPress URLs",
+  "active": true,
+  "conditionGroup": [
+    { "conditions": [{ "type": "path", "op": "re", "value": "/(wp-admin|wp-login\\.php|xmlrpc\\.php|wp-content|wp-includes|wp-signup\\.php|wp-activate\\.php|register\\.php|wp-register\\.php)" }] }
+  ],
+  "action": { "mitigate": { "action": "deny" } }
+}
+```
+
+**Note**: Uses regex — for Cloudflare non-Enterprise, split into multiple `pre` (prefix) conditions:
+```json
+"conditionGroup": [
+  { "conditions": [{ "type": "path", "op": "pre", "value": "/wp-admin" }] },
+  { "conditions": [{ "type": "path", "op": "pre", "value": "/wp-login.php" }] },
+  { "conditions": [{ "type": "path", "op": "pre", "value": "/xmlrpc.php" }] },
+  { "conditions": [{ "type": "path", "op": "pre", "value": "/wp-content" }] }
+]
+```
+
+## Creating Custom Templates
+
+Templates are TypeScript modules in `src/lib/templates/rules/`. Each exports a `Template` object:
+
+```typescript
+import { Template } from '../types'
+
+export const myTemplate: Template = {
+  metadata: {
+    title: 'My Custom Template',
+    reference: 'https://example.com/docs',
+  },
+  config: {
+    rules: [
+      {
+        id: 'rule_my_template',
+        name: 'My Rule',
+        description: 'What it does',
+        active: true,
+        conditionGroup: [
+          { conditions: [{ type: 'path', op: 'pre', value: '/protected' }] }
+        ],
+        action: { mitigate: { action: 'deny' } },
+      },
+    ],
+  },
+}
+```
+
+Register it in `src/lib/templates/index.ts` to make it available via `doorman template <name>`.
+
+## Template Best Practices
+
+1. **Start with `log` action** — observe traffic before blocking. Switch to `deny` once confident.
+2. **Add descriptions** — templates without descriptions lower the health score.
+3. **Combine templates** — use multiple templates together for layered security.
+4. **Validate after adding** — always run `doorman validate` after adding a template.
+5. **Review regex patterns** — template regex patterns are comprehensive but may need tuning for your specific use case.
+
+## Recommended Starter Stack
+
+```bash
+doorman template ai-bots
+doorman template bad-bots
+doorman template wordpress
+doorman template block-ofac-sanctioned-countries
+doorman validate
+doorman sync
+```
+
+This gives you bot protection, attack path blocking, and geo-compliance in under a minute.

package/skills/doorman/sync/README.md

@@ -0,0 +1,43 @@
+# Auto-Sync to gfargo/skills
+
+These files are templates for setting up auto-sync to the [gfargo/skills](https://github.com/gfargo/skills) central skills repository.
+
+## Setup Steps
+
+1. **In `gfargo/skills`**, create the plugin directory structure:
+
+   ```
+   plugins/security/
+   plugins/security/.claude-plugin/plugin.json   <- copy plugin.json here
+   plugins/security/skills/doorman/              <- synced from this repo
+   ```
+
+2. **Copy `sync-doorman.yml`** to `gfargo/skills/.github/workflows/sync-doorman.yml`
+
+3. **Update `gfargo/skills/.claude-plugin/marketplace.json`** to add the security plugin:
+
+   ```json
+   {
+     "name": "security",
+     "source": "./plugins/security",
+     "description": "Web application firewall management as code with Doorman: create rules, block IPs, rate limit, protect against bots, and deploy WAF configs to Vercel and Cloudflare.",
+     "version": "1.0.0",
+     "author": { "name": "Griffen Fargo" }
+   }
+   ```
+
+4. The workflow runs daily and on `workflow_dispatch`. It:
+   - Checks the latest release tag on `gfargo/doorman`
+   - Compares against `.source-version` in the destination
+   - If newer, clones at that tag, mirrors `skills/doorman/` content
+   - Bumps the security plugin version, commits, tags, and creates a release
+
+## Installation (end users)
+
+Once published:
+
+```bash
+npx skills add gfargo/skills --skill doorman
+```
+
+Or via the `gfargo/skills` README install instructions.

package/skills/doorman/sync/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "security",
+  "description": "Web application firewall management as code with Doorman: create rules, block IPs, rate limit, protect against bots, and deploy WAF configs to Vercel and Cloudflare.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Griffen Fargo",
+    "email": "ghfargo@gmail.com"
+  },
+  "homepage": "https://github.com/gfargo/doorman",
+  "keywords": [
+    "security",
+    "firewall",
+    "waf",
+    "vercel",
+    "cloudflare",
+    "doorman",
+    "iac",
+    "rules",
+    "ip-blocking",
+    "rate-limiting",
+    "bot-protection"
+  ]
+}

package/skills/doorman/sync/sync-doorman.yml

@@ -0,0 +1,80 @@
+name: Sync doorman skill from source
+
+on:
+  schedule:
+    - cron: '17 14 * * *'
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+
+env:
+  SOURCE_REPO: gfargo/doorman
+  SOURCE_SKILL_PATH: skills/doorman
+  DEST_SKILL_PATH: plugins/security/skills/doorman
+  PLUGIN_JSON: plugins/security/.claude-plugin/plugin.json
+  MARKETPLACE_JSON: .claude-plugin/marketplace.json
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check latest doorman release
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          latest=$(gh api "repos/${SOURCE_REPO}/releases/latest" --jq '.tag_name')
+          current=$(cat "${DEST_SKILL_PATH}/.source-version" 2>/dev/null || echo "none")
+          echo "latest=$latest" >> "$GITHUB_OUTPUT"
+          echo "current=$current" >> "$GITHUB_OUTPUT"
+          if [ "$latest" = "$current" ]; then
+            echo "up_to_date=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "up_to_date=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Fetch source at latest tag
+        if: steps.check.outputs.up_to_date == 'false'
+        run: |
+          git clone --depth 1 --branch "${{ steps.check.outputs.latest }}" \
+            "https://github.com/${SOURCE_REPO}.git" /tmp/source
+
+      - name: Mirror skill content
+        if: steps.check.outputs.up_to_date == 'false'
+        run: |
+          rsync -a --delete --exclude='sync/' "/tmp/source/${SOURCE_SKILL_PATH}/" "${DEST_SKILL_PATH}/"
+          echo "${{ steps.check.outputs.latest }}" > "${DEST_SKILL_PATH}/.source-version"
+
+      - name: Bump security plugin version
+        if: steps.check.outputs.up_to_date == 'false'
+        id: bump
+        run: |
+          old=$(jq -r '.version' "${PLUGIN_JSON}")
+          IFS='.' read -r major minor patch <<< "$old"
+          new="${major}.${minor}.$((patch + 1))"
+          jq --arg v "$new" '.version = $v' "${PLUGIN_JSON}" > "${PLUGIN_JSON}.tmp" && mv "${PLUGIN_JSON}.tmp" "${PLUGIN_JSON}"
+          jq --arg v "$new" '(.plugins[] | select(.name == "security") | .version) = $v' "${MARKETPLACE_JSON}" > "${MARKETPLACE_JSON}.tmp" && mv "${MARKETPLACE_JSON}.tmp" "${MARKETPLACE_JSON}"
+          echo "new_version=$new" >> "$GITHUB_OUTPUT"
+
+      - name: Commit and tag
+        if: steps.check.outputs.up_to_date == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add "${DEST_SKILL_PATH}" "${PLUGIN_JSON}" "${MARKETPLACE_JSON}"
+          git commit -m "sync: doorman ${{ steps.check.outputs.latest }} (security v${{ steps.bump.outputs.new_version }})"
+          git tag "v${{ steps.bump.outputs.new_version }}"
+          git push origin HEAD:main
+          git push origin "v${{ steps.bump.outputs.new_version }}"
+
+      - name: Create release
+        if: steps.check.outputs.up_to_date == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "v${{ steps.bump.outputs.new_version }}" \
+            --title "security v${{ steps.bump.outputs.new_version }} — doorman ${{ steps.check.outputs.latest }}" \
+            --notes "Synced security:doorman to [gfargo/doorman@${{ steps.check.outputs.latest }}](https://github.com/${SOURCE_REPO}/releases/tag/${{ steps.check.outputs.latest }})"