tgscope

OSINT, скрапинг и архивирование Telegram.
Локальное веб-приложение, которое полностью работает на вашей машине и взаимодействует только с 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 для получения профиля, все исторические фото и сравнение с прошлым разом
Экспорт	Десять форматов, от простого CSV до хешированного пакета доказательств
Работает на	Node 18+, Python 3.12+, SQLite. Одна база данных, одна папка, без сервисов

Что он делает

Сбор

• Каждый канал, группа, тема форума и чат по всем авторизованным аккаунтам в одном выбираемом дереве с полным -100 id рядом с названием и значком аккаунта, который его видит
• Каждый диалог собирается под аккаунтом, который действительно может его читать, поэтому выбор, охватывающий два аккаунта, запускает один прогон на каждый аккаунт
• Сообщения с полными метаданными: просмотры, пересылки, реакции, даты редактирования, альбомы, опросы, гео, ссылки, цепочки ответов, авторы постов и источник пересылки каждого сообщения
• Группы-форумы разделяются по темам — собирайте отдельные темы, а не целые группы
• Медиа скачиваются параллельно и дедуплицируются по SHA-256 и file id Telegram, поэтому файл, пересланный в пять каналов, хранится один раз
• Возобновление с отметки (watermark) для каждого диалога; непрерывный режим перепроверяет через интервал
• Сохранённые коллекции повторно запускают выбор одним кликом

Исследование

• Поиск по номеру телефона, @username, id пользователя или ссылке t.me
• Био, флаги, точность последнего визита как индикатор приватности, общие чаты, личный канал
• Всё, что Telegram решит добровольно сообщить об аккаунте: месяц регистрации, страна, к которой относится номер телефона, когда человек последний раз менял имя или фото, его таймер автоудаления, имя, показываемое при ограниченных пересылках. Учтите, что обычно он не сообщает ничего из этого. Эти поля приходят вместе с антимошеннической панелью, которую Telegram показывает, когда вам пишет незнакомец, и возвращаются пустыми для профиля, который вы ищете напрямую, поэтому считайте их бонусом, а не тем, на что стоит рассчитывать
• Бизнес-аккаунты надёжно выдают улицу, координаты и часовой пояс
• Каждое видимое фото профиля, хешированное с помощью SHA-256 и перцептивного хеша, показано в виде галереи
• Перцептивные хеши сопоставляются между аккаунтами, поэтому одна и та же картинка на втором профиле всплывает
• Отправители сообщений записываются по мере сбора, поэтому имя в браузере — это рабочая ссылка на поиск, даже если у человека нет username; «Sync members» заполняет это для всего, что было собрано ранее
• Каждый поиск сохраняется в снимке и сравнивается: изменения username, изменения отображаемого имени, правки био, добавленные или удалённые фото, изменённая приватность

Экспорт

Формат	Что вы получаете
csv	Один файл на диалог
json / jsonl	Полные метаданные; JSONL передаётся построчно
xlsx	Листы для сообщений, медиа, участников и реакций
html	Автономный отчёт: статистика, активность, топ отправителей, источники пересылок, таблица с поиском
markdown	Тот же отчёт в виде текста
gexf / edges	Граф пересылок для Gephi и Maltego
sqlite	Автономная база данных только выбранных диалогов
bundle	ZIP с данными, медиа, манифестом хешей SHA-256 и журналом сбора

Требования

• Node.js 18+
• Python 3.12+
• Учётные данные API с my.telegram.org/apps

npm install создаёт окружение Python в server/.venv и устанавливает обе стороны.

Где что находится

Что	Где
Конфигурация	~/.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

Имена каталогов объединяют handle с полным id, не-ASCII заголовки транслитерируются, а имена файлов дополняются нулями, чтобы они сортировались в хронологическом порядке.

Ограничения частоты и безопасность аккаунта

Каждый вызов Telegram проходит через регулятор для каждого аккаунта с token bucket и откатом FloodWait, и каждое постраничное чтение — сообщения, диалоги, участники, фото профиля — пережидает флуд и возобновляется, а не завершает запуск с ошибкой. Три профиля:

Профиль	Воркеры медиа	Интервал между запросами	Ожидания, поглощаемые молча
stealth	1	1.6 с	до 180 с
balanced	4	0.35 с	до 90 с
fast	8	нет	до 45 с

Более длительные ожидания объявляются в журнале активности и пережидаются; двенадцать подряд при одном чтении приводят к отказу и сообщению об этом.

Поддерживается несколько аккаунтов. Отметьте один как burner в настройках, и поиск по телефону будет выполняться на нём автоматически, поскольку это единственная рискованная операция:

Поиск по телефону на мгновение импортирует номер как контакт и снова удаляет его. Если у владельца уже сохранён ваш номер, он может увидеть уведомление «joined Telegram». tgscope спрашивает об этом заранее, каждый раз, а карточка профиля записывает, какой аккаунт использовался.

Разработка

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

Бэкенд — это FastAPI поверх ядра Telethon, протестированный на фейковом клиенте Telethon: скрапер, экспортёры, структура медиафайлов и каждая миграция схемы. Тесты фронтенда покрывают чистую логику браузера, арифметику периодов, разбиение гистограмм по корзинам и форматирование чисел и временных меток, а также рендерят каждый экран дважды — пустым и заполненным.

scripts/demo/ пересоздаёт docs/preview.gif из сгенерированных фейковых данных. Ему нужны chromium и ffmpeg, он ничего не трогает в вашем реальном рабочем пространстве и не является частью приложения.

Исходный код не содержит комментариев — смысл несут именование и структура, и это проверяется тестом.

Правовые аспекты