
Telegram 봇을 덤프합니다. Telegram 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...
200개 단위의 배치로 id 1..∞를 위쪽으로 순회하며 모든 메시지, 모든 미디어, 모든 사용자 프로필 사진을 다운로드합니다. 기본적으로 덤퍼는 덤프가 끝난 후에도 새로 들어오는 메시지를 계속 수신합니다. 기록 덤프 직후에 종료하려면(스크립트와 cron 작업에 이상적) --no-listen을 전달하세요.
./dumper.py --token 12345678:ABCe2rPVteUWZ7wLeCqCb3CH3ilUY_fLabc
활성 봇의 경우 위로 탐색하면 삭제(만료)된 오래된 id의 긴 구간에 부딪혀 포기하게 됩니다. 가장 최근 id에서 아래로 탐색하는 것이 훨씬 더 생산적입니다. --down은 상한을 자동으로 탐색하며(10의 거듭제곱으로 최대 10⁹까지) 발견한 가장 높은 비어 있지 않은 id에서 시작합니다:
./dumper.py --token TOKEN --down
참고. Telegram은 봇 메시지 기록을 영구적으로 보관하지 않습니다. 경험적으로 볼 때 마지막 수십만 개의 메시지만 접근 가능하며, 저희 테스트에서는 트래픽이 많은 봇이 약 마지막 500K 개의 메시지를 노출한 후
messages.getMessages가 더 오래된 id에 대해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
출력: id, username, first_name, last_name, phone, lang_code, bot, premium, verified, scam, fake 열을 가진 <bot_id>/users.csv.
하향 탐색은 다음 배치 경계를 <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
또는 --down을 사용하면 이전 id의 공백에 훨씬 덜 영향을 받습니다.
그룹 채팅(기본 그룹, 슈퍼그룹)의 기록은 덤프되지 않았습니다.
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