Melhores práticas de segurança para bots do Telegram

1. Trate o token como uma credencial viva

Quem estiver com o token do seu bot o controla por completo. Pode ler as mensagens recebidas, enviar mensagens em seu nome e mudar seu webhook para que seu próprio servidor pare de receber atualizações. Não existe tela de senha nem aprovação de dispositivo no caminho.

Onde os tokens vazam

• Enviados a um repositório. De longe o caminho mais comum, e repositórios públicos são escaneados continuamente por bots que não são seus.
• Colados em um chat de suporte ou em um sistema de tickets. Uma vez em um ticket, ele acaba em algum índice de busca em algum lugar.
• Fixados no código de um build mobile ou frontend. Tudo que é enviado a um dispositivo cliente é público.
• Deixados nos logs. Se você registra a URL completa da API, o token está na URL.

O que fazer em vez disso

• Mantenha o token em uma variável de ambiente ou em um gerenciador de segredos, nunca no código-fonte.
• Adicione .env ao .gitignore antes do primeiro commit, não depois.
• Oculte o token na saída dos logs.
• Use tokens separados para desenvolvimento e produção, para que um token de teste vazado não afete usuários reais.

Se um token vazar, revogue-o

Abra o BotFather, execute /revoke e escolha o bot. O token antigo para de funcionar imediatamente e você recebe um novo. Rotacioná-lo custa alguns minutos de instabilidade. Deixá-lo como está custa o bot. Reescrever o histórico do git não ajuda, porque o token já foi capturado.

2. Blinde o webhook

Se seu bot usa um webhook, essa URL é um endpoint aberto na internet. Qualquer pessoa que a encontrar pode publicar atualizações falsas que parecem exatamente tráfego real do Telegram.

• Defina um token secreto. O método setWebhook aceita um parâmetro secret_token. O Telegram então o devolve no cabeçalho X-Telegram-Bot-Api-Secret-Token em toda requisição. Rejeite tudo que não corresponder.
• Use HTTPS com um certificado válido. O Telegram exige isso, e evita que o conteúdo seja legível em trânsito.
• Use um caminho impossível de adivinhar. Um segmento aleatório na URL não é segurança de verdade por si só, mas te tira das varreduras oportunistas.
• Limite o que você recebe. O parâmetro allowed_updates permite que você assine apenas os tipos de atualização que você trata. Menos superfície, menos parsing.
• Responda rápido. Confirme o recebimento da requisição e depois faça o trabalho de forma assíncrona. Handlers de webhook lentos são uma negação de serviço esperando para acontecer.

3. Nunca confie no conteúdo de uma atualização

Tudo dentro de uma atualização foi digitado por um usuário. O nome exibido, o texto da mensagem, os dados de callback ao apertar um botão. Tudo isso é entrada controlada por um invasor.

• Valide os dados de callback no servidor. Um botão que carrega order_id=123 pode ser reproduzido com order_id=124. Verifique se o usuário que apertou é dono do registro.
• Escape o texto do usuário antes de repeti-lo. Se você envia mensagens em modo HTML ou Markdown e cola um nome exibido diretamente, um nome preparado pode quebrar sua formatação ou injetar um link.
• Parametrize as consultas ao banco de dados. Uma entrada de chat que chega a uma query string carrega o mesmo risco de injeção que um formulário web.
• Limite os tamanhos que você aceita. Defina limites de comprimento de texto e tamanho de arquivo antes de processar qualquer coisa.

4. Blinde os comandos de administrador

Quase todo bot acaba ganhando um comando de administrador. Broadcast, reembolso, exportar usuários. É aí que um bot funcional vira um incidente.

• Verifique uma lista de permissões de IDs de usuário no servidor, mantida em configuração. Nunca deduza status de administrador a partir de um nome de usuário, que pode ser alterado e reutilizado.
• Não esconda, verifique. Um comando não documentado é descoberto no momento em que alguém tenta usá-lo. Obscuridade não é controle.
• Confirme ações destrutivas com uma segunda etapa, e inclua o que está prestes a acontecer no texto de confirmação.
• Registre ações de administrador com o ID do usuário e o timestamp, para poder responder depois "quem enviou aquele broadcast".

5. Ative o modo privacidade em grupos

Por padrão, um bot adicionado a um grupo só recebe mensagens que são comandos, respostas às suas próprias mensagens ou menções a ele. Esse padrão se chama modo privacidade e existe por um bom motivo.

Você pode desativá-lo com /setprivacy no BotFather para que o bot veja todas as mensagens do grupo. Faça isso apenas se uma funcionalidade realmente precisar. Uma vez desativado, seu servidor passa a armazenar as conversas de outras pessoas, e essa responsabilidade passa a ser sua.

6. Limite sua própria taxa e a dos seus usuários

