How to Use Project Honeypot with NGINX and ModSecurity 3.0

[Editor – The NGINX ModSecurity WAF module for NGINX Plus officially went End-of-Sale as of April 1, 2022 and is transitioning to End-of-Life effective March 31, 2024. For more details, see F5 NGINX ModSecurity WAF Is Transitioning to End-of-Life<.htmla> on our blog.]

To help fight crime, the FBI maintains a public Ten Most Wanted list of the most dangerous criminals out there. Anyone who sees someone on the list will know to call the police, making it more difficult for these criminals to commit more crimes.

In the world of technology, there’s a similar concept called Project Honeypot. Project Honeypot maintains a list of known malicious IP addresses, available free to the public. The NGINX ModSecurity WAF integrates with Project Honeypot and can automatically block IP addresses on the Project Honeypot list. This process is known as IP reputation.

In this blog post, we cover how to configure ModSecurity 3.0 to integrate with Project Honeypot, for both NGINX and NGINX Plus.

Why “Project Honeypot”?

Project Honeypot is a community‑driven online database of IP addresses that are suspected spammers or bots. Each IP address is assigned a threat score between 0 and 255; the higher the number, the more likely the IP address is to be malicious.

The Project Honeypot database is powered by a network of volunteers who set up “honeypots”. A honeypot, in this context, is a fake page on a site that shows up when a bot scans a site, but is invisible to regular people accessing the site with a web browser. When the scanner follows the honeypot link and attempts to interact with the page – harvesting, for example, an embedded honeypot email address – the IP address is added to the database.

For more details on how Project Honeypot works, click here.

Prerequisites

1. Install NGINX Open Source or NGINX Plus.
2. Install ModSecurity 3.0 using the instructions for NGINX Open Source or NGINX Plus.
3. Install and enable the ModSecurity core rule set (CRS).

Note: ModSecurity 3.0 for NGINX Plus is now known as the NGINX ModSecurity WAF.

1. Set Up Your Honeypot

To start using Project Honeypot, set up a honeypot on your site using the script provided by Project Honeypot:

1. Sign up a for a free Project Honeypot account.
2. Set up your honeypot – Project Honeypot offers the honeypot script in PHP, Python, ASP, and a few other languages.
3. Download the honeypot script.

In this scenario, we use PHP for the scripting language. If your preferred language is not supported by Project Honeypot, PHP is a good choice, because it’s very easy to configure NGINX and NGINX Plus to run PHP scripts using PHP‑FPM.

There are plenty of tutorials online on how to install PHP‑FPM. For Ubuntu 16.04 and later, you can use these commands:

$ apt-get update$ apt-get -y install php7.0-fpm

You can then configure the Project Honeypot PHP script by adding this server block:

server {    server_name www.example.com;

    location ~ .php$ {
        modsecurity off;
        root /code;
        try_files $uri =404;
        fastcgi_split_path_info ^(.+.php)(/.+)$;
        fastcgi_pass localhost:9000;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
}

Notes:

• In the server_name directive, for www.example.com substitute the domain name you registered with Project Honeypot.
• ModSecurity must be disabled on the honeypot script for it to function properly.
• In the root directive, for /code substitute the directory where you placed the Project Honeypot script.

Once the script is installed, access it in a web browser and click the activation link to activate the honeypot.

2. Add the Honeypot Link to All Pages

The next step is to configure NGINX or NGINX Plus to add the honeypot link to all pages.

To catch bots and scanners, insert a link to the honeypot script on every page. The link is invisible to regular people using a web browser but visible to bots and scanners. Here, we use the sub_filter directive to add the link to the bottom of each page.

location / {    proxy_set_header Host $host;
    proxy_pass http://my_upstream;

    sub_filter '</html>' 
               '<a href="http://www.example.com/weddingobject.php"><!-- hightest --></a></html>';
}

In this example, the name of our PHP honeypot file is weddingobject.php. The sub_filter directive looks for the HTML end‑of‑page tag, </html>, and inserts the invisible link there.

3. Enable IP Reputation in the Core Rule Set

Now that our honeypot is set up, we can configure ModSecurity to query Project Honeypot on all HTTP requests.

1. Request a Project Honeypot http:BL access key.

2. In the file /usr/local/owasp-modsecurity-crs-3.0.0/crs-setup.conf, which you installed according to the instructions for setting up the CRS, locate the SecHttpBlKey block.

   Uncomment all the lines in the block and enter the API key you got in Step 1 as the parameter to SecHttpBlKey:

   SecHttpBlKey my_api_keySecAction "id:900500,
     phase:1,
     nolog,
     pass,
     t:none,
     setvar:tx.block_search_ip=0,
     setvar:tx.block_suspicious_ip=1,
     setvar:tx.block_harvester_ip=1,
     setvar:tx.block_spammer_ip=1"

   Note that block_search_ip is disabled in the above example, as it’s unlikely that you want to block search engine crawlers.

3. Reload the configuration for the changes to take effect.

   $ nginx -t && nginx -s reload

At this point, Project Honeypot is fully enabled and ModSecurity queries Project Honeypot on all HTTP requests. To minimize the performance impact, only the first request from a given IP address is sent to Project Honeypot, and the results of the query are cached.

4. Verify It Works

The Project Honeypot queries are based off the client source IP address. It’s not easy to spoof a source IP address, so a good way to test that the functionality is working is by adding this custom rule to /etc/nginx/modsec/main.conf. It sends the value of the IP address argument, passed in as part of the request, to Project Honeypot:

SecRule ARGS:IP "@rbl dnsbl.httpbl.org" "phase:1,id:171,t:none,deny,nolog,auditlog,msg:'RBL Match for SPAM Source'

Reload the configuration for the rule to take effect:

$ nginx -t && nginx -s reload

Then run the following curl command to test the rule with an IP address from Project Honeypot’s list of known bad IP addresses (substitute that address for the sample address used here, 203.0.113.20, which is a standard address reserved for documentation). If the rule works correctly, the request is blocked with status code 403.

$ curl -i -s -k -X $'GET' 'http://localhost/?IP=203.0.113.20'
HTTP/1.1 403 Forbidden
Server: nginx/1.13.4
Date: Wed, 04 Oct 2017 21:29:17 GMT
Content-Type: text/html
Transfer-Encoding: chunked
Connection: keep-alive

Summary

In this blog post, we covered the steps for configuring ModSecurity 3.0 to work with Project Honeypot. Project Honeypot is a very useful tool for automatically blocking known bad actors. It’s also free and community‑driven.

ModSecurity 3.0 is available for both NGINX Open Source, and as the NGINX ModSecurity WAF module for NGINX Plus. NGINX ModSecurity WAF is a precompiled dynamic module that is maintained and fully supported by NGINX, Inc. Try it free for 30 days.

[NGINX ModSecurity WAF officially went End-of-Sale as of April 1, 2022 and is transitioning to End-of-Life effective March 31, 2024. For more details, see F5 NGINX ModSecurity WAF Is Transitioning to End-of-Life<.htmla> on our blog.]