Best practice di sicurezza per i bot Telegram

1. Tratta il token come una credenziale viva

Chi possiede il token del tuo bot lo controlla completamente. Può leggere i messaggi in arrivo, inviare messaggi a tuo nome e cambiare il tuo webhook così che il tuo server smetta di ricevere aggiornamenti. Non c'è nessuna richiesta di password né approvazione del dispositivo di mezzo.

Dove sfugge il token

• Viene committato in un repository. Di gran lunga la via più comune, e i repository pubblici sono scansionati continuamente da bot che non sono i tuoi.
• Viene incollato in una chat di supporto o in un issue tracker. Una volta finito in un ticket, finisce anche in un indice di ricerca da qualche parte.
• Viene scritto direttamente in una build mobile o frontend. Tutto ciò che arriva su un dispositivo client è pubblico.
• Resta nei log. Se registri l'URL completo dell'API, il token è nell'URL.

Cosa fare invece

• Tieni il token in una variabile d'ambiente o in un secrets manager, mai nel codice sorgente.
• Aggiungi .env a .gitignore prima del primo commit, non dopo.
• Oscura il token nell'output dei log.
• Usa token separati per sviluppo e produzione, così un token di test compromesso non può toccare utenti reali.

Se un token viene compromesso, revocalo

Apri BotFather, esegui /revoke e scegli il bot. Il vecchio token smette di funzionare immediatamente e ne ricevi uno nuovo. Ruotarlo costa qualche minuto di inattività. Lasciarlo compromesso costa il bot. Riscrivere la cronologia git non serve, perché il token è già stato raccolto.

2. Blinda il webhook

Se il tuo bot usa un webhook, quell'URL è un endpoint aperto su internet. Chiunque lo trovi può pubblicare aggiornamenti falsi identici al vero traffico Telegram.

• Imposta un token segreto. Il metodo setWebhook accetta un parametro secret_token. Telegram lo rimanda poi indietro nell'header X-Telegram-Bot-Api-Secret-Token a ogni richiesta. Rifiuta tutto ciò che non corrisponde.
• Usa HTTPS con un certificato valido. Telegram lo richiede, e impedisce che il payload sia leggibile durante il transito.
• Usa un percorso impossibile da indovinare. Un segmento casuale nell'URL da solo non è vera sicurezza, ma ti toglie dalle scansioni opportunistiche.
• Limita cosa ricevi. Il parametro allowed_updates ti permette di sottoscrivere solo i tipi di aggiornamento che gestisci. Meno superficie, meno parsing.
• Rispondi velocemente. Conferma la richiesta, poi svolgi il lavoro in modo asincrono. Gestori di webhook lenti sono un attacco denial of service in attesa di accadere.

3. Non fidarti mai del contenuto di un update

Tutto ciò che è dentro un update è stato digitato da un utente. Il nome visualizzato, il testo del messaggio, i dati di callback alla pressione di un pulsante. Tutto questo è input controllato da un attaccante.

• Valida i dati di callback lato server. Un pulsante che porta order_id=123 può essere ripetuto con order_id=124. Verifica che l'utente che preme sia il proprietario del record.
• Esegui l'escape del testo utente prima di ripeterlo. Se invii messaggi in modalità HTML o Markdown e incolli un nome visualizzato direttamente, un nome creato ad arte può rompere la tua formattazione o iniettare un link.
• Parametrizza le query al database. Un input di chat che arriva a una query string comporta lo stesso rischio di injection di un form web.
• Limita le dimensioni che accetti. Imposta limiti sulla lunghezza del testo e sulla dimensione dei file prima di elaborare qualsiasi cosa.

4. Blinda i comandi admin

Quasi ogni bot finisce per avere un comando admin. Broadcast, rimborso, esportazione utenti. È qui che un bot funzionante diventa un incidente.

• Controlla una allowlist di ID utente lato server, tenuta in configurazione. Non dedurre mai lo stato di admin da uno username, che può essere cambiato e riutilizzato.
• Non nascondere, verifica. Un comando non documentato viene scoperto nel momento in cui qualcuno lo prova. L'oscurità non è il controllo.
• Conferma le azioni distruttive con un secondo passaggio, e includi cosa sta per accadere nel testo di conferma.
• Registra le azioni admin con l'ID utente e il timestamp, così puoi rispondere in seguito a "chi ha inviato quel broadcast".

5. Attiva la modalità privacy nei gruppi

Per impostazione predefinita, un bot aggiunto a un gruppo riceve solo messaggi che sono comandi, risposte ai propri messaggi o menzioni dirette. Questo comportamento predefinito si chiama modalità privacy ed esiste per una buona ragione.

Puoi disattivarla con /setprivacy in BotFather così che il bot veda ogni messaggio nel gruppo. Fallo solo se una funzionalità lo richiede davvero. Una volta disattivata, il tuo server memorizza le conversazioni di altre persone, e quella responsabilità diventa tua.

6. Limita la tua velocità e quella dei tuoi utenti

