NinjaFirewall (Pro Edition): The .htninja configuration file

This post is about the .htninja configuration file for NinjaFirewall Pro Edition. If you’re looking for NinjaFirewall WP Edition, please consult this post instead.

NinjaFirewall (Pro/Pro+ Edition) can use an optional configuration file that allows users to prepend their own PHP code to the firewall.
This file must be named .htninja and must be located either:

• In the folder above your website document root:
  If your document root is /home/user/public_html/, the location of the file will be /home/user/.htninja.
  This is the recommended choice. Because it is located outside the document root, the file is relatively safe and protected. However, if you have an open_basedir restriction, PHP will not be able to access it.

• In the document root folder:
  If your document root is /home/user/public_html/, the location of the file will be /home/user/public_html/.htninja.
  Recommended only if you have an open_basedir restriction. If you are using the Apache HTTP server, the file is relatively protected because, by default, it will never serve a file whose name starts with .ht*. However, if you are using Nginx or any other HTTP server that doesn’t use .htaccess files, you must set it up so that it will block any access to the file from a web browser.

NinjaFirewall’s package contains a sample file, named .htninja.sample. It is a regular PHP file. Note that it does not contain a PHP closing tag (?>). We recommend to keep it that way, because if there is a space or new line character after a closing tag, it may trigger errors on your site (PHP would need to send HTTP headers in order to ouput those characters before your website is loaded). This problem does not occur when the PHP closing tag is missing.
You can check if the .htinja file was detected from your NinjaFirewall’s admin dashboard, by clicking on the “Firewall > Overview” menu:

Server variables

You can add/modify server variables in the .htninja file. For instance, users of the CDN service Cloudflare can copy the visitor real IP (HTTP_CF_CONNECTING_IP) into the REMOTE_ADDR variable so that NinjaFirewall will use the correct IP:

<?php
/*
 +============================================================================================+
 | NinjaFirewall optional configuration file                                                  |
 |                                                                                            |
 | See: https://blog.nintechnet.com/ninjafirewall-pro-edition-the-htninja-configuration-file/ |
 +============================================================================================+
*/

// Users of Cloudflare CDN:
if (! empty($_SERVER["HTTP_CF_CONNECTING_IP"]) &&
 filter_var($_SERVER["HTTP_CF_CONNECTING_IP"],FILTER_VALIDATE_IP)) {
   $_SERVER["REMOTE_ADDR"] = $_SERVER["HTTP_CF_CONNECTING_IP"];
}

Users of the Incapsula CDN service should use the HTTP_INCAP_CLIENT_IP variable instead:

<?php
/*
 +============================================================================================+
 | NinjaFirewall optional configuration file                                                  |
 |                                                                                            |
 | See: https://blog.nintechnet.com/ninjafirewall-pro-edition-the-htninja-configuration-file/ |
 +============================================================================================+
*/

// Users of Incapsula CDN:
if (! empty($_SERVER["HTTP_INCAP_CLIENT_IP"]) &&
 filter_var($_SERVER["HTTP_INCAP_CLIENT_IP"], FILTER_VALIDATE_IP) ) {
   $_SERVER["REMOTE_ADDR"] = $_SERVER["HTTP_INCAP_CLIENT_IP"];
}

Users of NinjaFirewall (Pro+ Edition) can perform the same task from the “Access Control > Source IP” menu option rather than using the .htninja file.

ALLOW / BLOCK

It is possible to use NinjaFirewall special return values ALLOW and BLOCK in order to blacklist or whitelist anything you want:

• ALLOW: the firewall will accept the request immediately and will not filter it.
• BLOCK: the firewall will block the request (403 Forbidden) and close the connection immediately.

This is the fastest way to allow or block a request because it will be processed before WordPress is loaded and even before NinjaFirewall loads its own configuration. Note that, for this reason, the firewall will not write the event to its log.
For instance, we ask the firewall to allow IP 1.2.3.4:

<?php
/*
 +============================================================================================+
 | NinjaFirewall optional configuration file                                                  |
 |                                                                                            |
 | See: https://blog.nintechnet.com/ninjafirewall-pro-edition-the-htninja-configuration-file/ |
 +============================================================================================+
*/

if ( $_SERVER["REMOTE_ADDR"] == '1.2.3.4' ) {
   return 'ALLOW'; // whitelist
}

If you whitelist your IP using the .htninja, NinjaFirewall Live Log feature will not work.

Allow IPv4 1.1.1.1, 2.2.2.2 and IPv6 2001:4998:c:a06::2:4008:

<?php
/*
 +============================================================================================+
 | NinjaFirewall optional configuration file                                                  |
 |                                                                                            |
 | See: https://blog.nintechnet.com/ninjafirewall-pro-edition-the-htninja-configuration-file/ |
 +============================================================================================+
*/

$ip_array = array( '1.1.1.1' , '2.2.2.2' , '2001:4998:c:a06::2:4008' );
if ( in_array( $_SERVER["REMOTE_ADDR"], $ip_array ) ) {
   return 'ALLOW'; // whitelist
}

Allow all IPs from 1.1.1.1 to 1.1.1.255:

<?php
/*
 +============================================================================================+
 | NinjaFirewall optional configuration file                                                  |
 |                                                                                            |
 | See: https://blog.nintechnet.com/ninjafirewall-pro-edition-the-htninja-configuration-file/ |
 +============================================================================================+
*/

if ( preg_match( '/^1\.1\.1\.\d+$/', $_SERVER["REMOTE_ADDR"] ) ) {
   return 'ALLOW'; // whitelist
}

To block or allow IPv4 CIDR (e.g., 1.1.1.1/24) or custom IP ranges, see this discussion and that one on the WordPress.org forum.

To reject, use the BLOCK return value instead:

<?php
/*
 +============================================================================================+
 | NinjaFirewall optional configuration file                                                  |
 |                                                                                            |
 | See: https://blog.nintechnet.com/ninjafirewall-pro-edition-the-htninja-configuration-file/ |
 +============================================================================================+
*/

if ( $_SERVER["REMOTE_ADDR"] == '1.2.3.4') {
   return 'BLOCK'; // reject it
}

Users of NinjaFirewall (Pro+ Edition) can whitelist or blacklist IPs from the “Access Control > IP Access Control” menu option rather than using the .htninja file.

To allow any access to a PHP script located inside the /foo/bar/ directory:

<?php
/*
 +============================================================================================+
 | NinjaFirewall optional configuration file                                                  |
 |                                                                                            |
 | See: https://blog.nintechnet.com/ninjafirewall-pro-edition-the-htninja-configuration-file/ |
 +============================================================================================+
*/

if (strpos($_SERVER['SCRIPT_FILENAME'], '/foo/bar/') !== FALSE) {
   return 'ALLOW';
}

Advanced Filtering

The .htninja.sample included in NinjaFirewall package shows some advanced filtering samples, for instance, blocking a POST request if it contains a whatever variable sent to a PHP script named script.php:

<?php
/*
 +============================================================================================+
 | NinjaFirewall optional configuration file                                                  |
 |                                                                                            |
 | See: https://blog.nintechnet.com/ninjafirewall-pro-edition-the-htninja-configuration-file/ |
 +============================================================================================+
*/

// Block immediately a POST request if it contains a 'whatever' variable
// sent to a script named 'script.php' :
if ( isset($_POST['whatever']) && strpos($_SERVER['SCRIPT_NAME'], 'script.php') !== FALSE ) {
   return 'BLOCK';
}