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.
SYNOPSIS
BOTDEFENSE::action (allow |
browser_challenge |
captcha_challenge |
redirect_challenge |
tcp_rst |
(custom_response CONTENT
(HTTP_STATUS_CODE)?) |
(custom_redirect LOCATION
(HTTP_STATUS_CODE)?))?
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
+ browser_challenge - a browser challenge (HTML + JavaScript) is to be responded to the client
+ captcha_challenge - a CAPTCHA challenge is to be responded to the client
+ redirect_challenge - a redirection challenge (307 redirect) is to be responded to the client
+ tcp_rst - the TCP connection is to be closed using TCP RST
+ 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
BOTDEFENSE::action allow
* Allows the request to go up the chain
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.
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 2017-01-31 iRule(1)