Документация / 02
Экспорт Telegram через GitHub Actions
Выберите Takeout, выгрузку через обычный API или журнал чата на временном раннере GitHub.
Полный справочник
TgWitness / Документация / Папка · Независимый сбор данных
Предварительная версия доступна в main. Форк запускает закреплённый переиспользуемый
workflow из phishdestroy/TgWitness. Workflow выгружает аккаунт, выбранные чаты или журнал
событий одного чата через вновь созданную сессию Telegram, создаёт аттестацию ZIP с
доказательствами или манифеста многочастной доставки и загружает только
передаваемые пакеты, зашифрованные для получателя. Обычная панель администрирования наружу не
открывается.
Выберите client=official_web, чтобы запустить свидетеля на официальном клиенте с защищёнными элементами управления Telegram Web и видеозаписью. Для него нужен собственный вышестоящий (upstream) прокси, и он наблюдает один отображаемый чат. Вариант по умолчанию client=api сохраняет режимы выгрузки всего аккаунта, описанные ниже.
Верификатор сверяет архив с его аттестацией GitHub, утверждёнными коммитами workflow и коллектора, а также с подписанным журналом и хешами вложений. Процесс сбора использует закреплённый код исходного репозитория и новое хранилище. Проверяющий может изучить этот код и сверить доставленный архив с зафиксированным запуском.
На этой странице
Порядок работы#
Помощник объясняет пять этапов и позволяет попробовать подмену сообщения или коллектора на демонстрационных данных. Кнопка Начать сбор данных открывает мастер.
- Выберите Сбор данных с помощью GitHub Actions (предварительный просмотр) на главной
странице проекта, на экране входа в рабочее пространство или в
Экспорт → Помощник по открытому сбору данных. Можно также открыть
официальный помощник
или
tgwitness/static/capture.htmlиз доверенного checkout в современном браузере. Для обработки ключей и файлов помощник не выполняет сетевых запросов. Помощник поддерживает языки интерфейса сайта; временная панель сбора — английский и русский и открывается на языке браузера, если это один из них. - Сгенерируйте ключ и сохраните sealed-key.json. Это единственный закрытый ключ расшифровки. Скопируйте отдельное открытое значение recipient. Потеря закрытого ключа означает потерю доступа и к подключению, и к архиву. Подтвердите, что сохранили его, чтобы открыть следующий шаг. Если файл доставки у вас уже есть, загрузите сохранённый ключ и выберите У меня уже есть архив.
- Сделайте форк TgWitness, включите Actions в форке и запустите Sealed chat capture. Вставьте открытое значение recipient и выберите 30, 60 или 120 минут. Никогда не указывайте номер телефона, код входа, пароль Telegram, закрытый ключ или сессию во входных параметрах workflow, коммитах, issues или журналах.
- Во время выполнения скачайте sealed-connection из Artifacts и распакуйте его.
Загрузите
connection.tgwsealedв помощник, используя сохранённый закрытый ключ. Полученная ссылка содержит во фрагменте URL случайный секрет доступа. Не передавайте эту ссылку посторонним. Панель удаляет фрагмент и хранит секрет в session storage этой вкладки; в журналы HTTP-доступа он не попадает. - Откройте ссылку подключения. Войдите по QR-коду или по номеру телефона и коду входа. Если
Telegram попросит, введите пароль двухэтапной проверки. По умолчанию, как и в обычном рабочем
пространстве, используется встроенный пул учётных данных API. Можно развернуть
необязательный раздел собственных учётных данных и ввести оба значения —
api_idиapi_hash— с my.telegram.org/apps. Оставьте оба поля пустыми, чтобы использовать встроенный пул; неполная или некорректная пара отклоняется. Импорт сессий не допускается. Выберите режим и состав выгрузки. Ссылка подключения содержит секрет доступа: не передавайте её посторонним. - Выберите Telegram Takeout, Обычный Telegram API или Журнал одного чата. Для выгрузки аккаунта выберите все доступные чаты либо загрузите список и выберите один или несколько чатов, затем задайте даты, типы чатов, категории данных аккаунта и правила вложений. Проверьте настройки и размер, при желании сохраните JSON с настройками для независимого проверяющего, затем нажмите Начать сбор. После запуска настройки фиксируются. Продолжить сбор можно, только пока существует этот раннер; досрочное завершение сохраняет полученные данные и фиксирует пропуски. Истечение срока после запуска даёт явно помеченный частичный архив; истечение срока до запуска или отмена не дают архива.
- Дождитесь sealed-result, скачайте и распакуйте его и расшифруйте
delivery.tgwsealedв помощнике. Вы получитеdelivery.zipсevidence.zip,attestation.jsonlи инструкциями. Расшифровка в браузере ограничена 256 МиБ; для пакетов большего размера используйте потоковую локальную команду ниже. Большие результаты дополнительно содержат частиdelivery-NNNNNN.tgwsealed; тогда основнойdelivery.tgwsealedсодержитevidence.parts.jsonи аттестацию. Скачайте все части и соберите их локально, как описано ниже. - Если отзыв сессии не подтверждён или раннер был принудительно остановлен, завершите временную сессию в Telegram: Настройки → Устройства. При обычном завершении запрашивается выход из сессии, а запуск фиксирует, подтверждён ли отзыв.
В репозитории должны быть опубликованы закреплённые коммиты исходного кода и переиспользуемого workflow. Одну лишь локальную ветку другой репозиторий GitHub вызвать не может.
Бюджет времени сеанса#
Перед сбором кнопка Рассчитать время и объём оценивает выбранную историю и файлы по числу сообщений и ограниченной выборке. На экране отображаются время, уже затраченное на вход, расчётное время сбора и резерв на упаковку. Для файлов начальная оценка исходит из скорости 1 МиБ/с и двукратного запаса времени; по ходу сбора это допущение заменяется измеренной скоростью. Если оценка превышает оставшееся время, выберите Только сообщения или меньше чатов.
Сообщённое Telegram время ожидания Takeout добавляется к бюджету. Коллектор прекращает получение данных, когда оставшееся время требуется для упаковки, сохраняет полученные данные и помечает результат как частичный. Поэтому 120-минутный сеанс расходует оставшееся окно сбора, не дожидаясь истечения срока, чтобы начать подготовку архива. На экране отмечаются выборки, полный размер которых не удалось оценить.
Этот режим или постоянное рабочее пространство#
| Режим сбора | Настраиваемый состав | Отличия |
|---|---|---|
| Telegram Takeout, по умолчанию | Все доступные облачные чаты или выбранные чаты, даты, категории данных аккаунта, правила для медиа и представления JSON/HTML | Использует официальный механизм экспорта Telegram; может потребоваться подтверждение или ожидание. Takeout может перечислять покинутые каналы и группы, где Telegram это разрешает, и запрашивать дополнительные персональные данные. |
| Обычный Telegram API | Тот же состав данных аккаунта и те же варианты вывода — в пределах методов, доступных через обычный API | Не инициализирует Takeout; не может перечислять покинутые каналы и супергруппы или получать персональные данные, доступные только через Takeout. Контакты охватывают пользователей Telegram, а не весь сохранённый список телефонных контактов. Ограничения частоты запросов сохраняются. |
| Журнал одного чата | Один выбранный чат, правила вложений и, по желанию, аватары | Сохраняет историю и изменения, наблюдаемые во время этого запуска. Категории данных аккаунта, фильтры дат и представления, совместимые с Desktop, не применяются. |
У всех трёх режимов одинаковые аттестация GitHub и зашифрованная доставка. Takeout определяет способ получения данных и никогда не заменяется молча доступом через обычный API. TgWitness создаёт представления JSON/HTML из зафиксированных записей и сохраняет в экспорте выбранный способ получения данных. См. официальное описание Takeout API.
По умолчанию выбраны Takeout, все доступные типы чатов, включая архивные, весь период, профиль аккаунта и контакты, совместимые JSON и HTML, а также скачивание файлов. Начальный бюджет медиа — 4 ГиБ, пределы для каждого типа файлов видны в настройках; для файлов большего размера или при исчерпании бюджета скачивания сохраняются серверные хеши, если они доступны. Проверьте эти пределы до начала сбора. По хешам файл восстановить нельзя. Необязательные фото, истории, сведения о сессиях и дополнительные персональные данные выбираются отдельно.
Takeout может потребовать подтверждения в уже действующей сессии Telegram. Задержку устанавливает Telegram; новый вход или новый раннер её не обходят. Максимальное окно сбора — 120 минут с учётом входа и подтверждения, поэтому выгрузка большого аккаунта или долгое ожидание подтверждения могут не завершиться. Постоянная локальная выгрузка может продолжить ту же сессию, но аттестацию GitHub не наследует.
Согласование и проверка настроек#
После Проверить настройки и размер нажмите Сохранить настройки для проверки. Согласуйте
полученный sealed-export-settings.json с проверяющим до начала сбора. Изменения делают
сохранённую оценку недействительной. Коллектор подписывает действующие настройки и их SHA-256, а
квитанции выгрузки аккаунта привязывают те же параметры. Верификатор сообщает фактический режим,
выборку и полноту и отклоняет расхождение между журналом и вложенной выгрузкой аккаунта.
python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness --expected-selection sealed-export-settings.json --require-complete
--expected-selection отклоняет другой транспорт, состав чатов, фильтр или правило вложений.
--require-complete принимает только выгрузки аккаунта и журналы чатов, записанные как полные.
Без этих флагов верификатор всё равно проверяет происхождение и целостность и сообщает
записанные настройки и пропуски. Согласуйте ожидаемую выборку до запуска и храните её отдельно от архива.
Состав и интервалы получения данных определяют материал, собранный во время запуска; для сравнения
с предыдущими версиями используйте сохранённые ранее наблюдения.
| Задача | Режим |
|---|---|
| Выгрузить доступные данные аккаунта или выбранные чаты за ограниченный сеанс и передать проверяющему архив с внешней аттестацией | Сбор данных с помощью GitHub Actions (предварительный просмотр) |
| Непрерывно наблюдать за несколькими чатами, управлять аккаунтами, искать и читать пополняющийся архив | Локальное рабочее пространство или Docker |
Это отдельный сбор с новым входом. Он не загружает ваш существующий локальный журнал, не выгружает открытое сейчас рабочее пространство и не использует повторно его сессию Telegram. Незавершённый облачный сбор нельзя продолжить после уничтожения его раннера; новый запуск workflow начинает новый сбор.
Пункт Экспорт → Помощник по открытому сбору данных в рабочем пространстве открывает полный мастер внутри панели. Отдельная страница использует тот же мастер, элементы управления и темы. В обоих случаях ключи и расшифровка остаются в вашем браузере. Запуск workflow в GitHub и временная панель Telegram открываются в отдельных вкладках; мастер подсказывает, когда вернуться. Блокировка рабочего пространства удаляет ключ из памяти мастера. Сохранённый файл ключа остаётся на вашем устройстве.
Что публично, а что должно оставаться закрытым#
Сбор выполняется на стандартном раннере, размещённом GitHub. GitHub, утверждённый коллектор и его зависимости, страница помощника, браузер и HTTPS-туннель — доверенные части этой схемы. Временный хост обрабатывает сессию Telegram и сообщения в открытом виде; доставляемые артефакты зашифрованы для получателя.
Форк копирует код проекта в ваш репозиторий. Он не выгружает ваш аккаунт Telegram. Входной
параметр workflow recipient — открытый ключ шифрования. Не помещайте sealed-key.json, учётные
данные Telegram, коды входа, пароли 2FA и расшифрованный URL подключения в коммиты, входные
параметры workflow и публичные журналы.
Workflow публикует зашифрованные артефакты подключения и результата на один день. Скачайте оба вовремя; действуют доступность GitHub Actions, лимиты аккаунта и тарификация. Публичный форк не гарантирует неограниченных бесплатных вычислений. Ни платёжные данные, ни токен доступа GitHub в помощник не вводятся.
Закрытый ключ расшифровки остаётся в вашем браузере или файле. Данные сессии Telegram и наблюдения в открытом виде неизбежно существуют внутри временного коллектора. GitHub и HTTPS-туннель остаются доверенной инфраструктурой. Аттестация может сделать публичными дайджест архива и идентификатор workflow; содержимое архива в аттестацию не помещается. Метка времени аттестации не является меткой времени сообщения.
Устранение неполадок#
| Симптом | Что делать |
|---|---|
| Нет кнопки Run workflow | Откройте свой форк, включите Actions и синхронизируйте форк с main исходного репозитория. Не меняйте утверждённые закрепления исходного репозитория, чтобы обойти ошибку. |
Нет артефакта sealed-connection |
Проверьте, запустилось ли задание и завершило ли шаг запуска и загрузки. Запуску могут помешать сбои очереди, раннера, загрузки образа, туннеля или политики репозитория. |
| Не удаётся открыть подключение | Загрузите сохранённый ключ этого запуска, распакуйте скачанный артефакт и выберите connection.tgwsealed. Раннер должен ещё работать. |
| Чтение истории приостановлено | Проверьте статус в панели и, пока сеанс активен, продолжите сбор либо завершите его с уже собранными данными. Ограничения Telegram и недоступное содержимое могут оставить пропуски. |
Нет sealed-result |
Отмена или истечение срока до начала сбора не дают архива; запуск тогда завершается уведомлением No archive. Сбой на шаге сбора, аттестации или упаковки также препятствует доставке; упавший шаг называет причину супервизора без личных данных. Изучите его, не публикуя учётные данные. |
| Браузер не может расшифровать большой архив | Для пакетов больше 256 МиБ используйте потоковую команду CLI ниже. Неверным или утерянным закрытым ключом результат расшифровать невозможно. |
| Проверка отклоняет подписанта | Используйте доверенную актуальную установку TgWitness и точное имя вызывающего репозитория OWNER/REPOSITORY. Не принимайте замещающую политику, приложенную к архиву. |
| Telegram всё ещё показывает временную сессию | Завершите её в «Настройки → Устройства». Выход может не сработать, а принудительно прерванный workflow может не выполнить очистку. |
Прежде чем полагаться на эту предварительную версию, попробуйте её на небольшом чате под вашим контролем: создайте сообщение и вложение, соберите их, расшифруйте результат, запустите верификатор, проверьте результаты по охвату и медиа и убедитесь, что сессия Telegram отозвана. Автоматические проверки используют синтетический клиент Telegram и отдельный тест с настоящим сертификатом GitHub; прогон на реальном аккаунте для текущей ревизии не записан.
Локальная расшифровка и проверка#
Используйте инструменты из независимо доверенной установки, а не исполняемые файлы, поставляемые вместе с неизвестным архивом доказательств:
python -m tgwitness.sealed_crypto decrypt delivery.tgwsealed --key sealed-key.json --out delivery.zip
# Unzip delivery.zip using your archive manager, then:
python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness
При многочастной доставке сначала расшифруйте основной пакет и положите извлечённый из него манифест рядом со всеми зашифрованными частями, затем выполните:
python -m tgwitness.sealed_parts evidence.parts.json --key sealed-key.json --out evidence.zip
python -m tgwitness.sealed_verify evidence.parts.json --assembled evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness
Манифест является объектом аттестации и связывает все части и собранный ZIP. Для большого архива
задайте через --max-gib подходящий предел распакованного объёма при проверке; по умолчанию —
4 ГиБ. Проверки ожидаемой выборки и полноты состава работают и для многочастной доставки.
Требуются Python 3.11+, зависимости проекта и свежий GitHub CLI с поддержкой --signer-digest и
--deny-self-hosted-runners. Доступен также генератор ключей для командной строки:
python -m tgwitness.sealed_crypto keygen sealed-key.json.
Верификатор использует tgwitness/sealed_policy.json из доверенной установки. Он проверяет
вызывающий репозиторий, подписывающий workflow исходного репозитория, утверждённый коммит
подписанта, требование раннера, размещённого GitHub, дайджест всего ZIP, целостность внутреннего
журнала и вложений, то, что ключ аккаунта создан заново, и ожидаемый коммит коллектора. Он
показывает результаты по истории и медиа, а не подразумевает, что сохранены все данные. Пустой
список утверждённых релизов приводит к отказу (fail closed). Обновление политики — явное решение о
доверии; никогда не принимайте автоматически политику, предложенную самим архивом.
Для работы без сети заранее получите доверенные корни в доверенной среде:
gh attestation trusted-root > trusted_root.jsonl
python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness --trusted-root trusted_root.jsonl
Метка времени аттестации относится к фиксации архива. Она не подтверждает подлинность меток времени сообщений или показаний системных часов коллектора. См. параметры проверки GitHub.
Как форк остаётся вне процесса сбора#
Вызывающий workflow содержит на уровне задания ссылку на переиспользуемый workflow исходного
репозитория по полному SHA коммита. Этот workflow явно извлекает исходный репозиторий на
фиксированном SHA коллектора. actions/checkout по умолчанию в переиспользуемом workflow
извлёк бы вызывающий репозиторий, поэтому намеренно не используется.
Workflow не восстанавливает кэши вызывающего репозитория, не использует его артефакты, не выполняет его файлы и не принимает URL исходников или образов, команды оболочки, подготовленные ZIP-файлы или хеши для подписи. Он принимает открытое значение recipient ограниченной длины и длительность сеанса. Actions, базовый образ Python и cloudflared закреплены неизменяемыми дайджестами; зависимости Python берутся из существующих требований, закреплённых хешами. Образ собирается из доверенного исходного кода без кэша.
Коллектор работает от имени пользователя без прав root, с образом только для чтения, со сброшенными capabilities Linux, ограничениями ресурсов, без сокета Docker и без переменных окружения с токеном GitHub. Монтируются только новые каталоги конфигурации, рабочего пространства и вывода. Ограниченное приложение FastAPI предоставляет вход, список диалогов, настраиваемый сбор аккаунта или чата, статус, продолжение, завершение и отмену. Маршрута для скачивания данных в открытом виде, общего маршрута администрирования, маршрута импорта и конечной точки подписи нет.
Супервизор останавливает контейнеры с сетевым доступом до того, как действие аттестации прочитает
окончательный зафиксированный evidence.zip или evidence.parts.json. У контейнера упаковки нет
сети. Шаги загрузки указывают только connection.tgwsealed и delivery*.tgwsealed;
ни доказательства в открытом виде, ни учётные данные Telegram не загружаются как артефакты.
Очистка удаляет приватные каталоги и контейнеры, а GitHub уничтожает виртуальную машину
раннера после завершения задания. Артефакты хранятся один день; скачайте их до истечения срока.
Владелец форка может заменить вызывающий workflow или создать другой подписанный файл. Строгий верификатор должен отклонить получившийся другой подписывающий workflow или дайджест. Эта конструкция по-прежнему зависит от отсутствия эксплуатируемых ошибок в утверждённом коде и от целостности инфраструктуры раннеров и подписи GitHub.
Криптографическая передача#
Каждый ключ получателя — RSA-3072 (импорт RSA-4096 также принимается), экспонента 65537. Каждый конверт имеет новый случайный ключ AES-256 и 96-битный nonce. Ключ AES оборачивается с помощью RSA-OAEP с SHA-256/MGF1-SHA256. AES-GCM со 128-битным тегом аутентифицирует весь префикс и полезную нагрузку. Открытое значение recipient — DER SPKI в base64; файл закрытого ключа содержит DER PKCS8 в base64.
Байты конверта: TGWSEAL1\n, длина JSON-заголовка в формате uint32 big-endian, заголовок,
шифртекст и 16-байтовый тег GCM. Заголовок содержит ровно algorithm, key и nonce; алгоритм —
RSA-OAEP-256+A256GCM. Весь префикс до конца заголовка включительно служит дополнительными
аутентифицируемыми данными GCM. Размер заголовка ограничен 8192 байтами. CLI обрабатывает полезную
нагрузку до 8 ГиБ в потоковом режиме и выполняет аутентификацию до размещения запрошенного
выходного файла; перезаписывать существующий файл назначения он отказывается. Это собственный
формат конверта проекта поверх стандартных криптографических примитивов: RSA-OAEP с SHA-256
и AES-256-GCM, которые есть в OpenSSL и в любой крупной криптографической библиотеке.
Аттестация исходных байтов доказательств создаётся до помещения доказательств и аттестации во внешний зашифрованный пакет. Это исключает циклическую зависимость между хешем архива и сертификатом, включённым в тот же архив. Для публичных репозиториев метаданные аттестации (репозиторий, workflow, коммит, имя и дайджест артефакта) публичны. Никогда не указывайте названия чатов в публичных метаданных.
Охват и проверка#
Этот режим использует подписанный журнал и механизм выгрузки аккаунта. Secret Chats, история, удалённая до начала сбора, и недоступные аккаунту данные исключаются. Личные облачные чаты включаются, если выбраны. Список выбора чатов ограничен 20 000 диалогов; выгрузка аккаунта сама составляет свою опись. Отсутствующие данные, неудачные загрузки файлов и незавершённые задачи фиксируются. Пределы вложений и ограничения раннера по диску и времени сохраняются. Большая доставка использует зашифрованные части вместо фиксированного порога доставки в 4 ГиБ. Завершённость означает, что зафиксированные выбранные задачи выполнены, а не что в архиве есть каждая историческая запись Telegram. Журнал чата может также наблюдать живые обновления; ни один из режимов не является атомарным снимком. Создаваемые снимки экрана и записи экрана в этот режим не входят.
Тесты охватывают синтетический новый вход, изоляцию состава, медиа, отмену, частичное завершение по истечении срока, неудачный выход, запрещённые пути и поля API, отклонение заранее заполненного рабочего пространства, отклонение неверного ключа и подделки, обязательные флаги верификатора и совместимость шифрования в браузере и Python. Приёмочный тест в браузере использует явно помеченную имитацию аттестации; это не настоящий тест Sigstore. Результаты приёмки на настоящем размещённом раннере, в Docker, с настоящей аттестацией GitHub и на реальном Telegram необходимо сообщать отдельно от локальных синтетических проверок.
Условия GitHub Actions ограничивают использование размещённых раннеров жизненным циклом программного проекта. Форк этих ограничений не снимает; эту предварительную версию нельзя продвигать как неограниченный бесплатный хостинг для рабочей эксплуатации. Cloudflare Quick Tunnels также предназначены для тестирования и разработки. Помощник и workflow подходят для оценки этой функции; пригодность для рабочего сервиса остаётся отдельным требованием к развёртыванию.
Порядок выпуска для мейнтейнеров#
- Закоммитьте и проверьте коллектор, супервизор, определение контейнера и тесты.
- Закрепите этот коммит коллектора в
sealed-collector.yml, затем закоммитьте и проверьте переиспользуемый workflow. Никогда не выводите checkout неявно из SHA вызывающего репозитория. - Закрепите коммит переиспользуемого workflow в
sealed-witness.ymlи добавьте его пару SHA workflow/коллектора вsealed_policy.jsonв доверенном релизе. - Опубликуйте все упомянутые коммиты и помощник, затем протестируйте независимый форк и настоящий сертификат GitHub. Не удаляйте через squash коммиты, на которые ссылаются эти закрепления, если ссылки не будут заново сформированы и опубликованы.
О различии между вызывающим репозиторием и подписантом в исходном репозитории см. переиспользуемые workflow и аттестации.