Pular para o conteúdo
Todos os projetos

Caça-Golpes

Agente de IA no Telegram que analisa mensagens e links suspeitos com dados reais de ameaças

Papel
Projeto independente · AI Engineering
Situação
Python · Gemini API · VirusTotal API · Telegram Bot API · 41 testes

Um agente de IA que recebe uma mensagem suspeita no Telegram e responde, em linguagem simples, se há sinais de golpe. Construí em Python puro um pipeline com duas chamadas de LLM, consulta a uma API de inteligência de ameaças e guardrails contra alucinação e prompt injection.

Tecnologias

  • Python

    Só a biblioteca padrão (urllib, json, re, dataclasses). Orquestração, chamadas HTTP e testes, sem nenhuma dependência externa.

  • Gemini API

    Dois papéis: um classificador leve (gemini-3.1-flash-lite, temperatura 0, saída em JSON) e o agente de análise (gemini-3.5-flash). O modelo leve também é o reserva quando o principal fica indisponível.

  • VirusTotal API v3

    Reputação de cada link: quantos mecanismos de segurança o marcaram como malicioso ou suspeito. Link nunca analisado, chave inválida e limite de consultas viram respostas claras.

  • Telegram Bot API

    A interface com o usuário. Long polling, sem servidor público; respostas longas são divididas no limite de tamanho do Telegram.

  • Prompt engineering

    System prompt com formato de resposta fixo (veredito, motivos, recomendação), regras para citar só os dados recebidos e o texto do usuário delimitado por marcas.

  • unittest

    41 testes com clientes falsos de Gemini, VirusTotal e Telegram, que rodam sem internet e sem gastar cota de API.

O problema

Golpes por SMS e WhatsApp funcionam porque chegam com urgência e parecem legítimos. Quem recebe nem sempre sabe avaliar um link ou uma mensagem antes de clicar. Eu queria uma ferramenta que respondesse no mesmo lugar onde a dúvida aparece: no chat.

Arquitetura

1. Classificação: um modelo leve, com saída em JSON, separa o que é segurança digital, saudação ou outro assunto. Fora do tema, o bot recusa com educação e nem chama o agente. 2. Coleta de evidências: o código extrai até 3 links da mensagem e consulta o VirusTotal antes de qualquer chamada ao agente. 3. Raciocínio: o agente recebe a mensagem delimitada e o resultado do VirusTotal como bloco de dados do sistema, e combina os sinais do texto (urgência, pedido de senha, remetente falso) com a reputação dos links. 4. Resposta: veredito, motivos e uma recomendação prática, em texto curto para ler no celular. Cada conversa guarda um histórico curto para perguntas de acompanhamento.

Do n8n para Python

A primeira versão era um fluxo no n8n em que o agente tinha o VirusTotal como ferramenta e decidia sozinho quando usá-la. Em alguns casos a consulta falhava sem que eu percebesse, e o veredito saía sem dado real. Na reimplementação, a etapa que precisa ser garantida saiu das mãos do modelo: o código sempre consulta o VirusTotal e o modelo só interpreta o resultado.

Guardrails e confiabilidade

• Grounding: o modelo só pode citar os números que recebeu e nunca chama um link de "seguro"; sem sinalizações, ele diz que isso não garante nada. • Prompt injection: o texto do usuário vai entre marcas e é tratado como conteúdo a analisar, nunca como instrução. Se alguém tenta fechar a marca, ela é removida. • Resiliência: erros 429, 500 e 503 do Gemini geram novas tentativas com espera crescente e, se o modelo principal continuar fora, o reserva responde. • Falha segura: se o classificador falhar, a mensagem segue para a análise; se o agente falhar, o usuário recebe uma orientação segura em vez de um erro. • Segredos: chaves de API e o token do Telegram são removidos de URLs antes de qualquer log ou mensagem de erro. • Privacidade: o bot avisa que os links consultados passam a fazer parte da base do VirusTotal.

Qualidade e testes

Os clientes de Gemini, VirusTotal e Telegram recebem a função de requisição como parâmetro, então os testes trocam a rede por clientes falsos. São 41 testes que cobrem extração de links, tratamento de erros das APIs, novas tentativas, modelo reserva, delimitação contra injection, memória e um ciclo completo do loop principal. Há também um modo terminal para testar as chaves sem o Telegram.

Limitações e próximos passos

Ainda não analisa imagens (prints e QR codes), a memória das conversas fica só em RAM e o bot roda localmente. Próximos passos: leitura de QR code e deploy. É um assistente educativo e não substitui ferramentas profissionais de análise de ameaças.

ProgramAuto

Próximo projeto