Integrating Fail2Ban with Listed.Black

This guide will help you integrate Fail2Ban with your Listed.Black account so that any malicious activity detected by Fail2Ban on your system is automatically reported to the Listed.Black database. This contributes to a distributed database of known abusive IPs, helping to protect not just your system but others as well.

Step 1: Obtain Your API Key

First, you need to sign up for a Listed.Black account and obtain your API key. This key is used to authenticate your reports to the Listed.Black API.

1. Sign up or log in to your account on Listed.Black.
2. Navigate to the API section in your account dashboard.
3. Copy your unique API key; you will need it for configuring Fail2Ban.

Step 2: Install Fail2Ban

If you haven’t already installed Fail2Ban, you can do so using your package manager. On a Debian-based system, you would use:

sudo apt-get update
sudo apt-get install fail2ban

On CentOS or RHEL:

sudo yum install epel-release
sudo yum install fail2ban

Step 3: Configure Fail2Ban to Report to Listed.Black

Now, you need to modify your Fail2Ban configuration to report to Listed.Black.

Edit the Action File: Open or create a custom action file in the Fail2Ban action.d directory. For example:

sudo nano /etc/fail2ban/action.d/listedblack.conf

Add the following content to this file:

[Definition]
norestored = 1
actionstart =
actionstop =
actioncheck =

actionban = curl --fail 'https://api.listed.black/api/v2/report/' -H 'accept: */*' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'Key=<listedblack_apikey>' --data-urlencode 'ip=<ip>' --data-urlencode 'categories=<listedblack_category>' --data-urlencode "comment=<matches>" --data-urlencode 'jail=<name>' --data-urlencode 'port=null'

actionunban =

[Init]

listedblack_apikey = <YOUR_API_KEY>

Replace <YOUR_API_KEY> with the API key you obtained earlier.

Edit the Jail Configuration: Next, you need to tell Fail2Ban to use this new action. Open the jail.local file:

sudo nano /etc/fail2ban/jail.local

[sshd]
enabled = true
action = %(known/action)s
listedblack[listedblack_category="18,22"]

Step 4: Restart Fail2Ban

After you’ve made these changes, restart Fail2Ban to apply the new configuration:

You can use either:

sudo systemctl restart fail2ban
or 

sudo fail2ban-client restart

Step 5: Verify the Integration

You can verify that the integration is working by intentionally triggering a ban (e.g., by attempting multiple failed SSH logins) and checking if the IP is reported to Listed.Black.

You can also check your Listed.Black account dashboard to see if the IP reports are being logged.