Telegram applica i propri limiti, e superarli ti porta a essere rallentato o temporaneamente bloccato. L'indicazione generale di Telegram è di circa 30 messaggi al secondo su chat diverse, e circa 20 messaggi al minuto nello stesso gruppo. Trattali come tetti da restare ampiamente sotto, non come obiettivi.

• Metti in coda i messaggi in uscita invece di inviarli in un ciclo stretto.
• Rispetta il valore retry-after quando l'API restituisce un 429, invece di riprovare immediatamente.
• Limita anche per utente. Una sola persona che fa spam con un comando non dovrebbe poter far salire i tuoi costi o esaurire la tua quota.
• Metti un tempo di attesa su tutto ciò che è costoso, come le chiamate a un modello di IA a pagamento o un passaggio di generazione immagini.

7. Raccogli meno dati utente

Il record più sicuro è quello che non hai mai salvato. I bot accumulano per impostazione predefinita ID chat, nomi, numeri di telefono e contenuto dei messaggi, e la maggior parte non viene mai usata.

• Salva l'ID chat e ciò di cui hai davvero bisogno. Salta il resto.
• Non loggare il corpo completo dei messaggi a meno che tu non abbia un motivo concreto e un limite di conservazione.
• Imposta un periodo di conservazione ed elimina secondo pianificazione.
• Cifra i campi sensibili a riposo e limita chi può interrogare il database.
• Supporta le richieste di cancellazione. Sotto il GDPR e leggi simili un utente può chiederti di rimuovere i suoi dati, e ti serve un modo per farlo.
• Dichiara cosa raccogli in una privacy policy a cui il bot possa collegarsi.

Nota che i numeri di telefono ti raggiungono solo se l'utente tocca un pulsante di richiesta contatto. Chiederne uno di cui non hai bisogno è sia un costo di conversione che una responsabilità.

8. Verifica i dati di Web App e Login Widget

Se il tuo bot apre una Telegram Web App o usi il Login Widget su un sito web, i dati utente arrivano con un hash. Verifica quell'hash sul tuo server usando il token del tuo bot prima di fidarti anche di un solo campo. Saltare questo controllo significa che chiunque può fingersi qualsiasi utente modificando la richiesta.

9. Tieni d'occhio anche le cose banali

• Aggiorna le dipendenze. La maggior parte delle compromissioni reali arriva tramite una libreria, non tramite Telegram.
• Limita chi può fare il deploy e chi può leggere i segreti di produzione.
• Osserva pattern insoliti: un picco su un singolo comando, messaggi da un singolo utente in un ciclo stretto, richieste che falliscono il controllo del token segreto.
• Abbi un piano per il giorno no. Revoca il token, ferma il webhook, ripristina da un backup. Scrivilo prima di averne bisogno.

La checklist

• Il token vive nelle variabili d'ambiente, non su git, ed è oscurato nei log.
• Sai come eseguire /revoke in BotFather.
• Il webhook usa HTTPS e un token segreto che verifichi a ogni richiesta.
• allowed_updates è impostato solo su ciò che gestisci.
• I dati di callback vengono autorizzati lato server, non considerati affidabili così come arrivano.
• Il testo utente viene sottoposto a escape prima di essere ripetuto in un messaggio formattato.
• I comandi admin controllano una allowlist di ID e vengono registrati.
• La modalità privacy è attiva a meno che una funzionalità non la richieda davvero disattivata.
• I messaggi in uscita vengono messi in coda e le risposte 429 vengono rispettate.
• Salvi il minimo indispensabile, elimini secondo pianificazione e puoi soddisfare una richiesta di cancellazione.
• I payload di Web App e Login Widget sono verificati con hash.

Continua a leggere

• Guida a BotFather, incluso come revocare e ruotare un token
• Best practice per i bot Telegram, la checklist più ampia
• Best practice UX per i bot Telegram, per il lato design

Domande frequenti

Cosa succede se il token del mio bot Telegram viene compromesso?

Chi lo possiede controlla il bot completamente. Può leggere i messaggi in arrivo, inviare messaggi a tuo nome e cambiare il webhook così che il tuo server smetta di ricevere aggiornamenti. Non c'è nessuna richiesta di password di mezzo.

Come revoco il token di un bot Telegram?

Apri BotFather, invia il comando di revoca e scegli il bot. Il vecchio token smette di funzionare immediatamente e ne ricevi uno nuovo. Riscrivere la cronologia git non serve, perché un token compromesso viene raccolto nel giro di pochi minuti.

Il mio bot vede tutti i messaggi in un gruppo?

Solo se disattivi la modalità privacy. Per impostazione predefinita, un bot in un gruppo riceve solo comandi, risposte ai propri messaggi e menzioni dirette. Disattivare la modalità privacy fa sì che il tuo server memorizzi le conversazioni di altre persone.

Mi serve un token segreto sul webhook?

Sì. Senza, chiunque trovi l'URL del tuo webhook può pubblicare aggiornamenti falsi identici al vero traffico Telegram. Imposta il segreto quando registri il webhook e rifiuta le richieste il cui header non corrisponde.