Sticky Cookie
Sticky cookie is a special HTTP cookie that is generated by TempestaFW. It allows for unique identification of each client or can be used as challenge cookie for simple L7 DDoS mitigation when bots are unable to process cookies. It is also used for a load balancing.
When used, TempestaFW sticky cookie is expected in HTTP requests. Otherwise, TempestaFW asks in an HTTP response that sticky cookie is present in HTTP requests from a client. Default behaviour is that TempestaFW sticky cookies are not used.
Normal browsers supports cookies and follows redirects:
Bots not supporting cookies will be filtered:
The use and behaviour of TempestaFW sticky cookies is controlled by a single configuration directive that can have several parameters. The full form of the directive and parameters is as follows:
sticky [name=<COOKIE_NAME>] [enforce] [max_misses=<LIMIT>] [timeout=<TMT>];
name parameter specifies a custom Tempesta sticky cookie name COOKIE_NAME
for use in HTTP requests. It is expected that it is a single word without
whitespaces. When not specified explicitly, a default name is used.
enforce parameter demands that Tempesta sticky cookie is present in each
HTTP request. If it is not present in a request, a client receives HTTP 302
response from Tempesta that redirects the client to the same URI, and prompts
that Tempesta sticky cookie is set in requests from the client.
max_misses parameter sets the maximum count of redirected requests
(with no cookie or with incorrect cookie value). This option is applicable
only if 'enforce' mode is enabled. If configured limit is exhausted, the
corresponding client will be blocked. LIMIT is non-negative integer
(default value is 0, which means that limit verification is disabled).
timeout - sets the maximum period between the first redirected request and
successful cookie verification. This option is applicable only if 'enforce' mode
is enabled and 'max_misses' parameter has value greater then zero. If configured
timeout is expired, the corresponding client will be blocked. TMT is non-negative
integer (default value is 0, which means that timeout tracking is disabled).
Below are examples of TempestaFW sticky cookie directive.
sticky;
Enable Tempesta sticky cookie. Default cookie name is used. Tempesta expects
that Tempesta sticky cookie is present in each HTTP request. If it is not
present, then Tempesta includes Set-Cookie header field in an HTTP response,
which prompts that Tempesta sticky cookie with default name is set in requests
from the client.
sticky enforce;
Enable Tempesta sticky cookie. Default cookie name is used. Tempesta expects
that Tempesta sticky cookie is present in each HTTP request. If it is not
present, Tempesta sends HTTP 302 response that redirects the client to
the same URI and includes Set-Cookie header field, which prompts that
Tempesta sticky cookie with default name is set in requests from the client.
sticky name="__cookie__";
Enable Tempesta sticky cookie. The name of the cookie is __cookie__.
Tempesta expects that Tempesta sticky cookie is present in each HTTP request.
If it is not present, then Tempesta includes Set-Cookie header field in
an HTTP response, which prompts that Tempesta sticky cookie with the name
__cookie__ is set in requests from the client.
sticky name="__cookie__" enforce max_misses=10 timeout=15;
Enable Tempesta sticky cookie. The name of the cookie is __cookie__.
Tempesta expects that Tempesta sticky cookie is present in each HTTP request.
If it is not present, Tempesta sends HTTP 302 response that redirects
the client to the same URI and includes Set-Cookie header field, which
prompts that Tempesta sticky cookie with the name __cookie__ is set in
requests from the client. If the number of HTTP requests without sticky cookie
will exceed 10 or 15 seconds have elapsed since first redirected request until
successful cookie verification, such client will be blocked.
Sticky cookie value is calculated on top of client IP, User-Agent, session timestamp and the secret used as a key for HMAC.
sticky_secret <SECRET_PHRASE>; The option sets the secret string used for HMAC
calculation. It's desirable to keep this value in secret to prevent automatic
cookies generation on attacker side.
Defaults: a new random value on every start. This means that all user HTTP sessions are
invalidated on Tempesta restart.
<SECRET_PHRASE>: quoted secret string, maximum length is 20 bytes.
Example:
sticky_secret "f00)9eR59*_/22";
When HTTP session expires the client receives 302 redirect with new cookie value if enforced sticky cookie is used. This option doesn't affect sticky cookie expire time - it's a session, temporal, cookie.
sess_lifetime <SECONDS>: HTTP session lifetime in seconds.
Defaults: 0, i.e. unlimited life time.
Example:
sess_lifetime 900;
Client too often trying to reach resource with incorrect Sticky Cookie value will be blocked. Client too often trying to request a new sticky cookie will be blocked. Client trying to acquire too lot of simultaneous sessions will be blocked.
The feature is still under development and is planned for upcoming 0.6 release.
While the Sticky Cookie option is a good solution to protect backend servers from the simpliest bots, JavaScript Challenge options enhances the protection to filter bots which are capable to follow redirects and suppot cookies.
When a new client client tries to access the protected resource, TempestaFW
responds with 503 status code, Set-Cookie: header and JavaScript code in
message body. JavaScript code will force client to reload resource inside of
allowed time frame. After the client reloads resource in allowed time frame
it will be granted to have access to the protected resource. JavaScript
challenge won't be sent to the client once again in this session. After the
sticky cookie assigned to the client will expire, a new JS challenge will be
performed.
If client tries to reach resource outside of allowed time frame, it's requests will be treated as Sticky Cookie violation and will be filtered. Client will be blocked if it violates cookies too often.
If bot is a full web stack client (full featured web browser), it can process JavaScript challenge and proper configuration of Sticky Cookie rate limits is required.
js_challenge delay_min=<TIME> delay_range=<TIME> [resp_code=<CODE>]
[delay_limit=<TIME>] [SCRIPT_TEMPLATE];
delay_min: Start of allowed time frame - delay before client is allowed to
repeat it's request with Sticky Cookie set. Value is used in JS challenge code
and to be sent to client.
delay_range: Duration of allowed time frame - maximum delay when client is
allowed to send request with Sticky Cookie set. Value is used in JS challenge
code and to be sent to client.
delay_limit: Maximum difference between current time on evaluation client's
request and Sticky Cookie generation time. Optional parameter.
resp_code: Status code for response with JS challenge. Optional parameter,
default is 503.
<SCRIPT_TEMPLATE>: Path to response template with JS challenge script.
Optional parameter, default is /etc/tempesta/js_challenge.html, see
Custom JS challenge template chapter.
<TIME>: time in usecs.
NOTE: During start process "tempesta.sh' uses 'grep' to update <SCRIPT_TEMPLATE> file with values described in 'js_challenge' directive, so line breaks are not allowed inside directives
js_challengeandsticky.
Examples:
js_challenge resp_code=503 delay_min=1000 delay_range=1000 delay_limit=3000 /etc/ddos_redirect.html;
js_challenge delay_min=1000 delay_range=1000;
It's recommended to modify default JS challenge response template file
js_challenge.tpl located in configuration files directory
(/etc/tempesta/ by default) rather than provide a brand new template file
since JS challenge code must be synchronised with TempestaFW configuration file.
Attribute name of sticky directive, attributes delay_min and delay_range
of js_challenge directive must be passed to JS challenge code template.