enesilhaydin/mt-telegram-bot repository overview

⁠✨ Highlights

• 🛡️ WireGuard — spin up peers with auto-generated keys; get the .conf and a scannable QR right in chat
• ⚡ Wake-on-LAN — wake any device; pings first so it never WoLs an already-on machine
• 📲 Device radar — new-device alerts with one-tap Trust · Blacklist · Name buttons (zero spam)
• 🔬 Diagnostics — /diag, /find, /active, per-interface traffic, one-shot device health
• 🚨 Resource alerts — CPU/RAM/disk thresholds with cause attribution (which subsystem is hogging it)
• ⛔ Blacklist — block a MAC via bridge filter + DHCP block in a single command
• 🏷️ Notes — label devices; stored in the bot and the router's DHCP lease comment (WinBox-visible)
• 🌐 Bilingual — Turkish & English, hot-switch with /lang
• 🔑 Single-admin — locked to one Telegram user ID

⁠🚀 Quick Start

⁠1. Get your credentials

⁠2a. Run with Docker (any host that can reach the router API)

docker run -d --name mt-bot --restart unless-stopped \
  -e BOT_TOKEN="123456:AA..." \
  -e ADMIN_ID="123456789" \
  -e ROUTER_IP="192.168.88.1" \
  -e ROUTER_USER="api-user" \
  -e ROUTER_PASS="api-password" \
  -e ROUTER_PORT="8728" \
  -e TZ="Europe/Istanbul" \
  -v mt-bot-data:/app/data \
  enesilhaydin/mt-telegram-bot:latest

⁠2b. Docker Compose

services:
  mt-bot:
    image: enesilhaydin/mt-telegram-bot:latest
    restart: unless-stopped
    environment:
      BOT_TOKEN: "123456:AA..."
      ADMIN_ID: "123456789"
      ROUTER_IP: "192.168.88.1"
      ROUTER_USER: "api-user"
      ROUTER_PASS: "api-password"
      ROUTER_PORT: "8728"
      TZ: "Europe/Istanbul"
    volumes:
      - bot-data:/app/data
volumes:
  bot-data:

⁠2c. Run on the MikroTik itself (RouterOS container)

See MikroTik Container Deployment⁠ below — the bot runs as a container on the router, reaching the API over the internal container network.

Then open Telegram and send /start.

⁠🎮 Commands

⁠🖥️ System

⁠🔐 WireGuard

⁠📡 Devices

⁠🛡️ Trust / Blacklist

⁠⚡ Wake on LAN

⁠🎛️ Settings

⁠🔔 Background monitoring

• New device detection — scans ARP every 60s; first sighting of a MAC triggers an alert with ✅ Trust · 🚫 Blacklist · ✏️ Name/Note buttons. The Name/Note button starts a reply flow and saves to the bot DB and the router's DHCP lease comment. Reported only once per MAC. Toggle with /notify off.
• Resource alerts — samples CPU/RAM/HDD; on threshold breach (2 consecutive samples) sends an alert with cause attribution (one-shot /tool profile) + running jobs, 10-minute cooldown, plus a recovery notice.

⁠⚙️ Environment Variables

A RouterOS API user with only read,write,api (no shell/ssh) is recommended:

/user group add name=botapi policy=read,write,api,test
/user add name=api-user group=botapi password=strong-password

⁠🐳 MikroTik Container Deployment

⁠Prerequisites

• RouterOS 7.6+ with container support enabled
• USB/onboard storage for the container
• API user with read,write,api
• WireGuard interface configured (for WG features)

⁠Setup

# 1. Environment
/container envs add list=mt-bot key=BOT_TOKEN  value="123456:AA..."
/container envs add list=mt-bot key=ADMIN_ID   value="123456789"
/container envs add list=mt-bot key=ROUTER_IP  value="172.17.0.1"
/container envs add list=mt-bot key=ROUTER_USER value="api-user"
/container envs add list=mt-bot key=ROUTER_PASS value="api-password"
/container envs add list=mt-bot key=ROUTER_PORT value="8728"
/container envs add list=mt-bot key=TZ value="Europe/Istanbul"
/container envs add list=mt-bot key=WG_DNS value="192.168.88.1"   # your LAN gateway

