Skip to main content

General

This section contains general purpose modules and modules written for providing base services for BitNinja.

CLI​

This module is not an active module. It contains source code for bitninjacli. You can read more about it in the BitNinjaCLI chapter.

DataProvider​

This module is responsible for sending out regular updates about the server to the BitNinja analysis central. Data like system resource usage, system load, memory Usage, and BitNinja protection efficiency is sent for statistical purposes.

This module is also responsible for sending the server's IPs to our cloud, where we automatically add them to your whitelist so all your BitNinja servers can communicate with each other without restrictions.

IpFilter​

This module is responsible for the IP filtering functionality. BitNinja uses the ipset Linux kernel module to filter IP lists effectively, using minimal system resources at a stunning speed. You can find more details about this Linux module here: http://ipset.netfilter.org/

BitNinja manages many different ipsets for you automatically. Here are the different ipsets:

  • heimdall-greylist
  • heimdall-blacklist
  • heimdall-esentiallist
  • heimdall-user-blacklist
  • heimdall-user-whitelist

When the IpFilter module boots up on your server, it will try to detect the available ipset version. There are 3 options:

  • ipset 6.x
  • ipset 4.x
  • no ipset support, simulating the functionality with iptables

ipset 6.x​

In recent Linux distributions, you can enjoy the efficiency and speed of ipset v 6.x. Ipset 6.x is a complete rewrite of the previous major version, 4.x. Ipset 6.x. is the best option you can have for BitNinja.

ipset 4.x​

The older 4.x version has some limitations like having a maximum size of 65500 IP/ipsets, having a different set of cli options from the new version, and having a maximum of 255 ipsets. The BitNinja greylist has a size of millions of IPs. We have to split the greylist into smaller lists to use it with ipset 4.x. BitNinja splits the greylist into 100 smaller lists.

SimulatedIpset​

If there is no ipset available, BitNinja will simulate this functionality with iptables rules. This is much less efficient than using ipset so you should avoid it whenever possible. In case of container based virtualization, when ipset is not available, we fall back to simulated ipset functionality.

In case of simulated ipsets, the efficiency is so poor that we cannot use the whole greylist with millions of IPs so your server will start with an empty greylist and only use IP information gathered since the last restart.

You should try to get your server to use ipset v 6.x to enjoy the best performance. You can find more info about how to install ipset in the Installation section.

tip

If you'd like to use the country blocking feature with simulated ipset, please be aware that this function will be limited. This is because of the limitations of simulated ipset. For example, if you want to add a country having lot of IP ranges to the blacklist or whitelist, it is possible that not all of the ranges will be put on the list. At the moment, we're limiting the number of country IP ranges on user blacklist and user whitelist for simulated ipset to 8000.

Extending IpFilter​

You can define custom scripts to run whenever BitNinja finishes initializing its sets and iptables rules. This makes it possible to add your own IPs and rules to BitNinja's ruleset or run other programs when the IpFilter module finishes its startup process.

The following steps should be made in order to set up a post-up script

  • You should place a file into the /etc/bitninja/IpFilter/postup-scripts.d/ directory.
  • The name of the file should begin with al\_. For example, the file /etc/bitninja/IpFilter/postup-scripts.d/al_myscript.sh is a valid path for a post-up script.
  • Make sure that the script is owned by the root user and is runnable by the owner.
  • The post-up script should have the same syntax as the scripts you normally invoke from the shell. For example, its first line should be #! <the path of the interpreter>, as usual.
  • After you've created your script, you should restart BitNinja. You can check if there were any errors in the /var/log/bitninja/mod.ipfilter.log file.

Useful post-up extension scripts​

BitNinja normally block both inbound and outbound connections from and towards greylisted or blacklisted IPs. However, you may need to allow outbound traffic towards every IP, even the blocked ones. This script should help you.

#! /bin/bash

echo "Enabling outbound traffic..."
iptables -t nat -I HEIMDALL-GREY -m state --state ESTABLISHED,RELATED -j RETURN &&
iptables -t mangle -I HEIMDALL-IN -m state --state ESTABLISHED,RELATED -j RETURN &&
echo "Done."

Sometimes, you may need to exculde specific ports from being filtered. The following script can be used in such cases. You should replace the ports defined in the PORTS variable with the ports you need to enable.

#! /bin/bash

PORTS="25,110,143" # A list of TCP ports to be allowed, separated by comma

echo "Enabling all traffic on ports [$PORTS]..."
iptables -t mangle -I HEIMDALL-IN -p tcp -m multiport --dports "$PORTS" -j RETURN &&
iptables -t nat -I HEIMDALL-GREY -p tcp -m multiport --dports "$PORTS" -j RETURN &&
echo "Done."

You can enable the WAF module to work with private IP addresses too, using the following post-up script:

#!/bin/bash

echo "Enabling WAF manually..."
IPS="127.0.0.1 1.2.3.3 1.2.3.4" # A list of IP addresses to use with WAF, change it to your preference!
iptables -t nat -N BN_WAF_REDIR
iptables -t nat -A HEIMDALL-GREY -p tcp -m tcp -j BN_WAF_REDIR

for IP in $IPS; do
    echo "Creating DNAT HTTP and HTTPS redirection for ip [$IP]..."
    iptables -t nat -A BN_WAF_REDIR -d $IP/32 -p tcp -m tcp --dport 80 -j DNAT --to-destination $IP:60300
    iptables -t nat -A BN_WAF_REDIR -d $IP/32 -p tcp -m tcp --dport 443 -j DNAT --to-destination $IP:60414
done

This script won't enable the WAF module - you should do that manually on the Dashboard or using bitninjacli -, but it will create the necessary redirections.

Shogun​

The Shogun is the local governor of security on a BitNinja enabled system. The duty of this module is to accept and forward security incidents accordingly. For example, when there is an incident raised by the Captcha HTTP, it will be sent directly to the Shogun module and it will route it (after proper filtering) to other modules like AntiFlood, ipfilter as well as BitNinja Central.

Filters

  • flood if the IP is already blacklisted but for some reason (deleted iptables rules for example) incidents are still coming, this filter will protect against flooding central with bogus incidents

  • private network BitNinja does nothing with sources from private IP ranges.

  • user whitelist we do nothing with incidents generated by user whitelisted IPs

  • whitelist there are some built in whitelisted IPs and reverse DNS endings the client auto whitelist. (like Google bots, CloudFlare, w3c.org, Facebook bot, etc.)

System​

The duty of this module is to manage licensing, restart and update the BitNinja client, and accept commands to enable or disable the WAF module. In the future this module will manage remote configuration as well.