@gfargo/doorman 3.14.0 → 3.14.2

package/skills/doorman/references/rules.md

@@ -2,6 +2,8 @@
 
 Complete reference for creating and configuring Doorman firewall rules.
 
+> **Format note:** this reference covers the **legacy (Vercel-only) rule format** — no `provider`/`providers` field in the config. If your config has `provider`/`providers` set (required for Cloudflare/Fastly), rules use a different shape entirely (`conditions`/`enabled`/flat `action: {type}` instead of `conditionGroup`/`active`/`action: {mitigate}`) — see [cloudflare.md](cloudflare.md)/[fastly.md](fastly.md) for the correct format and field/operator/action support per provider, and `SKILL.md`'s "Rule Shape" section for a side-by-side comparison.
+
 ## Rule Structure
 
 Every rule in the `rules` array has this shape:
@@ -13,8 +15,16 @@ Every rule in the `rules` array has this shape:
   "description": "What this rule does and why",
   "active": true,
   "conditionGroup": [
-    { "conditions": [/* AND — all must match */] },
-    { "conditions": [/* OR — this group is an alternative */] }
+    {
+      "conditions": [
+        /* AND — all must match */
+      ]
+    },
+    {
+      "conditions": [
+        /* OR — this group is an alternative */
+      ]
+    }
   ],
   "action": { "mitigate": { "action": "deny" } }
 }
@@ -22,14 +32,14 @@ Every rule in the `rules` array has this shape:
 
 ### 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). |
+| 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
 
@@ -41,6 +51,7 @@ Every rule in the `rules` array has this shape:
 ```
 
 **Logic**:
+
 - Conditions **within** a group: AND (all must match)
 - **Between** groups: OR (any group matching triggers the rule)
 
@@ -52,35 +63,36 @@ Each condition has:
 { "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`. |
+| 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"` |
+| 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
@@ -89,16 +101,16 @@ Each condition has:
 
 ### 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` |
+| 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
 
@@ -154,13 +166,13 @@ Duration formats: `"30s"`, `"5m"`, `"1h"`, `"1d"`, `"permanent"`
 }
 ```
 
-| 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. |
+| 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
 
@@ -175,10 +187,10 @@ Duration formats: `"30s"`, `"5m"`, `"1h"`, `"1d"`, `"permanent"`
 }
 ```
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `location` | string | Redirect URL (absolute or relative path). |
-| `permanent` | boolean | `true` for 301, `false` for 302. |
+| Field       | Type    | Description                               |
+| ----------- | ------- | ----------------------------------------- |
+| `location`  | string  | Redirect URL (absolute or relative path). |
+| `permanent` | boolean | `true` for 301, `false` for 302.          |
 
 ### Log Only
 
@@ -210,13 +222,13 @@ IP rules go in the `ips` array, separate from `rules`:
 }
 ```
 
-| 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. |
+| 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
 
@@ -262,10 +274,12 @@ IP rules go in the `ips` array, separate from `rules`:
   "name": "Rate Limit POST to API",
   "active": true,
   "conditionGroup": [
-    { "conditions": [
-      { "type": "path", "op": "pre", "value": "/api/" },
-      { "type": "method", "op": "eq", "value": "POST" }
-    ]}
+    {
+      "conditions": [
+        { "type": "path", "op": "pre", "value": "/api/" },
+        { "type": "method", "op": "eq", "value": "POST" }
+      ]
+    }
   ],
   "action": {
     "mitigate": {
@@ -284,10 +298,12 @@ IP rules go in the `ips` array, separate from `rules`:
   "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" }
-    ]}
+    {
+      "conditions": [
+        { "type": "path", "op": "pre", "value": "/api/" },
+        { "type": "header", "op": "nex", "value": true, "key": "X-API-Key" }
+      ]
+    }
   ],
   "action": { "mitigate": { "action": "deny" } }
 }
@@ -327,9 +343,7 @@ IP rules go in the `ips` array, separate from `rules`:
 {
   "name": "Redirect Legacy API",
   "active": true,
-  "conditionGroup": [
-    { "conditions": [{ "type": "path", "op": "pre", "value": "/v1/api/" }] }
-  ],
+  "conditionGroup": [{ "conditions": [{ "type": "path", "op": "pre", "value": "/v1/api/" }] }],
   "action": {
     "mitigate": {
       "action": "redirect",

package/skills/doorman/references/templates.md

@@ -27,6 +27,7 @@ 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",
@@ -58,6 +59,7 @@ 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",
@@ -87,6 +89,7 @@ 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",
@@ -117,18 +120,28 @@ 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)" }] }
+    {
+      "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" }] },
@@ -157,9 +170,7 @@ export const myTemplate: Template = {
         name: 'My Rule',
         description: 'What it does',
         active: true,
-        conditionGroup: [
-          { conditions: [{ type: 'path', op: 'pre', value: '/protected' }] }
-        ],
+        conditionGroup: [{ conditions: [{ type: 'path', op: 'pre', value: '/protected' }] }],
         action: { mitigate: { action: 'deny' } },
       },
     ],