One BOT_TOKEN = "..." in a public repository hands your bot to a stranger, and a webhook set without secret_token lets anyone who finds the URL post a fake update that claims to come from your admin. On the Mini App side, a server that reads the user id from initData without checking its signature lets one shopper act as another. This skill finds those and the other Telegram bot and Mini App mistakes below before you deploy, and tells you how to fix each one.

Your agent runs a scanner on your bot and Mini App code (python-telegram-bot, aiogram, pyTelegramBotAPI, Telegraf, grammY, node-telegram-bot-api and PHP bots, plus Express, FastAPI and similar Mini App backends), .env files and JSON, YAML and TOML config. It skips comments, follows chat text through simple assignments, knows each library's webhook defaults (Telegraf's secret path, node-telegram-bot-api's token path) and the usual guards (a compared secret header, secret paths, verify middleware, filters.User, F.from_user.id, getChatMember, html.escape, safe_parse_webapp_init_data), gives credit for an nginx allow list of Telegram's networks in the project, and checks test folders for tokens only. It never runs the bot or contacts Telegram. It returns BLOCK, REVIEW, or NOT FLAGGED, with the file, line, reason, and a safer approach. Tokens are never printed.

What it checks

BLOCK (fix before shipping)

• T01: bot tokens in code, config files, .env.example files, api.telegram.org URLs or VITE_ and NEXT_PUBLIC_ variables that ship to the browser
• T02: webhooks set or served without a secret token: setWebhook without secret_token, run_webhook, start_webhook, SimpleRequestHandler or webhookCallback without one, or routes that never check the X-Telegram-Bot-Api-Secret-Token header
• T03: Mini App initData parsed on the server without a signature check that uses it, or initDataUnsafe read from a request
• T04: message text, command arguments or callback data passed to eval, exec or a shell

REVIEW (check before release)

• T11: admin commands (/ban, /broadcast, /restart, /sql and similar) without a user check
• T12: user names and message text sent as HTML or Markdown without escaping
• T13: bot tokens in logs: printed tokens, file links, and python-telegram-bot logging httpx request URLs
• T14: pre-checkout queries approved without looking at the order
• T15: download or file paths built from the sender's file name or message text
• T16: Mini App front ends that send initDataUnsafe user ids to the API
• T17: Mini App init data accepted at any age (no auth_date check)

What's included

• The scanner (Python 3.9+, standard library only)
• A rules guide with the reason, safer approach and official source for each rule
• A risky and a safe example project (bot, Mini App front end and backend), and the real report the scanner produces on the risky one

Limits

It reads each file as written: checks that live in another file (a middleware that verifies the webhook header or init data, an admin filter added elsewhere), reverse-proxy rules other than an nginx allow list in the project, BotFather settings and values built across modules are not followed. NOT FLAGGED is not a guarantee.

Contents

One ZIP file with 21 files: SKILL.md, the scanner in scripts/ (8 Python files), references/rules.md (every rule with its reason and safer approach), and examples/ (10 example files plus report.md, the real scanner output on the risky example).

How to use: This is an agent skill: a folder with a SKILL.md file and Python scripts that an AI coding agent such as Claude Code, Cursor, or Codex CLI can run. Unzip it into your agent's skills folder (for Claude Code: ~/.claude/skills/), then ask your agent to check your project. The scripts also run on their own with Python 3.9 or newer, with nothing to install. They read your files only: no network access, and nothing is sent anywhere.