O Telegram aplica seus próprios limites, e atingi-los faz você ser desacelerado ou bloqueado temporariamente. A orientação geral do Telegram é de cerca de 30 mensagens por segundo entre chats diferentes, e cerca de 20 mensagens por minuto no mesmo grupo. Trate esses números como tetos para ficar bem abaixo, não como metas.

• Coloque as mensagens de saída em fila em vez de enviá-las em um loop apertado.
• Respeite o valor de retry-after quando a API retornar um 429, em vez de tentar novamente de imediato.
• Limite também por usuário. Uma única pessoa fazendo spam de um comando não deveria conseguir elevar seus custos ou esgotar sua cota.
• Coloque um tempo de espera em qualquer coisa cara, como chamadas a um modelo de IA pago ou uma etapa de geração de imagens.

7. Colete menos dados de usuário

O registro mais seguro é aquele que você nunca armazenou. Bots acumulam por padrão IDs de chat, nomes, números de telefone e conteúdo de mensagens, e a maior parte nunca é usada.

• Armazene o ID do chat e o que você realmente precisa. Pule o resto.
• Não registre o corpo completo das mensagens a menos que você tenha um motivo concreto e um limite de retenção.
• Defina um período de retenção e exclua conforme um cronograma.
• Criptografe campos sensíveis em repouso e restrinja quem pode consultar o banco de dados.
• Suporte pedidos de exclusão. Sob a LGPD e leis semelhantes, um usuário pode pedir para você remover os dados dele, e você precisa de uma forma de fazer isso.
• Diga o que você coleta em uma política de privacidade que o bot possa linkar.

Note que números de telefone só chegam até você se o usuário tocar em um botão de compartilhamento de contato. Pedir um que você não precisa é ao mesmo tempo um custo de conversão e uma responsabilidade.

8. Verifique os dados de Web App e Login Widget

Se seu bot abre um Telegram Web App ou você usa o Login Widget em um site, os dados do usuário chegam com um hash. Verifique esse hash no seu servidor usando o token do seu bot antes de confiar em um único campo. Pular essa verificação significa que qualquer um pode se passar por qualquer usuário editando a requisição.

9. Fique de olho nas coisas mais básicas também

• Atualize as dependências. A maioria dos comprometimentos reais vem por uma biblioteca, não pelo Telegram.
• Restrinja quem pode fazer deploy e quem pode ler os segredos de produção.
• Observe padrões incomuns: um pico em um único comando, mensagens de um único usuário em um loop apertado, requisições que falham na checagem do token secreto.
• Tenha um plano para o dia ruim. Revogar o token, parar o webhook, restaurar de um backup. Escreva isso antes de precisar.

A checklist

• O token vive em variáveis de ambiente, não no git, e é ocultado nos logs.
• Você sabe como rodar /revoke no BotFather.
• O webhook usa HTTPS e um token secreto que você verifica em cada requisição.
• allowed_updates está configurado apenas para o que você trata.
• Os dados de callback são autorizados no servidor, não confiados como enviados.
• O texto do usuário é escapado antes de ser repetido em uma mensagem formatada.
• Os comandos de administrador verificam uma lista de permissões de IDs e são registrados.
• O modo privacidade está ativo, a menos que uma funcionalidade realmente exija desativá-lo.
• As mensagens de saída são enfileiradas e as respostas 429 são respeitadas.
• Você armazena o mínimo, exclui conforme um cronograma e consegue atender a um pedido de exclusão.
• Os payloads de Web App e Login Widget são verificados por hash.

Continue lendo

• Guia do BotFather, incluindo como revogar e rotacionar um token
• Melhores práticas para bots do Telegram, a checklist mais ampla
• Melhores práticas de UX para bots do Telegram, para o lado do design

Perguntas frequentes

O que acontece se o token do meu bot do Telegram vazar?

Quem estiver com ele controla o bot por completo. Pode ler as mensagens recebidas, enviar mensagens em seu nome e mudar seu webhook para que seu próprio servidor pare de receber atualizações. Não existe nenhuma tela de senha no caminho.

Como eu revogo o token de um bot do Telegram?

Abra o BotFather, envie o comando de revogação e escolha o bot. O token antigo para de funcionar imediatamente e você recebe um novo. Reescrever o histórico do git não ajuda, porque um token vazado é capturado em minutos.

Meu bot vê todas as mensagens de um grupo?

Somente se você desativar o modo privacidade. Por padrão, um bot em um grupo recebe apenas comandos, respostas às próprias mensagens e menções diretas. Desativar o modo privacidade faz seu servidor armazenar as conversas de outras pessoas.

Eu preciso de um token secreto no meu webhook?

Sim. Sem ele, qualquer pessoa que encontrar a URL do seu webhook pode publicar atualizações falsas que parecem exatamente tráfego real do Telegram. Defina o segredo ao registrar o webhook e rejeite requisições cujo cabeçalho não corresponda.