{"id":51124506,"url":"https://github.com/dvershinin/testcookie-nginx-module","last_synced_at":"2026-06-25T06:01:27.271Z","repository":{"id":46870500,"uuid":"198983170","full_name":"dvershinin/testcookie-nginx-module","owner":"dvershinin","description":"simple robot mitigation module using cookie based challenge/response technique. Not supported any more.","archived":false,"fork":true,"pushed_at":"2022-07-19T19:34:28.000Z","size":284,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-19T13:50:15.140Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://kyprizel.github.com/testcookie-nginx-module/","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"kyprizel/testcookie-nginx-module","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dvershinin.png","metadata":{"files":{"readme":"README","changelog":"Changelog","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-26T08:57:45.000Z","updated_at":"2024-01-20T21:50:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dvershinin/testcookie-nginx-module","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/dvershinin/testcookie-nginx-module","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dvershinin%2Ftestcookie-nginx-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dvershinin%2Ftestcookie-nginx-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dvershinin%2Ftestcookie-nginx-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dvershinin%2Ftestcookie-nginx-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dvershinin","download_url":"https://codeload.github.com/dvershinin/testcookie-nginx-module/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dvershinin%2Ftestcookie-nginx-module/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34761847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-25T06:01:23.870Z","updated_at":"2026-06-25T06:01:27.265Z","avatar_url":"https://github.com/dvershinin.png","language":"C","funding_links":[],"categories":["Bot mitigation"],"sub_categories":[],"readme":"DESCRIPTION\n\n    testcookie-nginx-module is a simple robot mitigation module using cookie based challenge/response.\n    Challenge cookies can be set using different methods:\n    *   \"Set-Cookie\" + 302/307 HTTP Location redirect\n    *   \"Set-Cookie\" + HTML meta refresh redirect\n    *   Custom template, JavaScript can be used here.\n    To prevent automatic parsing, challenge cookie value can\n    be encrypted with AES-128 in CBC mode using custom/random key and iv,\n    and then decrypted at client side with JavaScript.\n\n\nDIRECTIVES\n\n    testcookie\n        on - enable module\n        off - disable module\n        var - don't intercept requests, only set cookie vars\n\n    testcookie_name\n        cookie name, default is TCK\n\n    testcookie_domain\n        cookie domain, default is none, set by browser\n\n    testcookie_expires\n        cookie expiration value, default 31 Dec 2037 23:55:55 GMT\n\n    testcookie_path\n        cookie path, useful if you plan to use different keys for locations. default is /\n\n    testcookie_samesite\n        cookie samesite attribute, allows you to declare if your cookie should be restricted \n        to a first-party or same-site context. Default is None (Cookies will be sent in all contexts,\n        i.e sending cross-origin is allowed.) Accepts three values: Lax, Strict, None.\n\n    testcookie_secret\n        secret string, used in challenge cookie computation, should be 32 bytes or more,\n        better to be long but static to prevent cookie reset for legitimate users every server restart.\n        if set to \"random\" - new secret will be generated every server restart, not recomended(all cookies with previous key will be invalid),\n\n    testcookie_session\n        sets the challenge generation function input,\n            $remote_addr - clients IP address will be used as an user unique identifier\n            $remote_addr$http_user_agent - clients IP + User-Agent\n        * required configuration directive\n\n    testcookie_arg\n        GET parameter name, used for cookie setting attempts computation\n        if not set - server will try to set cookie infinitely(actually, browser will show the error page after 5 attempts).\n\n    testcookie_max_attempts\n        maximum number of redirects before user will be sent to fallback URL, according to RFC1945 can't be more than 5\n        if set to 0 or testcookie_arg not set - server will try to set cookie infinitely.\n\n    testcookie_p3p\n        P3P policy, default is none.\n\n    testcookie_fallback\n        sets the fallback URL, user will be redirected to after maximum number of attempts, specified by directive\n        testcookie_max_attempts exceded. nginx scripting variables can be used here.\n        if not set - client will get 403 after max attempts reached.\n\n    testcookie_whitelist\n        sets the networks for which the testing will not be used, add search engine networks here\n        currently IPv4 CIDR only.\n\n    testcookie_pass\n        variable name, if variable set to 1 cookie check will not be performed,\n        can be used for more complex whitelisting.\n\n    testcookie_redirect_via_refresh\n        set cookie and redirect using HTTP meta refresh, required if testcookie_refresh_template used (on|off)\n        default is off.\n\n    testcookie_refresh_template\n        custom html instead of simple HTTP meta refresh, you need to set cookie manually from the template\n        available all the nginx variables and\n\n            $testcookie_nexturl - URL the client should be redirected to\n            $testcookie_got - cookie value received from client, empty if no cookie or it does not match format\n            $testcookie_set - correct cookie value we're expecting from client\n            $testcookie_ok - user passed test (1/0). Note: changed from \"yes\"/\"no\" in v1.10\n\n        also, if testcookie_refresh_encrypt_cookie enabled there are three more variables\n            $testcookie_enc_key - encryption key (32 hex digits)\n            $testcookie_enc_iv - encryption iv (32 hex digits)\n            $testcookie_enc_sec - encrypted cookie value (32 hex digits)\n\n    testcookie_refresh_status\n        custom HTTP response status. 200 by default.\n\n    testcookie_deny_keepalive\n        close connection just after setting the cookie, no reason to keep connections with bots (on|off)\n        default is off.\n\n    testcookie_get_only\n        process only GET requests, POST requests will be bypassed (on|off)\n        default is off.\n\n    testcookie_https_location\n        redirect to https protocol after setting the cookie, also affects $testcookie_nexturl\n        useful with 3dparty SSL offload (on|off)\n        default is off.\n\n    testcookie_refresh_encrypt_cookie\n        encrypt cookie variable, used with testcookie_refresh_template to force client-side decryption\n        AES-128 CBC mode used (on|off)\n        default is off.\n\n    testcookie_refresh_encrypt_cookie_key\n        encryption key\n        possible values:\n                random - new key generated every nginx restart\n                32 hex digits - static key, useful if you plan to obfuscate it deep in client-side javascript\n        * required directive if encryption enabled\n\n    testcookie_refresh_encrypt_iv\n        encryption iv\n        possible values:\n                random - new iv generated for every client request\n                random2 - new iv generated for every nginx restart\n                32 hex digits - static iv, useful if you plan to obfuscate it deep in client-side javascript\n        default is random\n\n    testcookie_internal\n        enable testcookie check for internal redirects (on|off)\n        useful for this type of configs:\n            rewrite ^/(.*)$ /index.php?$1 last;\n        default is off.\n\n    testcookie_httponly_flag\n        adds HttpOnly flag for cookie (on|off)\n        default is off.\n\n    testcookie_secure_flag\n        adds Secure flag for cookie (on|off|$variable)\n        default is on.\n        any variable value except \"on\" interpreted as False.\n\n    testcookie_port_in_redirect\n        Keep server port in redirect (on|off)\n        default is off.\n\n\nINSTALLATION\n\n    Grab the nginx source code from nginx.org (\u003chttp://nginx.org/\u003e), for\n    example, the version 1.1.15 (see nginx compatibility), and then build\n    the source with this module:\n\n        wget 'http://nginx.org/download/nginx-1.1.15.tar.gz'\n        tar -xzvf nginx-1.1.15.tar.gz\n        cd nginx-1.1.15/\n        ./configure --add-module=/path/to/testcookie-nginx-module\n\n        make\n        make install\n\n    If you use nginx \u003e= 1.9.11 you can compile Dynamic module.\n\n        wget 'http://nginx.org/download/nginx-1.9.11.tar.gz'\n        tar -xzvf nginx-1.9.11.tar.gz\n        cd nginx-1.9.11/\n        ./configure --add-dynamic-module=/path/to/testcookie-nginx-module\n\n        make\n        make install\n\n    Then load \"ngx_http_testcookie_access_module.so\" using \"load_module\" directive.\n\n\n    For using client-side cookie decryption,\n    you need to manually grab SlowAES (\u003chttp://code.google.com/p/slowaes/\u003e)\n    JavaScript AES implementation, patch it(utils/aes.patch) and put it to document root.\n\nCOMPATIBILITY\n\n    Module was tested with nginx 1.1+, but should work with 1.0+.\n\nEXAMPLE CONFIGURATION\n\n    http {\n        #default config, module disabled\n        testcookie off;\n\n        #setting cookie name\n        testcookie_name BPC;\n\n        #setting secret\n        testcookie_secret keepmesecret;\n\n        #setting session key\n        testcookie_session $remote_addr;\n\n        #setting argument name\n        testcookie_arg ckattempt;\n\n        #setting maximum number of cookie setting attempts\n        testcookie_max_attempts 3;\n\n        #setting p3p policy\n        testcookie_p3p 'CP=\"CUR ADM OUR NOR STA NID\", policyref=\"/w3c/p3p.xml\"';\n\n        #setting fallback url\n        testcookie_fallback http://google.com/cookies.html?backurl=http://$host$request_uri;\n\n        #configuring whitelist\n        testcookie_whitelist {\n            8.8.8.8/32;\n        }\n\n\n        #setting redirect via html code\n        testcookie_redirect_via_refresh on;\n\n        #enable encryption\n        testcookie_refresh_encrypt_cookie on;\n\n        #setting encryption key\n        testcookie_refresh_encrypt_cookie_key deadbeefdeadbeefdeadbeefdeadbeef;\n\n        #setting encryption iv\n        testcookie_refresh_encrypt_cookie_iv deadbeefdeadbeefdeadbeefdeadbeef;\n\n        #setting response template\n        testcookie_refresh_template '\u003chtml\u003e\u003cbody\u003esetting cookie...\u003cscript type=\\\"text/javascript\\\" src=\\\"/aes.min.js\\\" \u003e\u003c/script\u003e\u003cscript\u003efunction toNumbers(d){var e=[];d.replace(/(..)/g,function(d){e.push(parseInt(d,16))});return e}function toHex(){for(var d=[],d=1==arguments.length\u0026\u0026arguments[0].constructor==Array?arguments[0]:arguments,e=\"\",f=0;f\u003cd.length;f++)e+=(16\u003ed[f]?\"0\":\"\")+d[f].toString(16);return e.toLowerCase()}var a=toNumbers(\"$testcookie_enc_key\"),b=toNumbers(\"$testcookie_enc_iv\"),c=toNumbers(\"$testcookie_enc_set\");document.cookie=\"BPC=\"+toHex(slowAES.decrypt(c,2,a,b))+\"; expires=Thu, 31-Dec-37 23:55:55 GMT; path=/\";location.href=\"$testcookie_nexturl\";\u003c/script\u003e\u003c/body\u003e\u003c/html\u003e';\n\n        server {\n            listen 80;\n            server_name test.com;\n\n\n            location = /aes.min.js {\n                gzip  on;\n                gzip_min_length 1000;\n                gzip_types      text/plain;\n                root /var/www/public_html;\n            }\n\n            location = /w3c/p3p.xml {\n                root /var/www/public_html;\n            }\n\n            location / {\n                #enable module for specific location\n                testcookie on;\n                proxy_set_header   Host             $host;\n                proxy_set_header   X-Real-IP        $remote_addr;\n                proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;\n                proxy_pass http://127.0.0.1:80;\n            }\n        }\n    }\n\nTESTS SUITE\n\n    This module comes with a Perl-driven test suite.\n    Thanks to the Test::Nginx (\u003chttp://search.cpan.org/perldoc?Test::Nginx\u003e) module in the Perl world.\n\nSOURCES\n\n    Available on github at kyprizel/testcookie-nginx-module\n    (\u003chttp://github.com/kyprizel/testcookie-nginx-module\u003e).\n\nTODO\n\n    *   Code review\n    *   More encryption algos (-)\n    *   Statistics (-)\n\nBUGS\n\n    Feel free to report bugs and send patches to kyprizel@gmail.com\n    or use github's issue tracker(\u003chttp://github.com/kyprizel/testcookie-nginx-module/issues\u003e).\n\nSUPPORT THE PROJECT\n\n    Send your donations to 1FHmPTP6aDBAzVtM7Pe7Y69zqhjPRx847s\n\nCOPYRIGHT \u0026 LICENSE\n\n    Copyright (C) 2011-2017 Eldar Zaitov (kyprizel@gmail.com).\n\n    All rights reserved.\n\n    This module is licenced under the terms of BSD license.\n\n    Redistribution and use in source and binary forms, with or without\n    modification, are permitted provided that the following conditions are\n    met:\n\n    *   Redistributions of source code must retain the above copyright\n        notice, this list of conditions and the following disclaimer.\n\n    *   Redistributions in binary form must reproduce the above copyright\n        notice, this list of conditions and the following disclaimer in the\n        documentation and/or other materials provided with the distribution.\n\n    *   Neither the name of the authors nor the names of its contributors\n        may be used to endorse or promote products derived from this\n        software without specific prior written permission.\n\n    THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND\n    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\n    ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE\n    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\n    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\n    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY\n    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF\n    SUCH DAMAGE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdvershinin%2Ftestcookie-nginx-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdvershinin%2Ftestcookie-nginx-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdvershinin%2Ftestcookie-nginx-module/lists"}