New APIBAN client for fail2ban

Almost four years since I learned about APIBAN from @apiban and posted how to use it with FreePBX here. Check that thread for background.

Yesterday, the project announced a new client that integrates APIBAN with fail2ban, just in time for #FridayFun.

Initially I started testing with my home system running the FreePBX 16 Distro. For reasons eplained below, this is less than ideal.

Starting with a FreePBX 17 system installed with the official Debian 12 install script, step one is to disable fail2ban email notifications if it’s enabled. Step 2 is to increase the fail2ban ban time to at least 7 days, the apiban client does a full refresh weekly, so you don’t want rules to expire before the flush happens. I’m using a value of 610,000 seconds, just over 7 days.

I found my old APIBAN key in the file /usr/local/bin/apiban/config.json but if you need to, you can recover an old key using this page.

After a quick review of the install script, I ran the one line command

curl -sSL | bash -s -- APIBANKEY

This is a low spec VM from vultr, so it took several minutes for the install to complete. While waiting, I could monitor the progress of the initial sync with the command

fail2ban-client status asterisk-iptables

where I would see the banned total steadily increment until it stopped at

Status for the jail: asterisk-iptables
|- Filter
|  |- Currently failed: 0
|  |- Total failed:     0
|  `- File list:        /var/log/asterisk/fail2ban
`- Actions
   |- Currently banned: 2096
   |- Total banned:     2096

Using this new APIBAN client works a bit more smoothly with the FreeBPX GUI, as now the banned IPs are viewable and controllable directly in the FreePBX Firewall module GUI. Browsing to Connectivity, Firewall, Intrusion Detection tab, we can see all of the current fail2ban bans

edit - If you don’t see this display, you’ll need to enable Intrusion Detection Sync Firewall under Firewall → Advanced → Advanced Settings

As before I will continue to monitor in the coming days to see how things work.

Huge thanks to Fred Posner/@apiban and the other fine folks there for providing this service!


Thanks @lgaetz ! Great to have this kind of feedback. The default on the fail2ban client uses both the SIP and HTTP dataset which should also help against some GUI bots/scanners.

1 Like

Good to know. For anyone testing this, know that all the APIBAN IPs are dumped in the asterisk-iptables fail2ban jail, so they will only appear in the GUI to have been banned by SIP.

Installed on a FPBX15 server now and can confirm installs and seems OK. layout of banned addresses is not as nice.

But definitely blank the email address in the “intrusion detection” page before running the script.

Thanks @apiban

1 Like

Sorry if I’m missing an easy, obvious button, but how are you getting the nice list of IP addresses that are banned, as well as a search box? I get this not so pretty thing.

The pretty format screen capped above is from the firewall module in 16.

Is that FPX 15 or 16 ? thats what I get on 15 on 16 I get the list

Hmm. I’m running FreePBX, it looks like:


To see the color formatting, in Firewall → Advanced → Advanced Settings you need Intrusion Detection Sync enabled.

This is the default setting going forward in 17 now. Obviously, if you need to maintain separate whitelists, then you don’t want to enable this.


Ah looks much better now. Thank you! Though all of a sudden, all those IP addresses don’t show as banned anymore:

Which I think they should? These are the settings I have:


If you did a restart you can always run a FULL command on the apiban-fail2ban client to refresh the list: “apiban-fail2ban FULL” in whatever directory you installed it. (script will install to /usr/local/bin/apiban/)

I didn’t do a restart, though I suppose I should sometime (it’s been up for a month or more). It is not a production system, still just testing around with FreePBX before we deploy it (though we need to get money from the public somehow to finally migrate to FreePBX someday).

It does look like it just banned six IP addresses, so I think it’s still working nicely now.

This is a quirk of FreePBX Distro 16 and earlier. The version of fail2ban is old, so bans are lost whenever fail2ban restarts.

I’m moving my test to FreePBX 17 now.

1 Like

As expected, things work better when using Debian 12 and fail2ban v1.0.2. I will update post 1 to reflect this.

If using with FreePBX distro 16 or earlier, then you must ensure that the apiban client runs once with the FULL argument every time fail2ban starts, including at system boot time:

/usr/local/bin/apiban/apiban-fail2ban FULL

For anyone that’s installed the script prior to this commit that happened about 2:45pm Eastern time today, then you’ll want to issue the following commands manually:

systemctl enable apiban-fail2ban.timer
systemctl enable apiban-fail2ban.service

This will ensure that services start automatically on boot. The current version of has these lines now.

1 Like

@apiban expanded the GitHub readme yesterday for apiban-fail2ban. There’s now a section for the config.json parameters which states that a new FULL sync is performed every 7 days. We can see this value hard coded in the client in seconds.

By default, the fail2ban ban time in FreePBX is set to 86400 seconds, only 24 hours. This means that the apiban fail2ban rules will expire after 1 day, and remain gone until the next flush 6 days later. For things to work properly, you’ll need to increase the fail2ban ban time to a value of at least 7 days, I’ve updated the first post with this new info.

Thanks. You could always add a cron job with the FULL to match whatever timeframe you’ve chosen for fail2ban…


# update apiban iptables
0 2 * * * /usr/local/bin/apiban/apiban-fail2ban FULL >/dev/null 2>&1
1 Like

I remember worked on this feature too, This capture comes from Intrusion detection in the menu on bottom of the page!

1 Like

Sorry if this has an obvious answer or if I’m missing a customization, but is this possible:

Customize the Fail2Ban emails in a way that sends different wording (maybe just a keyword in the subject line) to indicate a ban came via the API to APIBAN vs. an actual attempt directly against our system? I know in the end it doesn’t really matter too much, they all get banned. But that differentiation would make my supervisor less worried about the many emails that come in in chunks saying X.X.X.X was banned.

1 Like

This topic was automatically closed 31 days after the last reply. New replies are no longer allowed.