README.markdown

Description

testcookie-nginx-module is a simple robot mitigation module using cookie based challenge/response.

Challenge cookies can be set using different methods:

"Set-Cookie" + 302/307 HTTP Location redirect

"Set-Cookie" + HTML meta refresh redirect

Custom template, JavaScript can be used here.

To prevent automatic parsing, challenge cookie value can be encrypted with AES-128 in CBC mode using custom/random key and iv, and then decrypted at client side with JavaScript.

Directives

testcookie

syntax:testcookie (on|off|var);

default:off

context:http, server, location, if

on - Enable module

off - Disable module

var - Don't intercept requests, only set module variables.

testcookie_name

syntax:testcookie_name <string>

default:TCK

context:http, server, location

Sets cookie name.

testcookie_domain

syntax:testcookie_domain <string>

default:none, set by browser

context:http, server, location

Sets cookie domain.

testcookie_expires

syntax:testcookie_expires <string>

default:31 Dec 2037 23:55:55 GMT

context:http, server, location

Sets cookie expiration value.

testcookie_path

syntax:testcookie_path <string>

default:/

context:http, server, location

Sets cookie path, useful if you plan to use different keys for locations.

testcookie_secret

syntax:testcookie_secret <string>

default:none

context:http, server, location

Secret string, used in challenge cookie computation, better to be long but static to prevent cookie reset for legitimate users every server restart.
If set to "random" - new secret will be generated every server restart, not recomended(all cookies with previous key will be invalid),
If not set, only value based on testcookie_session will be used.

testcookie_session

syntax:testcookie_session <variable>

default:required configuration directive

context:http, server, location

Sets the challenge generation function input,

$remote_addr - clients IP address will be used as an user unique identifier

$remote_addr$http_user_agent - clients IP + User-Agent

testcookie_arg

syntax:testcookie_arg <string>

default:none

context:http, server, location

Sets GET parameter name, used for cookie setting attempts computation,

If not set - server will try to set cookie infinitely.

testcookie_max_attempts

syntax:testcookie_max_attempts <integer>

default:5

context:http, server, location

Sets maximum number of redirects before user will be sent to fallback URL, according to RFC1945 can't be more than 5.

If set to 0 - server will try to set cookie infinitely(actually, browser will show the error page).

testcookie_p3p

syntax:testcookie_p3p <string>

default:none

context:http, server, location

Sets P3P policy.

testcookie_fallback

syntax:testcookie_fallback <script>

default:none

context:http, server, location

Sets the fallback URL, user will be redirected to after maximum number of attempts, specified by directive testcookie_max_attempts exceded.
Nginx scripting variables can be used here. If not set - client will get 403 after max attempts reached.

testcookie_whitelist

syntax:testcookie_whitelist <network list>

default:none

context:http, server

Sets the networks for which the testing will not be used, add search engine networks here. Currently IPv4 CIDR only.

testcookie_redirect_via_refresh

syntax:testcookie_redirect_via_refresh (on|off);

default:off

context:http, server, location

Set cookie and redirect using HTTP meta refresh, required if testcookie_refresh_template used.

testcookie_refresh_template

syntax:testcookie_refresh_template <string>

default:none

context:http, server, location

Use custom html instead of simple HTTP meta refresh, you need to set cookie manually from the template
Available all the nginx variables and

Copyright & License

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of the authors nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.