How to Use Project Honeypot with NGINX and ModSecurity 3.0

It takes 20 years to build a reputation and 5 minutes to ruin it. If you think about that, you’ll do things differently.
– Warren Buffett

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. ModSecurity 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.


  1. Install NGINX or NGINX Plus.
  2. Install ModSecurity 3.0 using the instructions for NGINX 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 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 {

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;


  • In the server_name directive, for 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=""><!-- 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_key
    SecAction "id:900500,\

    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" "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,, 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='
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


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 open source NGINX, and as the NGINX WAF for NGINX Plus. The NGINX WAF is a precompiled dynamic module that is maintained and fully supported by NGINX, Inc. Try it free for 30 days.

Cover image
Microservices: From Design to Deployment
The complete guide to microservices development