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.

Что он делает

Сбор

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

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

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

Экспорт

Требования

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

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

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

Одна база данных хранит всё, что и делает возможным поиск по всем диалогам, общую таблицу пользователей, дедупликацию медиа и граф репостов.

Структура медиа

Файлы раскладываются по типу диалога, затем по диалогу, затем по теме форума, затем по типу медиа:

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 заголовки транслитерируются, а имена файлов дополняются нулями, чтобы они сортировались хронологически.

Лимиты и безопасность аккаунта

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

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

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

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

Разработка

npm test                    # 92 бэкенд- и 42 фронтенд-теста, сеть не нужна
npm run build               # production-сборка клиента

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

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

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

Правовая информация

Для исследований, журналистики и авторизованных расследований. Используется официальный Telegram API через Telethon, и читается только то, что ваш аккаунт уже может видеть — он не обходит ничьи настройки приватности. Не используйте его для преследования или сталкинга, соблюдайте условия использования Telegram и учитывайте применимое к вам законодательство о защите данных.

Лицензия MIT.