Block Requests

The block requests action continuously observes the request processing rate. When the request rate for the same key meets the blocking condition for multiple consecutive time windows, the system performs the configured reject action for that key for a specified duration. When the blocking duration ends, the system unblocks the key and starts observing it again.

# Use Cases

• A client sustains high-frequency access, and short-term request rate limiting does not prevent repeated retries.
• Distinguish occasional bursts from sustained abnormal traffic and block only request groups that trigger the threshold continuously.
• Apply a captcha, error page, connection closure, or another response to abnormal clients for a specified period.

Block requests acts on requests identified by page rules. To drop all packets from a source IP at the operating system level, use Block Source IP.

# How It Works

This action calculates the request processing rate for each key within an observation time window:

1. Requests below the throttle threshold are not limited.
2. Requests that reach the throttle threshold but have not reached the rejection threshold are delayed.
3. When the request rate reaches the rejection threshold, the system performs the reject action.
4. After the request rate meets the blocking condition for the configured number of consecutive time windows, the system continues to perform the reject action for the blocking duration.
5. When the blocking duration ends, the key is unblocked and the consecutive window count starts over.

# Configuration

In the page rules for the target application, select CC Attack Protection Actions > Block Requests.

# Parameters

1. Key: Groups requests so that they are observed separately. The client IP address is used by default, but you can combine it with keys such as the URI or URI argument. When selecting a URI argument or Cookie, you must also specify the corresponding argument or Cookie name. See Keys.
2. Throttle At: Requests below this rate are not limited. Requests that reach this rate but have not reached the rejection threshold are delayed.
3. Reject At: Once the request rate reaches this value, the system performs the reject action.
4. Time Window: The interval over which the request rate is observed.
5. Block Threshold: The number of consecutive time windows required to trigger blocking.
6. Block Duration: The duration of blocking. When it ends, the system unblocks the key and starts counting consecutive windows again.
7. Reject Action: The action performed when the rejection condition is reached or the key enters the blocked state. See Reject Actions.

The throttle and rejection thresholds can be specified in requests per second or requests per minute. Setting the two thresholds to the same value removes the throttling range, so the reject action is performed as soon as that rate is reached.

# Keys

Available keys include:

• Client IP Address: For example, 1.1.1.1.
• URI: For example, /openresty.
• URI Query Argument: For example, arg1 in /openresty?arg1=val1.
• Request Cookie: For example, c1 in Cookie: c1=v1.
• First IP Address in X-Forwarded-For: For example, 1.1.1.1 in X-Forwarded-For: 1.1.1.1, 1.1.1.2.
• Last IP Address in X-Forwarded-For: For example, 1.1.1.2 in X-Forwarded-For: 1.1.1.1, 1.1.1.2.
• Specified HTTP Request Header: For example, Host.
• Encrypted Cookie: Distinguishes clients by the encrypted Cookie generated by OpenResty Edge. If a request does not carry an encrypted Cookie, the system must fall back to other keys. Therefore, an encrypted Cookie must be combined with another key.

Before using X-Forwarded-For, make sure that a trusted proxy maintains the header and that clients cannot forge it.

# Reject Actions

When the rejection condition is reached or a key enters the blocked state, the system can perform the following preset actions. The default is Return Error Page.

• Close Request Connection: Immediately terminates the client connection without responding to the request.
• Return Error Page: Returns an error page with status code 503 by default.
• Complete hCaptcha Verification: Requires the client to pass an hCaptcha challenge.
• Complete OpenResty Edge Captcha Verification: Uses the OpenResty Edge captcha system to verify the user.
• Redirect Verification: Redirects the request to a verification page. Access can continue only after verification succeeds.
• JavaScript Challenge: Requires the client browser to run JavaScript to distinguish browsers from simple automated programs.
• Private Access Token: Requests client attestation and uses the configured fallback when a valid token is unavailable. Configure a fallback, page template when required, and Clearance Time (default 60 seconds). See Private Access Tokens. This action was first introduced in OpenResty Edge 26.9.1-1.
• Mark as Rejected: Marks the request as rejected and continues processing subsequent page rules. This action was first introduced in 24.9.1-7.

# Verification

After publishing the configuration, use a controlled client to continuously send requests that match the rule, then verify the following behavior in sequence:

1. Requests are processed normally below the throttle threshold.
2. Request latency increases in the throttling range.
3. The reject action takes effect at the rejection threshold.
4. After the blocking condition is met for consecutive time windows, subsequent requests continue to receive the configured response throughout the blocking duration.
5. When the blocking duration ends, requests recover and the consecutive window count starts over.

# Considerations

• A time window that is too short can be overly sensitive to momentary fluctuations, while a window that is too long delays detection of sustained attacks. Tune it to the normal traffic fluctuation period.
• A lower block threshold enters the blocked state more quickly and requires greater attention to false positives.
• When counting only by client IP address, users behind the same NAT or proxy can be treated as a single client.
• For traffic that can include legitimate browser users, prefer recoverable reject actions such as a captcha.