Skip to content
All projects

Caça-Golpes

An AI agent on Telegram that analyzes suspicious messages and links using real threat data

Role
Independent project · AI Engineering
Status
Python · Gemini API · VirusTotal API · Telegram Bot API · 41 tests

Caça-Golpes (Scam Hunter) is an AI agent that takes a suspicious message on Telegram and explains, in plain language, whether it shows signs of a scam. I built it in pure Python as a pipeline with two LLM calls, a threat-intelligence API lookup and guardrails against hallucination and prompt injection.

Tech stack

  • Python

    Standard library only (urllib, json, re, dataclasses). Orchestration, HTTP calls and tests with zero external dependencies.

  • Gemini API

    Two roles: a lightweight classifier (gemini-3.1-flash-lite, temperature 0, JSON output) and the analysis agent (gemini-3.5-flash). The lightweight model also serves as the fallback when the main one is unavailable.

  • VirusTotal API v3

    Reputation for each link: how many security engines flagged it as malicious or suspicious. Never-scanned links, invalid keys and rate limits become clear answers.

  • Telegram Bot API

    The user interface. Long polling, no public server needed; long replies are split at Telegram's size limit.

  • Prompt engineering

    A system prompt with a fixed answer format (verdict, reasons, recommendation), rules to cite only the data received, and user text wrapped in delimiters.

  • unittest

    41 tests with fake Gemini, VirusTotal and Telegram clients that run offline and use no API quota.

The problem

SMS and WhatsApp scams work because they arrive with urgency and look legitimate. People don't always know how to judge a link or a message before clicking. I wanted a tool that answers right where the doubt shows up: in the chat.

Architecture

1. Classification: a lightweight model with JSON output separates security questions, greetings and off-topic messages. Off-topic messages get a polite refusal and never reach the agent. 2. Evidence: the code extracts up to 3 links and checks them against VirusTotal before any call to the agent. 3. Reasoning: the agent receives the delimited message plus the VirusTotal result as a system data block, and combines red flags in the text (urgency, password requests, spoofed senders) with the links' reputation. 4. Answer: a verdict, reasons and a practical recommendation, short enough to read on a phone. Each chat keeps a short history for follow-up questions.

From n8n to Python

The first version was an n8n flow where the agent had VirusTotal as a tool and decided on its own when to use it. Sometimes the lookup failed without my noticing, and the verdict came out with no real data behind it. In the rewrite, the step that must be guaranteed was taken away from the model: the code always queries VirusTotal and the model only interprets the result.

Guardrails and reliability

• Grounding: the model may only cite the numbers it receives and never calls a link "safe"; with no flags, it says that guarantees nothing. • Prompt injection: user text is wrapped in delimiters and treated as content to analyze, never as instructions. Attempts to close the delimiter are stripped. • Resilience: Gemini 429, 500 and 503 errors trigger retries with increasing backoff, and if the main model stays down, the fallback answers. • Fail-safe: if the classifier fails, the message goes on to analysis; if the agent fails, the user gets safe guidance instead of an error. • Secrets: API keys and the Telegram token are stripped from URLs before any log or error message. • Privacy: the bot warns that checked links become part of VirusTotal's database.

Quality and tests

The Gemini, VirusTotal and Telegram clients take the request function as a parameter, so tests swap the network for fake clients. 41 tests cover link extraction, API error handling, retries, the fallback model, injection delimiting, memory and a full cycle of the main loop. A terminal mode also lets you test the keys without Telegram.

Limitations and next steps

No image analysis yet (screenshots and QR codes), conversation history lives only in RAM and the bot runs locally. Next steps: QR code reading and deployment. It is an educational assistant and does not replace professional threat analysis tools.

ProgramAuto

Next project