# 2. Mounts: persistent DB + (optional) live-code mount — see "Updating code"
/container mounts add name=mt-bot-data src=usb1/container/data/mt-bot dst=/app/data
/container mounts add name=mt-bot-code src=usb1/container/data/mt-bot-code dst=/app/app

# 3. Container (interface = your container veth)
/container add remote-image=enesilhaydin/mt-telegram-bot:latest \
  interface=veth1 envlist=mt-bot mounts=mt-bot-data,mt-bot-code \
  root-dir=usb1/container/mt-bot start-on-boot=yes \
  hostname=mt-bot logging=yes dns=172.17.0.1

# 4. Allow API + internet for the container subnet
/ip service set api address+=172.17.0.0/24
/interface list add name=CONTAINER
/interface list member add list=CONTAINER interface=containers
/ip firewall filter add chain=input action=accept in-interface-list=CONTAINER protocol=udp dst-port=53  comment="IN: CONTAINER DNS"
/ip firewall filter add chain=input action=accept in-interface-list=CONTAINER protocol=tcp dst-port=8728 comment="IN: CONTAINER API"
/ip firewall filter add chain=input action=drop   in-interface-list=CONTAINER comment="IN: CONTAINER drop rest"
/ip firewall filter add chain=forward action=accept src-address=172.17.0.0/24 out-interface-list=WAN comment="FWD: Container -> WAN"

# 5. Start
/container start [find name~"mt-telegram"]

⁠🧱 Architecture: volume-mounted code (low-end routers)

On low-power routers (dual-core ARM, USB storage), re-pulling and re-extracting the full image on every code change is slow and can wedge the RouterOS container daemon. Solution: the Python package (app/) is volume-mounted from USB into /app/app, so the image only carries the runtime + dependencies (which rarely change). Updating code = copy .py files to USB + restart the container (~10s). No pull, no extract, no reboot.

• mt-bot-data → /app/data (SQLite, persists)
• mt-bot-code → /app/app (Python code, overrides the image copy)

⁠Updating code (no re-pull)

Copy deploy.sh.example → deploy.sh, fill in your credentials, then:

./deploy.sh

It uploads app/*.py over FTP (LAN-only, auto-disabled) and restarts the container.

⁠Updating dependencies (rare — image rebuild)

Only when requirements.txt changes:

docker buildx build --platform linux/arm/v5 -t <repo>/mt-telegram-bot:latest --push .

Then remove + re-add the container (full re-pull). That's why code lives in a volume mount, not the image.

⁠🧪 Testing

# Import + i18n integrity (no router needed)
python3 test_smoke.py

# + live read-only router checks
ROUTER_IP=192.168.88.1 ROUTER_USER=api-user ROUTER_PASS=... python3 test_smoke.py

deploy.sh also runs a syntax check on every deploy.

⁠🔨 Build

# ARM/v5 (hEX S, hAP ac²)      ARM64 (RB5009, CCR2xxx)        x86_64 (CHR, x86)
docker buildx build --platform linux/arm/v5  -t <repo>/mt-telegram-bot:latest --push .
docker buildx build --platform linux/arm64   -t <repo>/mt-telegram-bot:latest --push .
docker buildx build --platform linux/amd64   -t <repo>/mt-telegram-bot:latest --push .

⁠🌍 i18n

Turkish & English, toggled with /lang. Strings live in app/i18n.py (TR/EN key parity is verified by test_smoke.py).

⁠📄 License

CC BY-NC-SA 4.0 — Creative Commons Attribution-NonCommercial-ShareAlike 4.0.

• ✅ Free to use, modify and share for non-commercial purposes
• ✍️ Must give credit (attribution)
• 🔁 Derivatives must stay under the same license (open)
• ⛔ Commercial / paid use is not permitted without separate written permission