SecureBot - Telegram Security Bot

A Telegram bot for monitoring SSH logins and managing fail2ban across multiple systems.

Features

• Monitor SSH logins locally and on remote servers
• Track fail2ban events (bans/unbans)
• Manage fail2ban (list jails, ban/unban IPs)
• Remote server monitoring via SSH
• Real-time notifications
• Configurable notification settings
• Access control (admin/viewer roles)
• Easy Ansible Deployment for managing multiple servers

Requirements

• Python 3.8+
• Fail2ban
• Telegram Bot Token

Preconditions Setup Telegram Bot

Before we start installing the bot, you need a API Token within Telegram which we will use later for the configuration.

Read the following instructions if you don't know what to do ;-).

• Telegram Bot Setup

Read also the documentation about Telegram.

• Telegram
• Download App
• Telegram API

Installation

Using the Ansible Playbook (Recommended)

Install Ansible & Git on your device if you want to deploy from your local system to your local system or other systems.

With the Ansible role, you have 2 options for installing the SecureBot. You can roll it out locally on the same system where you start the playbook or you can configure it so that it is immediately configured on other servers. The SecureBot is able to read the logs from other servers.

However, it is also possible to install the SecureBot “locally” on each system by not specifying the other servers in the inventory.yml file, but then reinstalling the Ansible role locally on each system and thus also the SecureBot again and again.

So that the SecureBot can collect data from other servers via SSH-Key, the role is equipped with appropriate rights and a dedicated SSH key is created for each system. Both are possible and you have better control over the security of your systems.

Preconditions for debian based OS

So that you can automatically install the securebot on your local or other Linux servers with the Ansible role, you first need the packages ansible and git on your workstation. You also have the option of installing SecureBot on the same workstation.

1. Install packages on you workstation or server:

   sudo apt update && apt upgrade
   sudo apt install ansible git -y

2. Clone this repository:

   git clone https://github.com/rtulke/securebot.git
   cd securebot

3. Edit the inventory.yml file to specify your servers:

   all:
     hosts:
       localhost:
         ansible_connection: local             # For local installation on the same host
     ## Activate this part if you want to install on other computers:
     # web_server:
     #   ansible_host: webserver.example.com
     #   ansible_user: admin                   # The user requires extended authorizations p.e. /etc/sudoers so that he can carry out the automatic configuration.
     # db_server:
     #   ansible_host: db.example.com
     #   ansible_user: admin                   # The user requires extended authorizations p.e. /etc/sudoers so that he can carry out the automatic configuration.

4. Edit the group_vars/all.yml file to customize your deployment:

   As described above, you will need the API token from your bot created via BotFather as well as the channel ID and your own Telegram ID. Otherwise see above in the section Preconditions Setup Telegram Bot if you do not know how to get this ID. I have explained it in more detail there.

   telegram_bot_token: "YOUR_BOT_TOKEN"
   telegram_chat_id: "YOUR_CHAT_ID"
   admin_users:
     - 123456789 # Your Telegram User ID

5. Run the Ansible playbook:

   ansible-playbook -i inventory.yml deploy.yml

Manual Installation (on one single system or for multiple systems)

1. Install required packages:

   sudo apt update
   sudo apt install -y python3-pip python3-venv fail2ban

2. Create a dedicated user for securebot:

   sudo useradd -r -s /bin/false securebot
   sudo mkdir -p /etc/securebot/keys
   sudo mkdir -p /var/lib/securebot

3. Set up a Python virtual environment:

   sudo python3 -m venv /var/lib/securebot/venv
   sudo /var/lib/securebot/venv/bin/pip install --upgrade pip
   sudo /var/lib/securebot/venv/bin/pip install -r requirements.txt

4. Generate a configuration file:

   sudo /var/lib/securebot/venv/bin/python securebot.py -g -c /etc/securebot.conf

5. Edit the configuration file:

   sudo nano /etc/securebot.conf

6. Create SSH keys for remote access:

   sudo -u securebot ssh-keygen -t ed25519 -f /etc/securebot/keys/securebot_key -N ""

