Adding ban/unban notifications from Fail2Ban to Discord!

Self-hosted Applications
, ,
1

image
image1920×1080 114 KB

Fail2Ban Discord Notifications Setup

This tutorial outlines the process of integrating Fail2Ban with Discord to receive notifications about various actions such as bans and unbans. The integration utilizes Discord webhooks to send messages to a specified channel.

Prerequisites

  • A Discord server and channel where notifications will be sent.
  • A running instance of Fail2Ban on your server.
  • Docker users should refer to the section on Docker modifications for additional configurations.

Creating the Discord Webhook

  1. Access Server Settings: Navigate to your Discord server and open the Server Settings.

  2. Create Webhook: Select Webhooks from the menu, then click on Create Webhook.

  3. Configure Webhook:

  4. Save Webhook URL: At the bottom of the page, copy the generated webhook URL for later use.

Configuring Fail2Ban Actions

  1. Create Configuration File:

    • Navigate to your Fail2Ban action.d directory (typically found at /etc/fail2ban/action.d/).
    • Create a new file named discord_notifications.conf.

  2. Add Configuration:
    Insert the following content into discord_notifications.conf, replacing <webhook> with your actual webhook URL:

    # Author: Adapted from Gilbn's tutorial
# Create the Discord Webhook in: Server settings -> Webhooks -> Create Webhooks

[Definition]

# Notify on Jail Startup
actionstart = curl -X POST "<webhook>" \
            -H "Content-Type: application/json" \
            -d '{"username": "Fail2Ban", "content":":white_check_mark: The **[<name>]** jail has started"}'

# Notify on Jail Shutdown
actionstop = curl -X POST "<webhook>" \
            -H "Content-Type: application/json" \
            -d '{"username": "Fail2Ban", "content":":no_entry: The **[<name>]** jail has been stopped"}'

# Notify on Ban
actionban = curl -X POST "<webhook>" \
            -H "Content-Type: application/json" \
            -d '{"username":"Fail2Ban", "content":":bell: Hey <discord_userid>! **[<name>]** :hammer:**BANNED**:hammer: IP: `<ip>` for <bantime> hours after **<failures>** failure(s). Here is some info about the IP: https://db-ip.com/<ip>"}' 
            curl -X POST "<webhook>" \
            -H "Content-Type: application/json" \
            -d '{"username":"Fail2Ban", "content":"If you want to unban the IP run: `fail2ban-client unban <ip>`"}'

# Notify on Unban
actionunban = curl -X POST "<webhook>" \
            -H "Content-Type: application/json" \
            -d '{"username":"Fail2Ban", "content":":bell: **[<name>]** **UNBANNED** IP: [<ip>](https://db-ip.com/<ip>)"}'

[Init]

# Name of the jail in your jail.local file. Default = [your-jail-name]
name = default

# Discord Webhook URL
webhook = https://discordapp.com/api/webhooks/XXXXXXXXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  3. Commenting Actions (Optional):
    If you wish to disable notifications for specific actions (e.g., startup, shutdown, or unban), comment out those lines by prefixing them with #.

Updating jail.local

  1. Open your jail.local file located in /etc/fail2ban/.
  2. Add the Discord action to each jail configuration where you want notifications. This can also be added under the [DEFAULT] section for global application.

Example configuration:

[nginx-http-auth]
enabled  = true
filter   = nginx-http-auth
action   = cloudflare-apiv4
           discord_notifications[bantime=24, discord_userid=<@!xxxxxxxxxxxxxxxxxxxx>]
           iptables-allports
port     = http,https
logpath  = /config/log/nginx/error.log
ignoreip = 192.168.1.0/24

Important Notes

  • The [bantime=24] tag is used for display purposes and does not affect actual ban duration.
  • To mention yourself in Discord, use your user ID formatted as <@!USER-ID-NUMBER>.
  • To exclude local IPs from being banned, adjust the ignoreip setting accordingly.

Restarting Fail2Ban

After completing these configurations, restart Fail2Ban to apply changes:

sudo systemctl restart fail2ban

Docker Modifications (if applicable)

If you are using the linuxserver/letsencrypt Docker container, consider using a Docker mod that enhances notification formatting:

linuxserver/docker-mods at swag-f2bdiscord (github.com)

  1. Add environment variables to your Docker container:
-e DOCKER_MODS=linuxserver/mods:swag-f2bdiscord
-e DISC_HOOK=40832456738934/7DcEpWr5V24OIEIELjg-KkHky86SrOgTqA  # Last two parts of the webhook URL
-e DISC_ME=120970603556503552  # Your user ID for mentions
  1. Update your action in jail.local:
action = cloudflare-apiv4 discordEmbed[bantime=24] iptables-allports

Conclusion

By following these steps, you will successfully configure Fail2Ban to send notifications to your Discord server, enhancing your server’s security monitoring capabilities through real-time alerts. Adjust notification messages as needed by modifying the discord_notifications.conf file directly.