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 allow list 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 challenge list has a size of millions of IPs. We have to split the challenge list into smaller lists to use it with ipset 4.x. BitNinja splits the challenge list 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 challenge list with millions of IPs so your server will start with an empty challenge list 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 block list or allow list, 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 block list and user allow list 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 challenge list or block listed 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 block listed 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 allow list we do nothing with incidents generated by user allow listed IPs

  • allow list there are some built in allow listed IPs and reverse DNS endings the client auto allow list. (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.

Disabling Modules via Servers Page​

On the Servers page, click on the gear icon next to the server card and toggle off the module you wish to disable.

Disabling Modules via Configuration Page​

You may also disable the modules from the Dashboard's Configuration page along with a few other settings

Disabling Modules via Configuration File​

You can disable any BitNinja module by editing the config file /etc/bitninja/config.php. Here you can search for the section disabledModules and add the module you want to disable to the list.

tip

Certain core modules can be ONLY disabled or re-enabled within the /etc/bitninja/config.php file config file.

            'disabledModules'=>array(
    //            'System',
    //            'DataProvider',
    //            'IpFilter',
    //            'CaptchaHttp',
    //            'CaptchaSmtp',
    //            'PortHoneypot',
    //            'AntiFlood',
    //            'Shogun',
    //            'DosDetection',
    //            'SenseLog',
    //            'SenseWebHoneypot',
    //            'WAF'
warning

Don't forget to sync your local configuration to the cloud with bitninjacli --syncconfigs after you have changed any settings in the configuration file.

You must restart BitNinja with service bitninja restart in order for the changes to take effect.