7. Create a systemd service file:

   sudo nano /etc/systemd/system/securebot.service

   Add the following content:

   [Unit]
   Description=SecureBot a Telegram Security Bot
   After=network.target
   
   [Service]
   Type=simple
   User=securebot
   Group=securebot
   ExecStart=/var/lib/securebot/venv/bin/python /usr/local/sbin/securebot -d -c /etc/securebot.conf
   Restart=on-failure
   RestartSec=5s
   
   [Install]
   WantedBy=multi-user.target
   

8. Install the SecureBot script:

   sudo cp securebot.py /usr/local/sbin/securebot
   sudo chmod +x /usr/local/sbin/securebot
   sudo chown securebot:securebot /usr/local/sbin/securebot

9. Enable and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable securebot
   sudo systemctl start securebot
   sudo systemctl status securebot

Configuration

SecureBot uses a TOML configuration file. A default configuration can be generated with:

securebot.py -g

Configuration File Structure

[general]
local_only = false
log_level = "INFO"  # DEBUG, INFO, WARNING, ERROR
notification_delay = 10  # Seconds between notifications

[telegram]
bot_token = "YOUR_BOT_TOKEN"
chat_id = "YOUR_CHAT_ID"
admin_users = [123456789, 987654321]  # Telegram User IDs
viewer_users = []  # View-only access

[local]
ssh_log = "/var/log/auth.log"
fail2ban_log = "/var/log/fail2ban.log"
audit_log = "/var/log/audit/audit.log"

[servers]
  [servers.webserver]
  hostname = "webserver.example.com"
  ip = "192.168.1.10"
  ssh_user = "monitor"
  ssh_key_path = "/etc/securebot/keys/webserver_key"
  ssh_port = 22
  host_key_path = "/etc/securebot/known_hosts/webserver"
  logs = { ssh = "/var/log/auth.log", fail2ban = "/var/log/fail2ban.log" }

[notifications]
ssh_login = true
fail2ban_block = true
server_unreachable = true

[customization]
date_format = "%Y-%m-%d %H:%M:%S"
resolve_hostnames = true
show_ipinfo_link = true

Command Line Options

-d, --daemon          Run as a daemon
-c, --config FILE     Specify the configuration file
-g, --generate-config Generate a default configuration file
-v, --verbose         Increase verbosity
-t, --test            Run in test mode (no actual actions)
--version             Show version information
-l, --log FILE        Specify a log file
--setup               Run interactive setup

Telegram Commands

• /help - Show help information
• /status - Show status of all monitored servers
• /login_history [n] - Show the last n login events
• /server list - List all configured servers
• /server status NAME - Show status of a specific server
• /mute [minutes] - Mute notifications temporarily
• /unmute - Unmute notifications

Admin commands:

• /fail2ban list [server] - List fail2ban jails
• /fail2ban status JAIL [server] - Show banned IPs in a jail
• /fail2ban ban IP JAIL [server] - Ban an IP in a jail
• /fail2ban unban IP JAIL [server] - Unban an IP from a jail

Remote Server Setup

To monitor remote servers:

1. Create a monitor user on the remote server:

   sudo useradd -r -m -s /bin/bash monitor

2. Set up sudo permissions for fail2ban commands:

   echo "monitor ALL=NOPASSWD: /usr/bin/fail2ban-client status, /usr/bin/fail2ban-client status *" | sudo tee /etc/sudoers.d/monitor-fail2ban

3. Add SecureBot's SSH key to the remote server:

   sudo mkdir -p /home/monitor/.ssh
   sudo cat /path/to/securebot_key.pub >> /home/monitor/.ssh/authorized_keys
   sudo chown -R monitor:monitor /home/monitor/.ssh
   sudo chmod 700 /home/monitor/.ssh
   sudo chmod 600 /home/monitor/.ssh/authorized_keys

Security Considerations

• The monitor user on remote servers should have minimal permissions
• Restrict the bot to only authorized Telegram users
• Regularly update SSH keys
• Consider using IP restrictions for SSH access
• Review fail2ban logs periodically

Troubleshooting

• Check the logs: journalctl -u securebot
• Check the Python Script: sudo -u securebot /var/lib/securebot/venv/bin/python /usr/local/sbin/securebot -c /etc/securebot.conf
• Verify the bot can connect to Telegram API
• Ensure proper permissions for log files
• Test SSH connections manually
• Validate the configuration file