telegram-bot-dumper

모든 Telegram 봇 관련 데이터를 손쉽게 덤프합니다.

입력: 봇 토큰만 필요합니다.

출력: 봇 이름 및 정보, 모든 채팅 텍스트 기록 및 미디어, 봇의 사용자 정보 및 사진.

---

Python 구현체입니다.

🚀 ScBoln이 만든 빠른 Golang 버전.

웹 뷰어

덤프를 위한 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은 봇 메시지 기록을 영구적으로 보관하지 않습니다. 경험적으로 마지막 수십만 개의 메시지만 접근 가능합니다 — 테스트에서 바쁜 봇은 약 마지막 500K개의 메시지를 노출한 후 messages.getMessages가 오래된 ID에 대해 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	사용자를 <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
   

   또는 오래된 ID의 공백에 훨씬 덜 영향을 받는 --down을 사용하세요.

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