Справочник / Безопасность и проект
Архитектура TgWitness: сборщик, журнал и API
Компоненты системы: сборщик, панель управления, журнал, рабочие процессы и модуль «witness», а также схема передачи данных между ними.
Один процесс на языке Python обеспечивает работу панели FastAPI и любого количества изолированных рабочих пространств, каждое из которых содержит клиент с учетной записью пользователя Telegram. В базе данных SQLite хранится подписанный журнал событий, доступный только для добавления, а также изменяемые операционные настройки. В зашифрованном хранилище находятся учетные данные API, объект StringSession и ключ подписи. Фронтенд представляет собой простой пакет HTML/CSS/JavaScript: не требуется сборка Node, использование CDN или загрузка фронтенда во время выполнения.
Дополнительные записывающие модули для браузера и AyuGram работают в отдельных процессах или контейнерах.
Данный tgwitness_capture пакет содержит собственный формат событий, ключи, артефакты,
API контрольных точек, независимый свидетель и автономный верификатор. Он входит в состав основного
пакета и также может быть установлен отдельно из addons/capture, без импорта
коллектора. Главная панель capture_api.py и capture_connections.py
предоставляют доступные только администратору средства управления в пределах рабочей области под /api/capture;
токены подключения хранятся в зашифрованном хранилище. Ни один рекордер или исходящий запрос не запускается
из основного процесса. Каждая явная команда проверяет новый челлендж по отношению к
закреплённому ключу рекордера. Экспорты проверяются перед загрузкой и сохраняют свою исходную
подпись; они не превращаются в события сообщений Telegram. Сеансы сбора данных и прокси-
маршруты остаются у каждого клиента. См. англоязычное руководство по независимому
сбору данных для получения информации о развёртывании и границах доверия.
| Модуль | Ответственность |
|---|---|
| collector.py | Авторизация, выбор диалога, обновления, моментальные снимки, очередь мультимедиа, мониторинг соединения |
| interactions.py / telegram_client.py | Четко описанные действия панели управления, подписанные подтверждения, постоянные идентификаторы запросов и политика повторных попыток обратного вызова/присоединения на уровне конкретной задачи |
| message_content.py | Наглядное сравнение сообщений без учета метаданных транспортного уровня |
| workers.py | Дождитесь завершения работы процессов экспорта файлов перед очисткой при отмене |
| distributed_export.py / distributed_pages.py | Параллельные задания в чатах, резервирование по учетным записям, подписанные контрольные точки и очистка после проверки архива |
| distributed_takeout.py / export_timing.py | Возможность возобновления сеансов Takeout и время запуска или возобновления каждого сеанса |
| store.py | Транзакции WAL, упорядоченная цепочка событий, фильтры запросов, операционные настройки |
| fulltext.py | Производный полнотекстовый индекс (формы слов, BM25), привязанный к заголовку подписанного журнала; никогда не экспортируется |
| security.py | Создание частных файлов, зашифрованное хранилище, подпись с использованием алгоритма Ed25519, блокировка одного процесса |
| evidence.py | Экспорт полного журнала, производные файлы, контрольные точки, проверка вложений |
| verify.py | Автономный верификатор, доступный только для чтения (stdlib + криптография): архивы, охват, журналы свидетелей и сообщения в каналах, файлы профилей |
| app.py | Аутентифицированный API, жизненный цикл, проверка запросов, статическая панель |
| profiles.py | Средства сбора данных из нескольких учетных записей, механизм управления общим доступом, жизненный цикл на уровне рабочей среды |
| access.py | Гранты с ограниченным охватом, проверка разрешений, ограничения по IP-адресам, ограничения на количество сеансов и консоль администратора |
| proxy_catalog.py | Снимки общедоступных каналов, проверки транспортных протоколов, общий пул прокси-серверов и отбор на основе работоспособности |
| provenance.py | Подписанные измерения идентичности, кода и зависимостей, выполняемые в режиме сбора данных |
| network.py | Проверенные маршруты для каждой рабочей среды; отредактированные данные о статусе и доказательствах; варианты передачи данных через Telethon |
| sessions.py | Офлайн-конвертация проверенных схем баз данных Telethon в формате SQLite в режим «только для чтения» |
| account_import.py | Обнаружение и нормализация поддерживаемых файлов учетных записей и JSON-файлов в памяти |
| tdata.py | Ограниченный современный считыватель ZIP-файлов TData, проверка контрольных сумм и дешифрования, без извлечения данных |
| doctor.py | Проверка готовности на локальном устройстве без сбора данных, входа в систему или установки пакетов |
| download.py | Загрузка аутентифицированных потоковых данных с ограниченным объёмом чтения и без перезаписи |
| monitoring.py | Проверенные политики событий для каждого рабочего пространства и правила для вложений по типам, общие для обработчиков, статусов и подписанных подтверждений получения |
| scope.py | Область мониторинга (выбранные чаты, папка Telegram, весь аккаунт), типы источников, исключения, уровни повторной проверки |
| dossier.py | Профили участников по каждому чату, сформированные на основе сохраненных записей: факты со ссылками на записи, SHA-256/pHash аватаров, извлечение упоминаний |
| witness_api.py | Токены свидетелей, доступные только для чтения, и подписанная заголовочная часть журнала, которую они могут получить |
| witness.py | Процесс независимого фиксирования: собственный ключ и журнал, проверка подлинности, подписанные сообщения в каналах, экспорт |
| alerts.py | Уведомления Apprise и список уведомлений на панели |
| logging_config.py | Ведение журнала консоли и ротация диагностических данных сервера при запуске без оконного интерфейса |
| static/ | Адаптивный интерфейс, локальный шлюз доступа, фильтры, подробная информация, экспорт данных, настройка учетной записи |
| demo.py | Чётко обозначенный синтетический журнал, изолированный от реального массива данных |
Обработчики наблюдения регистрируются до установления соединения. Сбор данных в режиме реального времени ограничивается идентификацией активного клиента, явным состоянием работы, включенными источниками или областью наблюдения (режимы «папка» или «весь аккаунт» добавляют новый чат в качестве источника при его первом обновлении), а также политикой обработки событий. Отклоненные и замененные клиенты не могут передавать обновления в режиме реального времени. Необработанные реакции и обновления членства сохраняют ограничения видимости. Содержимое входящего сообщения и его задание на сохранение в постоянном носителе фиксируются одновременно. Задания сохраняют исходный дескриптор TL и привязывают его хеш к подписанному наблюдению за сообщением. Семантика отправителя, редактора и удаляющего лица разделена.
Каждая рабочая область поддерживает одну учетную запись и имеет собственный каталог и идентификатор для подписи. Главная рабочая область по-прежнему находится в корневом каталоге в целях обеспечения совместимости; дополнительные рабочие области размещаются в profiles/<id>/. Один токен-носитель управляет всей установкой; рабочие области не являются отдельными субъектами авторизации. Блокировки процессов защищают каталоги; блокировки базы данных обеспечивают последовательную вставку событий. Каждое добавление синхронно фиксируется в журнале WAL базы данных SQLite в режиме FULL. Триггеры обновления/удаления событий предотвращают обычные изменения со стороны приложения; администраторы файловой системы остаются в пределах зоны доверия.
Авторизация API осуществляется с помощью токена bearer. Операции входа в систему сериализуются и ограничены по времени. При загрузке данных в аккаунт используются специальные ограничения: 12 MiB для кодированного тела и 8 MiB для декодированного файла; для обычных запросов API сохраняется ограничение 16 KiB. Преобразование выполняется в рабочем потоке, сохраняет загрузки в памяти и возвращает нормализованные входные данные в авторизованный браузер. Вход по QR-коду имеет кандидат на каждое рабочее пространство, кратковременный идентификатор, задачу ожидания и явную отмену. Только принятая авторизация становится активным клиентом. Telegram FloodWait возвращается со значением Retry-After; учетные данные и исходные сообщения об ошибках RPC не раскрываются в ошибках API. Экспорт журналов выполняется вне асинхронного цикла событий и сериализуется для каждого рабочего пространства. Они передают стабильный снимк чтения наряду с продолжающейся записью в WAL. Задания по сбору данных из чатов могут выполняться одновременно на разных учётных записях; каждая учётная запись остаётся зарезервированной до тех пор, пока её задание не завершится. Приостановленное или завершившееся с ошибкой задание сохраняет свои контрольные точки. Успешная проверка архива позволяет очистить его рабочие файлы, оставив ZIP-архив, подписанный план и статус. Коллекторы рабочих пространств используют общий процесс/цикл событий.
Текущие моментальные снимки истории и обновления в режиме реального времени могут пересекаться. Оба представляют собой отдельные наблюдения, помеченные с указанием источника; дубликаты не сворачиваются автоматически. Не реализовано никаких выводов на основании отсутствующих идентификаторов, сфабрикованного удалённого текста, принудительного перечисления участников или автоматического вступления в группу .
Практическое описание для оператора: как работает сбор данных и аккаунты и форматы сессий.
Настройки сети хранятся в зашифрованном хранилище. Применение маршрута приводит к закрытию старых клиентов и отмене незавершённых попыток входа; последующие подключения используют этот маршрут без прямого резервного перехода. При новой установке с использованием внешнего ключа для каждого рабочего пространства генерируется ключ Fernet с помощью алгоритма HKDF-SHA256 на основе файла мастер-ключа и сохраненного случайного солевого значения. Это обеспечивает защиту конфиденциальных данных отдельно от каталога данных, а не содержимого журнала или мультимедиа в виде открытого текста.
Местный демо-доступ использует отдельно сгенерированные процессуальные возможности, но ни в коем случае не настроенный токен панели. Для выдачи и принятия требуется явный демо-режим, синтетический корневой домен без дополнительных рабочих пространств или авторизованной сессии, пир/хост с обратной связью, отсутствие прокси- заголовков переадресации и отсутствие междоменных запросов браузера. Активные API сохраняют аутентификацию по носителю и отклоняют изменения в сборе данных в демонстрационном режиме.