Block

Block a request based on configured criteria. This action is designed to reduce the attack surface by filtering out malicious clients, unauthorized values, and unexpected protocol artifacts.

Purpose

Important:

Block is for blocking attacks, Validate is for preventing broken contracts.

This action is designed to reduce the attack surface by filtering out malicious or unauthorized clients and values (e.g., unauthorized IP addresses, prohibited content types, bot user agents). It is not intended for API Contract Enforcement (e.g., requiring specific headers to be present). For ensuring strict schema compliance, use the Validate policy.

Configuration Targets

Configure one of the following targets per block action instance. To apply multiple filters, define multiple block action instances.

Table 1. Configuration targets for `block`
Option	Data type	Details
ip	object	Block by IP address (supports CIDR notation and single IPs).
header	object	Block by HTTP header name/value pairs.
queryParam	object	Block by query parameter name/value pairs. Supports query flags (keys without values).
cookie	object	Block by cookie name/value pairs.

Block Modes and Properties

Inside your selected target (e.g., inside header), you must configure exactly one of the following properties to define the blocking logic:

Table 2. Block modes
Property	Logic Type	Behavior	Supported Targets	Example Use Case
`denyList`	Negative Security ("Block bad things")	Blocks the request if a key/value matches an entry in the list. Unknown keys are allowed. Empty list = no requests blocked.	All (IP, Header, Query, Cookie)	Blocking known bad actors (e.g., `User-Agent: EvilBot`) or specific IP addresses.
`allowList`	Positive Security ("Strictly allow only good things")	An exhaustive check. The request is allowed only if every key present in the request is defined in this list and matches the value. Any unknown key causes a block. Empty list = all requests blocked.	All (IP, Header, Query, Cookie)	Strict API lockdown. If your allowList contains `Content-Type` and the client sends it, the action will block if the sent value is not in the list. If the client sends `X-Custom-Header` (not in the list), the request is also blocked.
`constraints`	Conditional Check ("If you send this, it must look like this")	Checks values only for the keys defined in the constraint list. Unknown keys are ignored and do not trigger a block. Empty list = no requests blocked.	Header, Query, Cookie (Not available for IP)	If your constraints list contains `X-Version` and the client sends it, the action will block if the sent value is not in the list. If the client sends `X-Custom-Header` (not in the list), that header is simply ignored.

Important: Important considerations for allowList mode:

Completeness is required: You must explicitly list every header (or cookie/query param) that your upstream service needs. If a client sends a standard header like Accept or User-Agent and it is not in your list, the request will be blocked.
"Opting Out" of value checks: If you need to allow a header but do not care about its value, you must still add it to the list. You can use a regex wildcard (.*) to allow any value.
When to switch: If you find yourself adding many headers with wildcard values just to let normal traffic pass, Constraints Mode is likely a better fit.

Pattern Matching (Regex)

For Headers, Cookies, and Query Parameters, you can use Regular Expressions by specifying the valueType in your item configuration:

plain (Default): The value must match the configuration string exactly.
regex: The value must match the provided regular expression.

Query Parameter Special Handling

Query parameters support an additional configuration option for handling flags (keys without values):

Normal pair: Matches ?search=books - { "name": "search", "value": "books" }
Empty value: Matches ?search= (key present, value is empty string) - { "name": "search", "value": "" }
No Value (Flag): Matches ?flag (key present, no equals sign) - { "name": "flag" } or { "name": "flag", "value": null }. Note: Regex cannot be used for flags.

Block specific IP addresses using denyList

- block:
    version: 1.0.0
    ip:
      denyList:
        - "192.168.1.100"
        - "10.0.0.0/8"
        - "1.2.3.4"

Allow only specific IP addresses using allowList

- block:
    version: 1.0.0
    ip:
      allowList:
        - "192.168.1.0/24"
        - "10.0.0.1"

Only requests from the listed IP addresses or ranges are allowed. All others are blocked.

Block known malicious User-Agent headers using denyList with regex

- block:
    version: 1.0.0
    header:
      denyList:
        - name: "User-Agent"
          value: "EvilBot 1.0"
          valueType: "plain"
        - name: "X-Exploit"
          value: ".*"
          valueType: "regex"
        - name: "X-Debug"
          value: "(dump|trace)"
          valueType: "regex"

This blocks specific User-Agent values, any X-Exploit header regardless of value, and X-Debug headers containing "dump" or "trace".

Strict API lockdown using allowList for headers

- block:
    version: 1.0.0
    header:
      allowList:
        - name: "Content-Type"
          value: "application/json"
          valueType: "plain"
        - name: "Authorization"
          value: "^Bearer [a-zA-Z0-9._-]+$"
          valueType: "regex"
        - name: "X-Request-ID"
          value: "^[a-f0-9-]{36}$"
          valueType: "regex"
        - name: "User-Agent"
          value: ".*"
          valueType: "regex"

Only the listed headers are allowed. Content-Type must be exactly "application/json", Authorization must be a Bearer token, X-Request-ID must be a UUID, and User-Agent can be any value. If the client sends any other header (e.g., Accept, Host), the request is blocked.

Validate specific headers if present using constraints

- block:
    version: 1.0.0
    header:
      constraints:
        - name: "X-Version"
          value: "^(v1|v2)$"
          valueType: "regex"
        - name: "X-Tenant"
          value: "acme-corp"
          valueType: "plain"

Standard headers like User-Agent, Accept, etc. pass through without checking. However, if the client sends X-Version, it must be "v1" or "v2". If X-Tenant is sent, it must be "acme-corp". Other headers are ignored.

Block specific query parameters using denyList

- block:
    version: 1.0.0
    queryParam:
      denyList:
        - name: "debug"
          value: "true"
          valueType: "plain"
        - name: "admin"

Blocks requests with ?debug=true or ?admin (flag without value).

Validate cookie constraints

- block:
    version: 1.0.0
    cookie:
      constraints:
        - name: "session_type"
          value: "admin|superuser"
          valueType: "regex"

If the session_type cookie is present, it must match "admin" or "superuser". Other cookies are allowed.