ltm rule command BOTDEFENSE action¶

iRule(1) BIG-IP TMSH Manual iRule(1)

BOTDEFENSE::action
Returns or overrides the action to be taken by Bot Defense.

DESCRIPTION
Returns or overrides the action to be taken by Bot Defense.

Overriding the action may fail on certain cases. For example, overriding to the "browser_challenge" action,
may only be done on requests to which the value of BOTDEFENSE::cs_possible is "true". When overriding the
action, the command returns "ok" if the action was successfully set. Otherwise, the action is not changed, and
the reason for failure is returned.

After a successful action override (resulting in the "ok" string), the action cannot be overridden again.
Attempting to override the action after it was successfully overridden will fail, and the "already forced by
irule" string will be returned.

Syntax

BOTDEFENSE::action

* Returns the action to be taken by Bot Defense: how the received HTTP request is handled. The returned value is one of the following strings:
+ undetermined - the action has not yet been determined; this should only be returned upon an error
+ allow - the HTTP request is allowed to go up the chain
+ alarm - the HTTP request is allowed to go up the chain and will be reported according to profile log
+ block - the request will be blocked. In case of mobile application, the TCP connection will be reset instead.
+ browser_challenge - a browser challenge (HTML + JavaScript) is to be responded to the client. Not applicable to mobile app clients
+ captcha_challenge - a CAPTCHA challenge is to be responded to the client. Not applicable to mobile app clients.
+ redirect_challenge - a redirection challenge (307 redirect) is to be responded to the client. Not applicable to mobile app clients
+ tcp_rst - the TCP connection is to be closed using TCP RST (drop)custom_response - Responds to the client with a custom HTTP response.
+ redirect_to_referring_domain - a 307 redirect response is to be sent to the client, redirecting it to the referring domain
+ internal_bigip_response - a response is to be sent to the client, without forwarding the HTTP request up the chain; the response is an internal part of the Bot Defense mechanism
+ redirect_with_cookie - a 307 redirect response is to be sent to the client, and this response is an internal port of the Bot Defense mechanism
+ custom_response - a custom response is to be sent to the client
+ custom_redirect - a custom redirect response is to be sent to the client
+ honeypot_page - a response page as defined in profile will be sent. In case of mobile application, the TCP connection will be reset instead.
+ redirect_to_pool - the request will be redirected to the pool configured in the profile.

BOTDEFENSE::action allow

* Allows the request to go up the chain

BOTDEFENSE::action alarm

* Allows the request to go up the chain and will be reported according to profile log

BOTDEFENSE::action block

* The request will be blocked by responding with configured blocking page from the profile

BOTDEFENSE::action browser_challenge

* Responds to the client with a browser challenge (HTML + JavaScript).

BOTDEFENSE::action captcha_challenge

* Responds to the client with a CAPTCHA challenge.

* Note that although Bot Defense will send the CAPTCHA challenge screen back to the user, the enforcement is not always done automatically. To enforce the correct CAPTCHA response, the BOTDEFENSE::captcha_status command should be used.

* Also note that this action may bypass the default Bot Defense challenge and validation, and this may cause other requests to be blocked in some cases. Therefore, it is recommended to first check the action, and only use the CAPTCHA challenge if the default action is "allow". That is, use the CAPTCHA as a secondary validation stage, the first being the default browser challenge. See the example in the BOTDEFENSE::captcha_status and BOTDEFENSE::captcha_age commands.

BOTDEFENSE::action redirect_challenge

* Responds to the client with the Bot Defense "redirect challenge", which
* is a method of challenging bots that does not require JavaScript.

BOTDEFENSE::action tcp_rst

* Aborts the transaction (closes the TCP connection) by sending a TCP RST message to the client.

BOTDEFENSE::action custom_response []

