Firewall Synchronization Tool (FST) is a cross-platform utility, built on top of already existing tools such as fail2ban, sshguard, ModSec and is meant to synchronize banning and unbanning IP addresses over a wide area network. FST fills a gap that has been observed on public forums where administrators have been attempting to create a synchronization tool similar to FST. FST extends on the syncrhonization principle and abstracts away enough such that the synchronized messages amongst a pool of servers do not carry information specific to any server.

The tool is written using Node.JS, contains pre-written rules for fail2ban and additionally can display various metrics on the IP addresses that have been banned or unbanned that updates in real-time.

The source code can be retrieved via Subversion:

• http://svn.grimore.org/fst

FST is currently licensed under the MIT license.

To checkout the code using Subversion, issue:

svn co http://svn.grimore.org/fst/trunk

in any directory, provided that Subversion is installed.

• Any server with the capability to execute Node.JS scripts,
• A fairly modern browser to view metrics and,
• [Optional] fail2ban - scripts can be written for any other software package.

FST is meant to be ran on servers that offer public services such as SSH, http, etc. Once a server is under attack, FST notifies other servers (either on the local network or on a wide area network) that an attack is taking place. Upon receiving the attack notification, the other servers can decide whether to ban the attacker's IP address. Since fail2ban can also expire IP addresses periodically, FST can also broadcast a notification when the ban has expired.

The graph above depicts a server named Server B that is currently under attack. Server B sends a message to FST and FST distributes that message to Server A and Server B such that both server A and B can take preventive measures to ensure that an attacker cannot proceed to compromise other servers on the network.

FST builds further on the notification message being broadcast such that FST is not strictly limited to actions such as "ban" or "unban" but allows administrators to create custom actions and name them as they see fit. Upon receiving a notification message, FST checks the local server to see whether the action is defined - if the received action is defined, then FST executes user-defined scripts for that action, conversely, if the action is not defined, then FST will ignore the message.

Upon downloading the code, two directories are created:

• fst,
• fst-wwwroot

the two directories can be placed independently of each other on the filesystem.

The fst folder contains the backend responsible for host discovery and broadcast of notifications whilst the fst-wwwroot folder contains the frontend capable of displaying metrics.

The user must change directory to both fst and fst-wwwroot and execute, in turn, the command:

npm install

to install any software dependencies.

The next step is to edit the file fst/sync-peers.txt and enter the hostname or IP address of the machines that FST will be running on, including the local machine. For three servers named serverA.lan, serverB.lan and serverC.lan that are meant to synchronize, the fst/sync-peers.txt on all three servers shall be identical and read:

serverA.lan
serverB.lan
serverC.lan

Finally, the configuration file at fst/config.yml.dist should be copied over to fst/config.yml and edited to adjust the configuration - this step has to be performed for each server. The configuration config.yml should be rather straightforward to read and contains comments for most configuration settings.

The folder fst/contrib/systemd contains two systemd scripts:

• fst-metrics.service,
• fst-server.service

that are meant to be copied into /etc/systemd/system and edited to change the paths according to the placement of the folders fst and fst-wwwroot from the FST distribution. After copying the files, the following commands must be run:

systemctl enable fst-metrics.service
systemctl enable fst-server.service

followed by:

systemctl start fst-metrics.service
systemctl start fst-server.service

to start both the metrics and the FST server.

Optionally, the file contrib/logrotate.d/fst must be copied into /etc/logrotate.d in order to rotate the FST log files when they get too large.

The FST distribution contains configuration files for fail2ban; these are to be found under the folder contrib/fail2ban. They have to be copied into the fail2ban configuration directory appropriately. For instance, the folder contrib/fail2ban/action.d/fst.conf should be copied into the fail2ban action folder, commonly placed at /etc/fail2ban/action.d.

The fail2ban configuration must then be adjusted to use the FST action. For example, the fail2ban jails have to be adjusted under /etc/fail2ban/jail.d to include fst on the banaction configuration parameter:

banaction = iptables-multiport,
            fst

which will take care to call the script fst/sync-action.js every time a host is banned or unbanned.

With all configuration files in place, fail2ban will emit a notification to FST whenever a host is attacked at which point, FST will connect to all peers defined in the sync-peers.txt file and notify them of a ban action. Every server in sync-peers.txt will then execute all the script files in fst/action/ban or fst/action/unban sequentially depending on whether the fail2ban action has been ban or unban. FST already contains pre-written scripts for fail2ban under fst/action/ban.d, respectively fst/action/unban.d that call fail2ban-client in order to add a ban (or remove a ban) through fail2ban.

The message that is synchronized across FST peers contains the following information:

• the peer that has been attacked,
• the action that was performed by the peer (ie: ban or unban),
• a descriptive name for the action (using fail2ban, this would be the jail name, ie: ssh, etc.),
• the port on which the attack was carried out (ie: 22 or ssh),
• the IP address from where the attack originates.

Based on the action contained in the message, FST will execute all user-defined scripts under fst/action/. For example, an message that has action set to ban, will make FST attempt to execute the scripts placed under fst/action/ban.d.

However, it is entirely possible to broadcast a message with the action parameter set to any action. Looking at the fail2ban configuration provided with FST contrib/fail2ban/action.d/fst.conf, a "banning" action is sent to FST via the command fst-action:

actionban = /opt/fst/fst/fst-action.js ban '<name>' '<protocol>' '<port>' '<ip>'

where ban is the action to perform and the other variables such as name, protocol, etc. are expanded by fail2ban itself.

It is entirely possible to call the fst-action.js script from any software other than fail2ban with matching parameters, ie:

./fst-action.js nullroute route IP null XXX.XXX.XXX.XXX 

where:

• nullroute is the action to perform,
• the name of the action will be defined as route,
• the protocol will be set to IP,
• the port will be set to null and,
• the IP address will be XXX.XXX.XXX.XXX

When other machines receive the notification described previously, FST will attempt to execute all scripts under fst/action/nullroute.d. In case the folder fst/action/nullroute.d does not exist remotely, then FST will ignore the message, otherwise any script created in fst/action/nullroute.d/ will be executed sequentially.

FST is designed to be able to run on any operating system, provided that the node interpreter can run. Mainly, FST does not care what scripts are placed under fst/action/ for various action.

On Windows machines, FST will execute batch files under fst/action/ and on Linux, FST will execute any executable scripts under fst/action/.

All that FST cares about is a notification message to be delivered locally with fst-action and then that message will be broadcast to any peer defined in sync-peers.txt.