telegram-bot-dumper

Простой дампер всего содержимого Telegram-бота.

Вход: только токен бота.

Выход: имя и информация о боте, текстовая история всех чатов и медиа, информация и фото пользователей бота.

---

Это реализация на Python.

🚀 Быстрая версия на Golang от ScBoln.

Веб-просмотрщик

Браузерный интерфейс в стиле Telegram Web для дампа: список чатов, полная история сообщений со встроенными медиа, профили пользователей с каруселью фото и глобальный поиск сразу по всем диалогам. Поддерживается режим реального времени: дампер запускается в фоне и транслирует новые сообщения в браузер в реальном времени.

Сценарий использования — пентест утёкшего токена бота. Токены Telegram-ботов постоянно всплывают в ходе работ — зашитые в мобильное/десктопное приложение, закоммиченные в репозиторий или оставленные в логе CI, конфигурационном файле либо клиентском бандле. Сам по себе токен выглядит как находка низкой критичности; загрузка его сюда показывает реальный масштаб ущерба. Для внутреннего бота (служба поддержки, помощник IT/DevOps, AI-ассистент) это все переписки сотрудников с ним — внутренние имена хостов, профили VPN, учётные данные и детали инфраструктуры — доступные для просмотра и поиска, что позволяет оценить масштаб и подтвердить находку в отчёте.

Запуск из готового образа (Docker Hub)

docker run --rm -p 8010:8010 -v "$PWD:/data" soxoj/telegram-bot-dumper-web

Или сборка локально

docker compose up --build      # builds and serves on http://127.0.0.1:8010

Или без Docker

pip install -r requirements.txt
python webapp/server.py        # serves the current directory's dumps on :8010

Откройте http://127.0.0.1:8010 и вставьте токен бота, чтобы выбрать папку его дампа. Просмотр в режиме только чтения не требует аутентификации, работает локально и не нуждается в учётных данных API. Для режима реального времени дополнительно нужны API_ID/API_HASH с my.telegram.org, передаваемые через окружение — никогда не зашитые в образ:

# one-off container
docker run --rm -p 8010:8010 -v "$PWD:/data" \
  -e API_ID=123456 -e API_HASH=abc... soxoj/telegram-bot-dumper-web

# or with docker compose: put them in a local .env (see .env.example)
cp .env.example .env && $EDITOR .env && docker compose up

Переменные окружения PORT и HOST переопределяют значения по умолчанию (8010, 127.0.0.1).

Возможности

• Дамп сообщений бота с медиаконтентом путём перебора id сообщений вверх (по умолчанию) или вниз (--down / --start-from-id).
• Режим прослушивания в реальном времени (--listen-only): приём новых сообщений в реальном времени с предложением дампить историю вниз начиная с первого замеченного id.
• Разрешение информации о пользователях как для входящих сообщений, так и для исходящих ответов бота.
• Облегчённые режимы для быстрого перечисления пользователей: пропуск медиа, пропуск текстовой истории по чатам, запись пользователей в единый CSV.
• Сообщения групп / супергрупп помечаются тегом [from:USER][group:CHAT]. Исходящие личные сообщения бота помечаются тегом [to:USER].
• Мониторинг групп: если бот добавлен в группу/супергруппу И его режим приватности отключён, бот получает все сообщения группы — не только команды и ответы — и --listen-only будет дампить их в реальном времени. При включённом режиме приватности (по умолчанию) бот видит только команды, упоминания и ответы.

Требования

• Python >= 3.6
• Telethon (закреплённая версия указана в requirements.txt)
• Зарегистрируйте приложение Telegram, чтобы получить API_ID и API_HASH

Использование как CLI-инструмента

pip install -r requirements.txt

# Telegram API credentials from https://my.telegram.org (read from the environment)
export API_ID=123456
export API_HASH=abc...

Быстрый старт — полный дамп (поведение по умолчанию)

Перебирает id 1..∞ вверх пакетами по 200, скачивая каждое сообщение, все медиа и все фото профилей пользователей. По умолчанию дампер продолжает слушать новые входящие сообщения после завершения дампа. Чтобы выйти сразу после дампа истории (идеально для скриптов и cron-задач), передайте --no-listen.

./dumper.py --token 12345678:ABCe2rPVteUWZ7wLeCqCb3CH3ilUY_fLabc

Дамп вниз от последнего сообщения

Для активного бота перебор вверх упирается в длинный участок удалённых (устаревших) старых id и сдаётся. Перебор вниз от самого свежего id гораздо продуктивнее. --down автоматически зондирует верхнюю границу (степени 10 вплоть до 10⁹) и начинает с самого высокого непустого найденного id:

./dumper.py --token TOKEN --down

Примечание. Telegram не хранит историю сообщений бота вечно. Эмпирически доступны только последние несколько сотен тысяч сообщений — в наших тестах активный бот отдавал примерно последние 500K сообщений, после чего messages.getMessages начинал возвращать только MessageEmpty для более старых id. Если ваш бот исторически обработал больше трафика, старая история просто исчезла на стороне сервера, и никакой флаг её не восстановит.

Если вы уже знаете недавний id сообщения (например, увиденный в реальном времени), можно пропустить зондирование и начать точно с него:

./dumper.py --token TOKEN --start-from-id 11922524

Режим прослушивания

Ничего не дампить; просто наблюдать за поступающим. При первом входящем сообщении скрипт предложит начать дамп вниз с этого id:

./dumper.py --token TOKEN --listen-only

Облегчённое перечисление пользователей (CSV, без медиа, без истории по чатам)

Полезно, когда нужен только список тех, кто общался с ботом — без zip-архивов, без jpeg-файлов, без *_history.txt по чатам.

./dumper.py --token TOKEN --down --users-csv --no-photos --no-media --no-history

Выход: <bot_id>/users.csv со столбцами id, username, first_name, last_name, phone, lang_code, bot, premium, verified, scam, fake.

Возобновление после сбоя / FloodWait

Перебор вниз печатает Requesting message ids X..Y ... для каждого пакета. Если запуск прерван, перезапустите с последней напечатанной нижней границы:

./dumper.py --token TOKEN --start-from-id <Y>

Настройка размера пакета

Меньшие пакеты → более быстрая обратная связь в логе и меньшее окно восстановления после FloodWait. Большие пакеты → меньше сетевых обменов при сканировании разреженных / удалённых диапазонов id. Значения вплоть до 1000 на практике работают нормально.

./dumper.py --token TOKEN --down --batch-size 50
./dumper.py --token TOKEN --down --batch-size 500
./dumper.py --token TOKEN --down --batch-size 1000

Другие флаги

Флаг	Действие
--lookahead N	После полностью пустого пакета продолжать сканирование ещё N пакетов, прежде чем сдаться. Полезно при разреженных id.
--no-photos	Пропустить скачивание фото профилей пользователей (аватарок).
--no-media	Пропустить скачивание фото и документов внутри сообщений; метаданные всё равно записываются в текстовую историю.
--no-history	Не записывать <chat_id>_history.txt по чатам. Комбинируйте с --users-csv для максимально лёгкого запуска.
--users-csv	Записывать пользователей в единый <bot_id>/users.csv вместо директорий <user_id>/<user_id>.json.
--tor	Маршрутизация через локальный Tor SOCKS5-прокси на 127.0.0.1:9050 (обход блокировки Telegram).

Запустите ./dumper.py --help для полного списка.

Известные на данный момент проблемы