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 기반으로 제작되었습니다.

수집	여러 계정에 걸쳐 채널, 그룹, 포럼 토픽을 미디어, 중복 제거, 이어받기 기능과 함께 수집
조사	전화번호, @username, id 또는 t.me 링크로 프로필 조회, 모든 과거 사진, 지난번 이후 변경 사항 diff
내보내기	일반 CSV부터 해시 검증된 증거 번들까지 10가지 형식
실행 환경	Node 18+, Python 3.12+, SQLite. 데이터베이스 하나, 폴더 하나, 서비스 없음

주요 기능

수집

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

조사

• 전화번호, @username, 사용자 id 또는 t.me 링크로 조회
• 바이오, 플래그, 프라이버시 지표로서의 마지막 접속 정밀도, 공통 채팅, 개인 채널
• Telegram이 계정에 대해 자발적으로 제공하는 모든 정보: 등록 월, 전화번호가 속한 국가, 마지막으로 이름을 바꾼 시점이나 사진을 교체한 시점, 자동 삭제 타이머, 제한된 포워드에 표시되는 이름. 다만 보통은 아무것도 제공하지 않는다는 점을 유의해야 함. 해당 필드들은 낯선 사람이 메시지를 보낼 때 Telegram이 표시하는 안티 스캠 패널에 함께 제공되며, 직접 조회한 프로필에서는 빈 값으로 돌아오므로, 이를 계획의 근거로 삼기보다는 보너스로 취급할 것
• 비즈니스 계정은 도로명 주소, 좌표, 시간대를 안정적으로 제공
• 모든 표시되는 프로필 사진을 SHA-256과 지각적 해시로 해시하여 갤러리로 표시
• 지각적 해시가 계정 간에 매칭되므로, 두 번째 프로필에 있는 동일한 사진이 드러남
• 메시지 발신자는 스크래핑 시점에 기록되므로, 브라우저에 표시된 이름은 해당 인물에게 사용자명이 없더라도 조회로 이어지는 작동하는 링크가 됨. "Sync members"는 이전에 수집된 항목에 대해 이를 채워줌
• 모든 조회는 스냅샷으로 저장되고 diff됨: 사용자명 변경, 표시 이름 변경, 바이오 수정, 사진 추가 또는 제거, 프라이버시 변경

내보내기

형식	결과물
csv	대화별 파일 하나
json / jsonl	전체 메타데이터; JSONL은 행 단위로 스트리밍
xlsx	메시지, 미디어, 참여자, 반응 시트
html	독립형 보고서: 통계, 활동, 상위 발신자, 포워드 출처, 검색 가능한 표
markdown	동일한 보고서를 텍스트로
gexf / edges	Gephi 및 Maltego용 포워드 그래프
sqlite	선택한 대화만 담은 독립형 데이터베이스
bundle	데이터, 미디어, SHA-256 해시 매니페스트, 수집 로그를 담은 ZIP

요구 사항

• Node.js 18+
• Python 3.12+
• my.telegram.org/apps에서 발급받은 API 자격 증명

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

파일 위치

항목	위치
설정	~/.config/tgscope/config.json (모드 600)
데이터베이스	~/.local/share/tgscope/tgscope.db (WAL, FTS5)
미디어	~/.local/share/tgscope/media/
내보내기	~/.local/share/tgscope/exports/<timestamp>-<label>/

하나의 데이터베이스가 모든 것을 담고 있으며, 이것이 대화 간 검색, 공유 사용자 테이블, 미디어 중복 제거 및 포워드 그래프를 가능하게 합니다.

미디어 레이아웃

파일은 대화 유형, 그다음 대화, 그다음 포럼 주제, 그다음 미디어 종류 순으로 분류됩니다:

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

디렉터리 이름은 핸들에 전체 id를 결합한 형태이며, 비ASCII 제목은 음역되고, 파일 이름은 시간순으로 정렬되도록 0으로 채워집니다.

속도 제한 및 계정 안전

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

프로필	미디어 워커	요청 간격	조용히 흡수되는 대기 시간
stealth	1	1.6 s	최대 180 s
balanced	4	0.35 s	최대 90 s
fast	8	없음	최대 45 s

더 긴 대기는 활동 로그에 알림으로 표시되고 대기한 후 진행됩니다. 한 번의 읽기에서 연속 열두 번 발생하면 포기하고 보고합니다.

여러 계정이 지원됩니다. 설정에서 하나를 버너(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 라이선스.