| alertbot.ini | ||
| alertbot.py | ||
| LICENSE | ||
| README.md | ||
📡 AlertBot - Reticulum LXMF Alert System v0.1
Un bot di messaggistica di massa per la rete Reticulum/LXMF, pensato per la gestione di gruppi di allerta in scenari di emergenza, comunicazioni decentralizzate e notifiche critiche off-grid.
💡 Idea e caso d'uso
AlertBot nasce dall'esigenza di avere un sistema di notifica affidabile e indipendente da infrastrutture centralizzate: niente server cloud, niente app commerciali, niente dipendenza da internet.
Basandosi su Reticulum Network Stack e il protocollo LXMF, AlertBot può funzionare su:
- 🔗 Reti LoRa (RNode, Heltec, LILYGO)
- 📶 WiFi mesh (OpenWrt, LibreMesh, B.A.T.M.A.N.-adv)
- 🌐 TCP/IP (internet, VPN, LAN)
- 🔀 Qualsiasi combinazione delle precedenti
Scenari tipici:
- Gruppi di protezione civile e volontariato
- Comunicazioni di emergenza in zone senza copertura cellulare
- Ham radio operators con nodi RNode
- Community off-grid che necessitano di broadcast rapido
- Notifiche critiche su infrastrutture (server down, alert IoT, ecc.)
Il gestore del bot (master admin) controlla una lista di iscritti verificati. In caso di emergenza, un singolo comando /alert raggiunge tutti i destinatari tramite la rete mesh, instradando automaticamente attraverso i nodi disponibili.
📋 Requisiti
pip install rns lxmf
Nota: Reticulum deve essere configurato con almeno un'interfaccia attiva (LoRa, TCP, I2P, ecc.).
Per la configurazione di Reticulum vedere la documentazione ufficiale.
🚀 Quick Start
1. Clona il repository
git clone https://github.com/fr33n0w/alertbot.git
cd alertbot
2. Installa le dipendenze
pip install rns lxmf
3. Avvia il bot
python alertbot.py
Al primo avvio il bot:
- Genera automaticamente una nuova identità Reticulum (
alertbot_identity) - Crea il file di configurazione
alertbot.inicon tutti i valori di default - Crea il file
admins.txtvuoto con le istruzioni - Annuncia la sua presenza sulla rete
Output atteso:
[AlertBot] Avvio Reticulum...
[AlertBot] Nuova identità : <ab:cd:ef:12:34:56:...>
[AlertBot] Display name : Alert-a1b2cd
[AlertBot] LXMF address : abcdef1234567890...
[AlertBot] Iscritti : 0
[AlertBot] Admin : 0
[AlertBot] ⚠ Nessun master admin configurato!
[AlertBot] Invia /claimmaster da LXMF per impostarlo,
[AlertBot] oppure modifica manualmente: admins.txt
[AlertBot] Announce inviato. In ascolto...
4. Imposta il master admin
Hai due opzioni:
Via LXMF - dal tuo client (Sideband, NomadNet, ecc.) cerca il bot per nome o hash e invia:
/claimmaster
Funziona solo se non esiste ancora nessun master admin. Dopo il primo claim, il comando viene disabilitato.
Via file - modifica admins.txt direttamente:
master:aabbccddee1122334455667788990011aabbccddee1122334455667788990011
📁 Struttura dei file
alertbot/
├── alertbot.py # Script principale
├── alertbot.ini # Configurazione (auto-generato)
├── alertbot_identity # Identità Reticulum (auto-generato)
├── admins.txt # Hash degli admin (auto-generato)
├── subscribers.json # Lista iscritti (auto-generato)
├── pending.json # Richieste iscrizione in attesa (auto-generato)
└── intro.txt # Messaggio di benvenuto personalizzato (opzionale)
⚠️ Non condividere
alertbot_identity- contiene la chiave privata del bot.
⚙️ Configurazione - alertbot.ini
Il file viene generato automaticamente al primo avvio. Ogni parametro è commentato.
[bot]
| Parametro | Default | Descrizione |
|---|---|---|
display_name |
auto |
Nome visualizzato nella rete. auto genera Alert-XXXXXX dall'hash dell'identità |
auto_announce_interval |
360 |
Secondi tra un announce automatico e l'altro. 0 = disabilitato |
delivery_timeout |
60 |
Timeout in secondi per la path discovery durante il broadcast |
send_delay |
0.4 |
Pausa in secondi tra un invio e l'altro durante un broadcast |
propagation_node |
(vuoto) | Hash del nodo di propagazione LXMF preferito |
[lxmf]
| Parametro | Default | Descrizione |
|---|---|---|
desired_method |
auto |
Metodo di consegna: auto (OPPORTUNISTIC), direct, propagated |
stamp_cost |
0 |
Costo stamp richiesto ai mittenti. 0 = nessuno |
[access]
| Parametro | Default | Descrizione |
|---|---|---|
open_subscription |
false |
false = /sub richiede approvazione admin. true = iscrizione immediata |
allow_unsub |
true |
Permette agli iscritti di disiscriverssi con /unsub |
reply_to_unknown |
true |
Risponde con l'intro a messaggi non-comando |
[messages]
| Parametro | Default | Descrizione |
|---|---|---|
alert_title |
ALERT |
Titolo LXMF dei messaggi /alert |
broadcast_title |
BROADCAST |
Titolo LXMF dei messaggi /broadcast |
max_alert_length |
2000 |
Lunghezza massima del testo alert in caratteri. 0 = illimitato |
alert_prefix |
🚨 |
Prefisso aggiunto automaticamente al testo degli alert |
[menu]
| Parametro | Default | Descrizione |
|---|---|---|
help_header |
╔══════ Alert Bot ══════╗ |
Intestazione del menu /help |
help_footer |
╚═══════════════════════╝ |
Piè di pagina del menu /help |
👥 Ruoli e permessi
AlertBot ha tre livelli di accesso:
| Ruolo | Descrizione |
|---|---|
| Utente | Chiunque contatti il bot. Può iscriversi e ricevere alert |
| Admin | Gestisce iscritti e invia alert. Nominato dal master |
| Master Admin | Pieno controllo del bot. Unico, non rimuovibile |
📨 Comandi utente
Disponibili per chiunque contatti il bot.
| Comando | Descrizione |
|---|---|
/help |
Mostra il menu dei comandi disponibili per il proprio ruolo |
/info |
Mostra nome, hash LXMF del bot, numero di iscritti e admin |
/sub |
Invia una richiesta di iscrizione. Con open_subscription = true aggiunge direttamente. Con open_subscription = false (default) la richiesta viene inoltrata agli admin per approvazione |
/unsub |
Rimuove sé stessi dalla lista iscritti (se allow_unsub = true) |
🔧 Comandi admin
Disponibili per admin e master admin.
| Comando | Descrizione |
|---|---|
/alert <messaggio> |
Invia un alert a tutti gli iscritti. Il messaggio viene preceduto dal prefisso configurato (default 🚨) e dal titolo ALERT |
/broadcast <messaggio> |
Invia un messaggio a tutti gli iscritti senza prefisso né tag di allerta |
/list |
Mostra la lista completa degli hash degli iscritti |
/listadmins |
Mostra la lista degli admin con il loro ruolo (master/admin) |
/pending |
Mostra le richieste di iscrizione in attesa con timestamp e comandi di approvazione pronti |
/approve <hash> |
Approva la richiesta di iscrizione di un utente. L'utente riceve una notifica di conferma |
/deny <hash> |
Rifiuta la richiesta di iscrizione. L'utente riceve notifica del rifiuto |
/add <hash> |
Aggiunge direttamente un iscritto senza passare dal flusso di richiesta |
/remove <hash> |
Rimuove un iscritto dalla lista |
/status |
Mostra lo stato completo del bot: iscritti, pending, admin, configurazione attiva |
/announce |
Forza un announce immediato sulla rete |
/showintro |
Mostra il testo intro attuale e indica se proviene da intro.txt o dal default |
👑 Comandi master admin
Disponibili solo per il master admin.
| Comando | Descrizione |
|---|---|
/addadmin <hash> |
Promuove un utente al ruolo di admin |
/removeadmin <hash> |
Revoca i privilegi di admin (non può rimuovere il master) |
/setname <nome> |
Cambia il display name del bot. Usa auto per tornare al nome generato dall'hash. Richiede riavvio |
/setdelay <secondi> |
Modifica la pausa tra gli invii del broadcast a runtime, senza riavviare |
/setintro <testo> |
Modifica il messaggio di benvenuto. Usa \n per i ritorni a capo. /setintro default ripristina il testo originale |
/showintro |
Mostra il testo intro attuale |
/claimmaster |
Disponibile solo se non esiste ancora nessun master admin. Registra il mittente come master |
🔔 Flusso di iscrizione con approvazione
Con open_subscription = false (impostazione consigliata per gruppi chiusi):
Utente Bot Admin
│ │ │
│──── /sub ─────────────▶│ │
│ │──── "Richiesta inviata" ─▶│ (conferma all'utente)
│ │ │
│ │──── notifica a tutti ───▶│ (con /approve e /deny pronti)
│ │ │
│ │◀─── /approve <hash> ─────│
│ │ │
│◀─── "Approvato!" ──────│ │
│ │──── "Approvato per..." ──▶│ (conferma all'admin)
Gli admin ricevono:
📬 Nuova richiesta di iscrizione
──────────────────────────────
Hash: aabbccdd1122...
──────────────────────────────
Approva : /approve aabbccdd1122...
Rifiuta : /deny aabbccdd1122...
Le richieste in attesa persistono in pending.json anche dopo un riavvio del bot.
📝 Messaggio di benvenuto personalizzato
Quando un utente contatta il bot per la prima volta (o invia un testo libero), riceve il messaggio intro.
Ordine di priorità:
- Contenuto di
intro.txtnella cartella del bot (se esiste e non è vuoto) - Testo di default hardcoded nel codice
Modifica via filesystem:
nano intro.txt
Nessun riavvio necessario - il file viene letto ad ogni invio.
Modifica via LXMF (master admin):
/setintro 📡 Gruppo Alert Protezione Civile\n\nQuesto bot invia notifiche di emergenza.\nUsa /sub per richiedere l'iscrizione.
Ripristino al default:
/setintro default
🔐 Sicurezza e gestione admin
Il file admins.txt contiene gli hash degli amministratori nel formato:
# AlertBot - File Admin
# Formato: ruolo:hash_completo
master:aabbccddee1122334455667788990011aabbccddee1122334455667788990011
admin:1122334455667788990011aabbccddee1122334455667788990011aabbccddee
admin:ffeeddccbbaa9988776655443322110011223344556677889900aabbccddeeff
- Il master è unico. Se si prova a impostarne un secondo via file, il bot usa il primo che trova.
- Il file viene riscritto dal bot quando si usano
/addadmino/removeadmin- i commenti vengono persi. Usa questi comandi oppure modifica il file a mano con il bot fermo. - L'hash usato è quello LXMF del client (non l'hash RNS dell'identità), visibile in Sideband sotto "Your LXMF address".
🛠️ Avvio come servizio (Linux/systemd)
[Unit]
Description=AlertBot LXMF
After=network.target
[Service]
ExecStart=/usr/bin/python3 /opt/alertbot/alertbot.py
WorkingDirectory=/opt/alertbot
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
sudo cp alertbot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now alertbot
sudo journalctl -fu alertbot
🔗 Risorse
- Reticulum Network Stack
- LXMF
- Sideband - client LXMF per Android/desktop
- NomadNet - client e nodo per desktop
- rmap.world - mappa nodi Reticulum
📄 Licenza
MIT License - libero uso, modifica e distribuzione.