Telegram Bot

Telegram Bot — a ServerGuard module that sends you notifications about security events on your server in Telegram and lets you manage protection directly from the chat: block and unblock IPs, change settings, view statistics and server status.

The bot runs on your Linux server and accesses data from other ServerGuard modules. You do not need to open the desktop application for this.

1. What the bot can do

• notifications about IP blocking and unblocking;
• notifications about SSH logins, including logins from a new IP;
• notifications about failed login attempts (optional);
• notifications about SSH key changes (SSH Key Guard);
• notifications about system service changes;
• a daily report;
• management of blocks and the whitelist (whitelist);
• configuring the threshold and block duration;
• server status and the latest SSH log lines;
• an inline button menu and commands.

2. How it works

ServerGuard modules on the server
(brute-force protection, SSH Key Guard, service monitoring)
              |
              v
       record events
              |
              v
        Telegram Bot
              |
              v
   filters, groups, sends
              |
              v
      your Telegram chat
              |
              v
  you press a button → the bot performs an action on the server

The bot checks for new events every few seconds. Old events are not sent again when the bot starts.

3. Connecting

The bot is linked to your Telegram account using a one-time code.

1. In ServerGuard, open Telegram bot and install/configure the bot (you will need a token issued by @BotFather).
2. Select Generate verification code and copy the code.
3. Open your bot in Telegram and send:

/start CODE

4. The bot will delete the message with the code from the chat and confirm registration.

After that you will see the main menu.

Important: - the code is valid for 5 minutes; if it has expired, create a new one; - after several incorrect codes in a row, the bot temporarily stops accepting attempts; - the bot works only in a private chat.

4. Access: a single owner

The bot serves only one owner — the person who registered with the code.

• Messages and buttons from other users are ignored or rejected.
• If you generate a new code and another account activates it, access transfers to the new account. The previous owner will receive a notification about this.
• Settings and the list of known IPs are preserved when the owner changes.

Do not share the bot token or verification codes with anyone.

5. Main menu

Open the menu with the /menu command.

6. Which notifications you receive

Many notifications contain action buttons — for example, block an IP or add it to the whitelist with one tap.

7. Block notification

It shows:

• the blocked IP and its geolocation (if enabled);
• the number of failed attempts;
• the block duration and end time;
• the reason.

Buttons: 🔓 Unblock, ✅ Add to whitelist, 🔎 Info.

8. SSH login notification

It contains the user, IP, geolocation, authentication method and time.

If the login was made from an IP that has had no successful logins before, the bot marks it as 🆕 New IP. Such a notification arrives with increased priority. If it was not you, press 🚫 Block immediately.

Buttons: 🚫 Block, ✅ Add to whitelist, 🔎 Info.

9. SSH key changes

These notifications are generated by the SSH Key Guard module. The bot reports:

• what exactly happened: the key was added, removed, or changed;
• the account and the authorized_keys file;
• the key type, fingerprint and comment;
• who made the change: user, process, command (if auditd is available);
• the source IP address, if it could be determined.

Removing a key is considered a critical event. If you did not make the change, check the server immediately.

10. Service notifications

The bot reports changes to system services: start, stop, state change.

• Service and noisy processes (sessions, updates, timers, etc.) are filtered out.
• Identical events for the same service are not repeated for 10 minutes.
• Stopping important services — SSH, the firewall, fail2ban, auditd, ServerGuard — arrives as a critical notification.

11. Daily report

Once a day (by default at 9:00 server time) the bot sends a summary for the last 24 hours:

• the number of failed attempts and unique attacking IPs;
• the number of successful logins;
• SSH key changes;
• new and active blocks;
• top attackers and the list of logins.

You can choose the sending hour: 6, 9, 18 or 22. The report can be disabled.

12. Configuring notifications

Open 🔔 Notifications and tap the items — ✅ enabled, ❌ disabled.

The Important only mode is enabled by default: unblocks, failed attempts and service starts are hidden so as not to distract you. Turn it off if you want to see everything.

13. Mute and critical notifications

To temporarily disable notifications:

/mute 60      — for 60 minutes (default 60, maximum 7 days)
/unmute       — turn back on

You can also press 🔕 1h, 🔕 8h or 🔔 Unmute in the notifications menu.

Critical notifications always arrive, even in mute mode: login from a new IP, SSH key removal, stopping an important service.

14. Flood protection

If there are a lot of events (for example, a mass attack is underway), the bot does not bury you in messages: some notifications are suppressed, and then a short 🌊 Flood protection message arrives with the number of skipped ones. The full data remains in the logs and in the Events and Status sections.

15. Managing protection

The 🛡 Protection section lets you change password-guessing protection parameters directly from Telegram:

Changes take effect within about 5 seconds. The selected item is marked with ●.

Loosen protection deliberately: too high a threshold or disabled protection makes password guessing easier.

16. Blocking and unblocking IPs

IP card. Send the bot any IP address — it will show a card:

• geolocation and provider;
• status (whether it is blocked, how much time is left);
• whether it is in the whitelist;
• the number of failed attempts and logins over 7 days;
• which usernames were tried;
• the Block / Unblock and Add to / Remove from whitelist buttons.

Commands:

/ip 1.2.3.4              — IP card
/block 1.2.3.4           — block with default parameters
/block 1.2.3.4 60        — for 60 minutes
/block 1.2.3.4 perm      — forever
/unblock 1.2.3.4         — unblock

The 🚫 Blocks section shows active blocks with their duration; the Unblock all button lifts all blocks after confirmation.

You cannot block: IPs from the whitelist and the server's own IP.

17. Whitelist

Whitelist — trusted IPs that are not blocked automatically.

/whitelist                 — show the list
/whitelist add 1.2.3.4     — add
/whitelist del 1.2.3.4     — remove

You can also add and remove with buttons in the cards and notifications. If the IP was already blocked, adding it to the whitelist removes the block.

Only add addresses that you truly trust.

18. All commands

19. Geolocation and privacy

For public IPs, the bot can show the country, city and provider (as well as a “hosting / VPN / proxy” label). To do this, the IP address is sent to an external geolocation service. No request is made for local addresses.

• Geolocation is approximate and does not determine a person's real location.
• If you do not want to share IPs with third parties, turn off 🌍 IP geolocation in the notification settings.

Keep in mind that notifications pass through Telegram servers. Do not send data through the bot that should not leave the server.

20. What the bot does not do

• it does not replace server protection — it informs and executes your commands;
• it does not block IPs without the ServerGuard protection module or without your command;
• it does not see events that other modules do not record;
• it does not work in groups or channels, only in a private chat with the owner;
• it does not guarantee delivery during network or Telegram problems.

21. If something is not working

22. Recommendations

• keep login from a new IP, blocks and SSH key changes enabled;
• leave Important only on until you get used to the flow of events;
• enable the daily report at a convenient time;
• add your permanent addresses to the whitelist so you do not block yourself;
• do not publish the bot token or verification codes (including in screenshots);
• enable two-factor authentication in Telegram — access to your account gives access to block management;
• use the bot together with the other modules: Security, SSH Hardening, SSH Key Guard, FileGuard.

This documentation describes how the Telegram Bot works at the user level. Internal implementation details belong to the developers' technical documentation.