
Telegramボットをダンプします。Telegram Webのように閲覧できます。Webインターフェースを備えたフォレンジックCLIツール
Telegramボットのあらゆる情報を簡単にダンプします。
入力: ボットトークンのみ。
出力: ボット名と情報、すべてのチャットのテキスト履歴とメディア、ボットのユーザー情報と写真。
これはPython実装です。
📖 完全なドキュメント: https://telegram-bot-dumper.readthedocs.io
ダンプ用のTelegram Web風ブラウザUI: チャット一覧、インラインメディア付きの完全なメッセージ履歴、写真カルーセル付きのユーザープロフィール、そしてすべての会話を一度に横断検索できるグローバル検索。ライブモードにも対応: バックグラウンドでダンパーを実行し、新しいメッセージをリアルタイムでブラウザにストリーミングします。
会話を開いてDownload chatを選択すると、その履歴、メディア、写真をdump_<bot_id>_<chat_id>.zipとして保存できます。アーカイブは<bot_id>/<chat_id>/のディレクトリ構造を維持し、他のチャットやボットレベルのファイルは含まれません。
ユースケース — 漏洩したボットトークンのペネトレーションテスト。 Telegramのボットトークンは、モバイル/デスクトップアプリへのハードコード、リポジトリへのコミット、CIログ、設定ファイル、クライアントサイドのバンドルなど、エンゲージメント中に頻繁に見つかります。トークン単体では低深刻度の所見に見えますが、ここに読み込むことで実際の影響範囲が明らかになります。内部ボット(サポートデスク、IT/DevOpsヘルパー、AIアシスタント)の場合、それは従業員とのすべての会話、つまり内部ホスト名、VPNプロファイル、認証情報、インフラの詳細であり、閲覧・検索可能であるため、影響範囲を特定し、レポートに所見の証拠として記載できます。

docker run --rm -p 127.0.0.1:8010:8010 -v "$PWD:/data" soxoj/telegram-bot-dumper-web
docker compose up --build # builds and serves on http://127.0.0.1:8010
pip install -r requirements.txt
python webapp/server.py # serves dumps from the repository folder on :8010
./run-viewer.sh # live mode + dumping new bots, API_ID/API_HASH from .env
http://127.0.0.1:8010 を開き、ボットトークンを貼り付けてそのダンプを開きます。トークンはそのダンプの bot.json に保存されているものと一致している必要があります。読み取り専用の閲覧には API 認証情報は不要です。ライブモードではさらに、my.telegram.org から取得した API_ID/API_HASH を環境変数経由で渡す必要があります — イメージに埋め込まないでください:
# one-off container
docker run --rm -p 127.0.0.1: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)を上書きします。
デフォルトでは、ビューアはすでにダンプが存在するボットのみを開きます。--allow-new-dumps(Docker では ALLOW_NEW_DUMPS=1)を付けて起動すると、まだダンプのないトークンが Telegram で確認され、そのフォルダと bot.json が取得され、ライブモードで履歴全体がブラウザへ直接ダンプされます。これには API_ID/API_HASH が必要です。
このページを開けるユーザーは誰でも、あなたの API_ID の下にある任意のボットをサーバーにダンプさせることができるため、ビューアは非ループバックの HOST でこのフラグを有効にした状態での起動を拒否します。Docker ではコンテナ内の HOST は常に 0.0.0.0 になるため、ALLOW_PUBLIC=1(--allow-public)を追加し、ポートは自身でループバックに限定してください:
docker run --rm -p 127.0.0.1:8010:8010 -v "$PWD:/data" \
-e API_ID=123456 -e API_HASH=abc... -e ALLOW_NEW_DUMPS=1 -e ALLOW_PUBLIC=1 \
soxoj/telegram-bot-dumper-web
--down / --start-from-id)にたどって、ボットのメッセージをメディアコンテンツとともにダンプします。--listen-only):新しいメッセージをリアルタイムで受信し、最初に観測したIDから履歴を下方向にダンプすることを提案します。[from:USER][group:CHAT] のタグが付きます。送信するボットのDMには [to:USER] のタグが付きます。--listen-only はそれらをリアルタイムでダンプします。プライバシーモードが有効(デフォルト)の場合、ボットはコマンド、メンション、返信のみを参照します。requirements.txt を参照)API_ID と API_HASH を取得するためにTelegramアプリケーションを登録する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 件のメッセージを公開しており、それより古い id に対しては
messages.getMessagesがMessageEmptyのみを返すようになりました。ボットが歴史的にそれ以上のトラフィックを処理してきた場合、古い履歴はサーバー側で単に失われており、どのフラグでも復元できません。
直近のメッセージ id をすでに知っている場合(例えばリアルタイムで見たもの)、プローブをスキップして正確にその id から開始できます:
./dumper.py --token TOKEN --start-from-id 11922524
何もダンプせず、受信したものを見るだけです。最初の受信メッセージで、スクリプトはその id から下方ダンプを開始するかどうかを提案します:
./dumper.py --token TOKEN --listen-only
ボットと会話した人の名簿だけが必要な場合に便利です — 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。
下方走査は次のバッチ境界を <bot_id>/last_message_id.txt に保存します。
実行が中断された場合は、再度プローブせずに既存のダンプフォルダ内で続行します:
./dumper.py --token TOKEN --resume
元の実行時と同じ --output ディレクトリを、設定されていた場合は使用します。保存されたチャット履歴とセッションファイルは保持されます。チェックポイントが存在しないか無効な場合は、接続前にエラーが発生します。--resume は --listen-only や --start-from-id と組み合わせることはできません。これは下方への走査を意味します。
代わりに開始点を手動で選択するには、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 を実行して確認してください。
履歴が完全にダンプされる前にボットが終了する。
ユーザーによって一部のメッセージが削除されている場合、バッチが完全に空で返ってくることがあり、スクリプトが早すぎる段階で停止する可能性があります。さらに、ボットが非常に大量のトラフィックを処理している場合、古いメッセージは Telegram のサーバーから単に返されなくなります — それらは削除済みであり、どのフラグでも復元できません。疎ではあるが存在する履歴については、--lookahead を増やして空の区間を越えてスキャンを続けてください:
# check additionally 5*200 = 1000 ids
./dumper.py --token TOKEN --lookahead 5
あるいは、古いIDの欠落の影響をはるかに受けにくい --down を使用してください。
グループチャット(基本グループ、スーパーグループ)の履歴はダンプされませんでした。
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