telegram-bot-dumper

Telegramボットのあらゆるデータを簡単にダンプできます。

入力: ボットトークンのみ。

出力: ボット名と情報、すべてのチャットのテキスト履歴とメディア、ボットのユーザー情報と写真。

---

これはPython実装です。

🚀 高速なGolang版（ScBoln作）。

Webビューア

ダンプ用のTelegram-Web風ブラウザUI: チャット一覧、インラインメディア付きの完全なメッセージ履歴、写真カルーセル付きのユーザープロフィール、すべての会話を一度に横断検索できるグローバル検索。ライブモード対応: バックグラウンドでダンパーを実行し、新着メッセージをリアルタイムでブラウザにストリーミングします。

ユースケース — 漏洩したボットトークンのペネトレーションテスト。 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認証情報も不要です。ライブモードではさらにmy.telegram.orgのAPI_ID/API_HASHが必要で、環境変数経由で渡します — イメージに焼き込まないでください:

# 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]のタグが付きます。送信ボットDMには[to:USER]のタグが付きます。
• グループ監視: ボットがグループ/スーパーグループに追加されており、かつプライバシーモードが無効な場合、ボットはコマンドと返信だけでなくすべてのグループメッセージを受信し、--listen-onlyがそれらをリアルタイムでダンプします。プライバシーモードが有効（デフォルト）な場合、ボットはコマンド、メンション、返信のみを認識します。

要件

• Python >= 3.6
• Telethon（固定バージョンはrequirements.txtを参照）
• API_IDとAPI_HASHを取得するためにTelegramアプリケーションを登録する

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はボットのメッセージ履歴を永久には保持しません。経験的に、アクセス可能なのは直近の数十万件のメッセージのみです — 我々のテストでは、ビジーなボットはmessages.getMessagesが古いIDに対してMessageEmptyのみを返し始めるまで、およそ直近500K件のメッセージを公開していました。ボットが歴史的にそれ以上のトラフィックを処理していた場合、古い履歴はサーバー側で単に消えており、どのフラグでも復元できません。

最近のメッセージ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	ユーザーを<user_id>/<user_id>.jsonディレクトリではなく、単一の<bot_id>/users.csvに書き込みます。
--tor	127.0.0.1:9050のローカルTor SOCKS5プロキシ経由でルーティングします（Telegramブロックの回避）。

完全なリストは./dumper.py --helpを実行してください。

現在判明している問題

1. 履歴が完全にダンプされる前にボットが終了する。 一部のメッセージがユーザーによって削除されている場合、バッチが完全に空で返り、スクリプトが早すぎるタイミングで停止することがあります。さらに、ボットが非常に大量のトラフィックを処理していた場合、古いメッセージはTelegramのサーバーから単に返されなくなります — それらは削除済みで、どのフラグでも復元できません。疎だが存在する履歴については、--lookaheadを増やして空の区間を越えてスキャンを続けます:

   # check additionally 5*200 = 1000 ids
   ./dumper.py --token TOKEN --lookahead 5
   

   または単に--downを使用してください。古いIDのギャップの影響をはるかに受けにくいです。

2. グループチャット（基本グループ、スーパーグループ）の履歴がダンプされなかった。 messages.getMessagesはボットのPM履歴のみを返します。スーパーグループの履歴にはチャンネルごとの呼び出しが必要で、通常ボットは実行できません。グループメッセージは、グループプライバシーがオフの場合（機能を参照）、--listen-onlyモードでライブにキャプチャされます。

テスト

オフラインユニットテスト（ネットワークなし、トークンなし）:

pip install -r test-requirements.txt
pytest tests/ --ignore=tests/bot_test.py

実際のボットに対する統合テスト（動作するボットトークンが必要）:

TEST_TOKEN=12345678:... pytest tests/bot_test.py

トークン漏洩

Dorksの例: telepot.bot