tgscope

Telegram OSINT, 스크래핑 및 아카이빙.
사용자 컴퓨터에서 완전히 실행되며 오직 Telegram과만 통신하는 로컬 웹 앱.

npm install
npm start

그런 다음 **http://127.0.0.1:5173**을 여세요. 첫 실행 시 API 자격 증명, QR 로그인, 다이얼로그 로딩 과정을 안내합니다. 통신하는 서버는 Telegram이 유일합니다. 만들 계정도, 텔레메트리도, 중간에 끼어드는 서비스도 없습니다. 수집한 것은 사용자가 소유한 SQLite 파일에 그대로 남습니다.

telegram-scraper, telescope, Harrier의 후속작이며 Telethon 1.44 기반입니다.

하는 일

수집(Collect)

• 로그인된 모든 계정의 모든 채널, 그룹, 포럼 주제, 채팅을 하나의 선택 가능한 트리로 표시. 이름 옆에는 전체 -100 id와 해당 항목이 보이는 계정의 배지가 함께 표시됨
• 각 다이얼로그는 실제로 읽을 수 있는 계정 아래에 수집되므로, 두 계정에 걸친 선택은 계정당 한 번의 실행(run)으로 시작됨
• 전체 메타데이터를 포함한 메시지: 조회수, 전달(forward) 수, 반응, 수정 날짜, 앨범, 투표, 지리 정보, 링크, 답글 체인, 게시자, 모든 메시지의 전달 출처
• 포럼 그룹은 주제별로 분리 — 전체 그룹 대신 개별 주제만 수집
• 미디어는 병렬로 다운로드되고 SHA-256 및 Telegram 파일 id로 중복 제거되므로, 다섯 개 채널로 전달된 파일도 한 번만 저장됨
• 다이얼로그별 워터마크부터 재개; 연속 모드는 일정 간격으로 다시 확인함
• 저장된 컬렉션은 클릭 한 번으로 선택 항목을 다시 실행함

조사(Investigate)

• 전화번호, @username, 사용자 id 또는 t.me 링크 조회
• 소개(bio), 플래그, 프라이버시 지표로서의 마지막 접속 정밀도, 공통 채팅, 개인 채널
• Telegram이 해당 계정에 대해 공개하기로 선택한 모든 정보: 등록된 달, 전화번호가 속한 국가, 사용자가 마지막으로 이름을 바꾸거나 사진을 교체한 시점, 자동 삭제 타이머, 제한된 전달(restricted forwards)에 표시되는 이름. 대개 아무것도 공개하지 않는다는 점을 알아두세요. 이러한 필드는 낯선 사람이 메시지를 보낼 때 Telegram이 표시하는 안티 스캠 패널에 따라오는 것이며, 직접 조회하는 프로필에서는 빈 값으로 반환됩니다. 따라서 계획의 대상이 아니라 보너스로 취급하세요
• 비즈니스 계정은 도로명 주소, 좌표, 시간대를 확실히 제공함
• 모든 공개된 프로필 사진을 SHA-256 및 지각 해시(perceptual hash)로 해싱해 갤러리로 표시
• 지각 해시는 계정 간에 매칭되므로, 다른 프로필에 있는 동일한 사진도 드러남
• 메시지 발신자는 스크래핑할 때 기록되므로, 브라우저의 이름은 사용자명이 없는 사람이라도 조회로 이어지는 실제 링크가 됨. "Sync members"는 이전에 수집된 모든 항목에 대해 이를 채워 넣음
• 모든 조회는 스냅샷 및 diff 처리됨: 사용자명 변경, 표시 이름 변경, bio 수정, 사진 추가/제거, 프라이버시 변경

내보내기(Export)

요구 사항

• Node.js 18+
• Python 3.12+
• my.telegram.org/apps의 API 자격 증명

npm install은 server/.venv 아래에 Python 환경을 만들고 양쪽 모두를 설치합니다.

파일 위치

하나의 데이터베이스가 모든 것을 담기 때문에 다이얼로그 간 검색, 공유 사용자 테이블, 미디어 중복 제거, 전달 그래프가 가능합니다.

미디어 구조

파일은 다이얼로그 유형 → 다이얼로그 → 포럼 주제 → 미디어 종류 순으로 정리됩니다:

media/
├── channels/technews_-1002116176890/
│   ├── photos/00004711-8001-conference-slides.jpg
│   └── documents/00004802-8210-quarterly-report.pdf
├── groups/pythondev_-1001597139842/
│   ├── general/photos/…
│   └── help/voice/00000004-9004-voice.ogg
└── profiles/123456789/000-5544332211.jpg

디렉터리 이름은 핸들과 전체 id를 결합하며, 비ASCII 제목은 음역(transliteration)되고, 파일 이름은 연대순 정렬을 위해 0으로 패딩됩니다.

속도 제한 및 계정 안전

모든 Telegram 호출은 토큰 버킷과 FloodWait 백오프를 갖춘 계정별 거버너(governor)를 거치며, 모든 페이지 읽기(메시지, 다이얼로그, 멤버, 프로필 사진)는 플러드(flood) 대기를 기다렸다가 실행을 실패시키지 않고 재개합니다. 세 가지 프로필:

더 긴 대기는 활동 로그에 공지된 뒤 기다립니다. 한 번의 읽기에서 12회 연속 발생하면 포기하고 이를 보고합니다.

여러 계정이 지원됩니다. 설정에서 하나를 버너(burner) 로 지정하면 전화번호 조회가 자동으로 그 계정에서 실행됩니다. 이것이 유일한 위험한 작업이기 때문입니다:

전화번호 조회는 그 번호를 잠시 연락처로 가져왔다가 다시 삭제합니다. 상대방이 이미 내 번호를 저장해 두었다면 "Telegram 가입" 알림을 볼 수 있습니다. tgscope는 매번 먼저 확인을 거치며, 프로필 카드에는 어떤 계정이 사용되었는지 기록됩니다.

개발

npm test                    # 92 backend and 42 frontend tests, no network needed
npm run build               # production bundle of the client

백엔드는 Telethon 코어 위의 FastAPI이며, 가짜 Telethon 클라이언트로 테스트됩니다: 스크래퍼, 내보내기 도구, 미디어 구조, 모든 스키마 마이그레이션. 프론트엔드 테스트는 브라우저 뒤의 순수 로직, 기간 연산, 히스토그램 버케팅, 숫자 및 타임스탬프 형식 지정을 다루며, 모든 화면을 두 번씩(한 번은 빈 상태, 한 번은 데이터가 채워진 상태) 렌더링합니다.

scripts/demo/는 시드된 가짜 데이터로 docs/preview.gif를 재생성합니다. chromium과 ffmpeg가 필요하며, 실제 작업 공간에는 아무것도 건드리지 않고 앱의 일부도 아닙니다.

소스에는 주석이 없습니다 — 의미는 명명과 구조가 전달하며, 테스트가 이를 강제합니다.

법적 고지

연구, 저널리즘 및 승인된 조사를 위한 도구입니다. Telethon을 통해 공식 Telegram API를 사용하며 계정이 이미 볼 수 있는 것만 읽습니다 — 누구의 프라이버시 설정도 우회하지 않습니다. 괴롭힘이나 스토킹에 사용하지 말고, Telegram의 서비스 약관을 준수하며, 자신에게 적용되는 데이터 보호법을 유의하세요.

MIT 라이선스.