Skip to content

js-challenge: NGINX Javascript challenge module


You can install this module in any RHEL-based distribution, including, but not limited to:

  • RedHat Enterprise Linux 7, 8, 9
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 and Amazon Linux 2023
yum -y install
yum -y install nginx-module-js-challenge

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/;

This document describes nginx-module-js-challenge v0.0.1 released on Jun 27 2022.

A request for stable release exists. Vote up here.


GitHub CodeFactor

Demo website

Simple javascript proof-of-work based access for Nginx with virtually no overhead.

Easy installation: just add load_module /path/to/; to your nginx.conf file and follow the configuration instructions.


Simple configuration

server {
    js_challenge on;
    js_challenge_secret "change me!";

    # ...

Advanced configuration

server {
    js_challenge on;
    js_challenge_secret "change me!";
    js_challenge_html /path/to/body.html;
    js_challenge_bucket_duration 3600;
    js_challenge_title "Verifying your browser...";

    location /static {
        js_challenge off;
        alias /static_files/;

    location /sensitive {
        js_challenge_bucket_duration 600;


  • js_challenge on|off Toggle javascript challenges for this config block
  • js_challenge_secret "secret" Secret for generating the challenges. DEFAULT: "changeme"
  • js_challenge_html "/path/to/file.html" Path to html file to be inserted in the <body> tag of the interstitial page
  • js_challenge_title "title" Will be inserted in the <title> tag of the interstitial page. DEFAULT: "Verifying your browser..."
  • js_challenge_bucket_duration time Interval to prompt js challenge, in seconds. DEFAULT: 3600

Build from source

These steps have to be performed on machine with compatible configuration (same nginx, glibc, openssl version etc.)

  1. Install dependencies
    apt install libperl-dev libgeoip-dev libgd-dev libxslt1-dev libpcre3-dev
  2. Download nginx tarball corresponding to your current version (Check with nginx -v) bash wget tar -xzf nginx-1.16.1.tar.gz export NGINX_PATH=$(pwd)/nginx-1.16.1/
  3. Compile the module
    git clone
    cd ngx_http_js_challenge_module
  4. The dynamic module can be found at ${NGINX_PATH}/objs/

Known limitations / TODO

  • Users with cookies disabled will be stuck in an infinite refresh loop (TODO: redirect with a known query param, if no cookie is specified but the query arg is set, display an error page)
  • If nginx is behind a reverse proxy/load balancer, the same challenge will be sent to different users and/or the response cookie will be invalidated when the user is re-routed to another server. (TODO: use the x-real-ip header when available)


You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-js-challenge.