* Responds to the client with a custom HTTP response.
* This is normally used to send a blocking page to the client, instead of aborting the connection.
* The is the payload of the HTTP response, and me be given between double-quotes "", or braces {}.
* The is 200 if not supplied.
* The response is sent with the default Bot Defense non-caching headers. If manipulation of the headers or HTTP version is required, this can be done from the HTTP_RESPONSE_RELEASE event, using the HTTP:: commands. See the examples below.
* Note that the command may fail on some cases. So, it is recommended to verify the return status of the command. See below for the blocking-page example.

BOTDEFENSE::action custom_redirect []

* Responds to the client with a custom HTTP redirect.
* This is normally used to redirect the client to a blocking page, instead of aborting the connection.
* The is the URL to place in the Location header of the HTTP response.
* The is 307 if not supplied.
* The response is sent with the default Bot Defense non-caching headers. If manipulation of the headers or HTTP version is required, this can be done from the HTTP_RESPONSE_RELEASE event, using the HTTP:: commands. See the examples below.
* Note that the command may fail on some cases. So, it is recommended to verify the return status of the command. See below for the blocking-page example.

BOTDEFENSE::action honeypot_page

* Responds to the client with a page configured as honeypot page in the profile

BOTDEFENSE::action redirect_to_pool

* The request will be redirected to the pool configured in the profile.
* If no pool configured - tcp rst will be sent.

RETURN VALUE
* When called without any arguments: Returns a string signifying the action to be taken by Bot Defense. If the
action was overridden, the returned action is the overridden one. * When called with an argument for
overriding the action, the return value is a status string. The returned string is "ok" if the command was
successful. Otherwise, the reason for failure is returned.

VALID DURING
BOTDEFENSE_ACTION

EXAMPLES
# EXAMPLE 1: Bypassing enforcement on URL pattern
when BOTDEFENSE_ACTION {
if {[HTTP::uri] starts_with "/t/"} {
log local0. "bypassing enforcement for URI [HTTP::uri]"
set res [BOTDEFENSE::action allow]
log local0. "set action to allow, result \"$res\""
log local0. "resulting action [BOTDEFENSE::action] reason \"[BOTDEFENSE::reason]\""
}
}

# EXAMPLE 2: Instead of blocking the request with TCP RST, respond with a
# blocking-page
when BOTDEFENSE_ACTION {
if {[BOTDEFENSE::action] eq "tcp_rst"} {
# if the custom_response action fails, the tcp_rst action will remain,
# so we don't need to check the return string in this case
BOTDEFENSE::action custom_response "sorry\ni am blocking you\n"
}
}

# EXAMPLE 3: Instead of blocking the request with TCP RST, respond with a
# multi-line blocking-page of 404 status and a response header
when BOTDEFENSE_ACTION {
if {[BOTDEFENSE::action] eq "tcp_rst"} {
set res [BOTDEFENSE::action custom_response {
sorry
i am blocking you
} 404]
if {$res eq "ok"} {
set botdefense_responded 1
}
}
}
when HTTP_RESPONSE_RELEASE {
if {[info exists botdefense_responded]} {
HTTP::header insert "myheader" "blocked request"
}
}

# EXAMPLE 4: Instead of blocking the request with TCP RST, redirect the client
# to a blocking page, and white-list the URL of the blocking-page
when BOTDEFENSE_ACTION {
if {[HTTP::uri] eq "/blocked.html"} {
BOTDEFENSE::action allow
} elseif {[BOTDEFENSE::action] eq "tcp_rst"} {
BOTDEFENSE::action custom_redirect "/blocked.html"
}
}

# EXAMPLE 5: Force the browser_challenge to be sent to the client on the login
# page, even if the cookie is valid (may be used to force the renewal of the
# Bot Defense cookie)
when BOTDEFENSE_ACTION {
if { ([HTTP::uri] eq "/t/login.php") &&
([BOTDEFENSE::action] eq "allow") &&
(not ([BOTDEFENSE::reason] starts_with "passed browser challenge"))} {
BOTDEFENSE::action browser_challenge
}
}

HINTS
SEE ALSO
CHANGE LOG
@BIGIP-12.1 --First introduced the command.

BIG-IP 2020-06-23 iRule(1)