jailbird

Jailbird is a fail2ban add on, adding to the standard fail2ban action of dynamically blocking an ip address by creating temporary firewall rules. The main additional action is to further block entire ip ranges for a short period, the default being for 10 minutes. The rational for this is to prevent a continuous attack from a host with a range of addresses. This is likely to be particularly helpful where incoming traffic is ipv6 based.

Its other benefit is the logs it creates, which list every ip address that fail2ban blocks along with the range/s to which they belong and which jailbird itself has blocked. It also includes the NetName or Organization Name, which will naturally be more memorable than addresses and ranges and will help you spot persistent infringers.

11/03/2025 02:29 exim 123.164.0.0/14 chinanet-hl 123.164.193.186
11/03/2025 02:30 apache-modsecurity 39.108.0.0/16 39.104.0.0/14 39.96.0.0/13 alisoft 39.105.169.60
11/03/2025 02:46 exim 167.250.0.0/16 lacnic-erx-167-250-0-0 167.250.119.253
11/03/2025 04:04 exim 87.120.67.0/24 neterra-skatomurtag-net 87.120.67.149
11/03/2025 04:14 apache-modsecurity 117.72.0.0/16 jdcom 117.72.42.191
11/03/2025 04:22 exim 106.240.0.0/12 boranet 106.249.158.71
11/03/2025 05:39 exim 116.72.0.0/14 hathway-net 116.72.181.164
11/03/2025 06:11 apache-modsecurity 188.166.0.0/17 eu-digitalocean-nl1 188.166.63.185

In the example log snippet above you see date and time fields followed by the fail2ban jail name. The offending ip address is at the end of each line and is preceded by the net or organization name as recorded by the RIPE database and the range or ranges that were briefly blocked by jailbird.

Installation

Jailbird is written in a combination of lua and bash. So in addition to a running fail2ban instance you need a lua install and the command line programs whois and at.

Download the archive and move it to the base (ie /) of your filesystem and run the following command as root:

root@bulawayo:/# tar --no-same-owner -zxvf jailbird.tar.gz 
usr/local/sbin/iptables.sh
usr/local/sbin/whois.lua
usr/local/bin/cidr.lua
etc/fail2ban/action.d/jailbird.local
etc/fail2ban/jail.local.example
etc/logrotate.d/jailbird
usr/share/man/man1/jailbird.1.gz

You may need to edit the path to the lua executable in the two lua files. You may if you wish edit the DELAY variable in iptables.sh. You must create the iptables chains to which jailbird will append temporary rules and you will probably want to implement some scheme to save and restore or recreate them after a reboot. It's not really necessary to save any DROP rules in the chains at the time of a reboot as they were never going to persist for very long.

root@bulawayo:/ # /usr/sbin/iptables -N jbird
root@bulawayo:/ # /usr/sbin/iptables -I INPUT -j jbird
root@bulawayo:/ # /usr/sbin/iptables -A jbird  -j RETURN
root@bulawayo:/ # /usr/sbin/ip6tables -N jbird
root@bulawayo:/ # /usr/sbin/ip6tables -I INPUT -j jbird
root@bulawayo:/ # /usr/sbin/ip6tables -A jbird  -j RETURN

You must either rename /etc/fail2ban/jail.local.example to /etc/fail2ban/jail.local and edit it to suit your setup or else copy the action lines to your own existing jail.local. Now fail2ban can be restarted to allow jailbird to hook into to its ban action as defined in /etc/fail2ban/action.d/jailbird.local. You should also check that the at daemon is running.

Further Explanation

The whois cli program is called by jailbird.local to fetch information about the offending ip address. If it is an ipv6 address the cidr notation for the parent range is extracted as is. Such information for ipv4 addresses seems to often be inaccurate, so instead the network start and end addresses are grabbed and the network's cidr notation is calculated.

A DROP rule is added to the iptables firewall and an at job is created to remove the rule in 10 minutes, or in whatever time the DELAY variable holds. The log line is written as the DROP rule is created and network name information from the whois lookup is added.

The ipv4 calculations are performed by the cidr.lua program, which can also be used as a standalone network information and calculation tool. Simple run cidr.lua to see help with this.

Links

Here's some useful information on running fail2ban on a Debian web and email server and nameserver.