# Підключення, проксі-сервери та захист даних

Canonical page: https://phishdestroy.github.io/TgWitness/uk/docs/reference/connection/

Аутентифікація, автоматичні пули проксі-серверів, режими IP, політика резервного переходу, зовнішні запити та зберігання секретних даних.

Цей документ описує поведінку TgWitness 0.7.0 та її обмеження. Аутентифікація, доступ до джерел, мережеве з’єднання та повнота збору даних — це окремі стани. Щоб дізнатися про етапи входу, формати файлів та роботу з кількома обліковими записами, почніть з розділу [«Облікові записи та формати сеансів](https://phishdestroy.github.io/TgWitness/uk/docs/reference/accounts/)». Щодо політик подій та поведінки при перезапуску див. розділ [«Як працює збір даних](https://phishdestroy.github.io/TgWitness/uk/docs/reference/collection/)».

## Методи автентифікації

**Ідентифікатор API та хеш API ідентифікують додаток; вони не замінюють дані для входу в обліковий запис.** У TgWitness їх використання є необов’язковим. Пріоритет: спочатку пара, введена у форму, потім — з імпортованого JSON-файлу облікового запису, потім — пара, збережена в робочій області, а потім — вбудований пул із 50 публічних пар, які перевіряються у випадковому порядку з автоматичною ротацією, коли Telegram відхиляє одну з них. Лише пара Telegram Desktop (2040) надсилається разом із відповідним описом клієнта Telegram Desktop. Вашу власну пару з Інструментів розробки API на [my.telegram.org](https://my.telegram.org) можна використовувати з усіма вашими обліковими записами; кожен обліковий запис все одно має власну авторизацію.

| Метод | Вимоги | Підтримка TgWitness |
| --- | --- | --- |
| Номер телефону, код, опціональна двофакторна аутентифікація (2FA) | Доступ до облікового запису; пара API — необов’язкова | Вхід у панель |
| HEX-код автентифікації + DC-ідентифікатор | Повний ключ довжиною 512 символів та DC 1–5 | Вкладка **«Ключ** прямої **авторизації»**; опціональний ідентифікатор користувача перевіряється перед збереженням авторизації |
| Telethon StringSession | Дійсний рядок сеансу | Вхід у панель |
| Telethon SQLite `.session` | Закритий, послідовний текст | Пряме імпортування схем із панелі 7/8; опціональний офлайн-інтерфейс командного рядка (CLI) |
| Pyrogram SQLite `.session` | Закрита виробнича сесія користувача | Пряме імпортування схем із панелі 2/3 |
| Telegram Desktop TData ZIP | Один сучасний обліковий запис; локальний пароль, якщо обліковий запис захищений | Перетворення в оперативній пам’яті з перевіркою контрольних сум та дешифрування |
| JSON-файл облікового запису | Підтримувані поля API/сесії/ключа | Метадані самі по собі заповнюють облікові дані API; все одно потрібен вхід за допомогою сесії/ключа або номера телефону/QR-коду |
| Вхід за QR-кодом | Підтвердження від офіційного додатка Telegram | Локальне генерування QR-кодів, термін дії/повторна спроба, опціональна двофакторна аутентифікація (2FA) |
| TDLib / Pyrogram StringSession | Інші формати, специфічні для бібліотек | Не підтримується |
| Токен бота | Бот із власною моделлю доступу та оновлення | Цей збирач даних не використовує цей інструмент |

Telegram обирає доставку коду; доставка SMS не гарантується. Хеш API не може відновити скасовану сесію або замінити забутий пароль 2FA. TgWitness не зберігає коди входу або пароль 2FA Telegram на диску.

Для приватного джерела обліковий запис повинен уже мати доступ. Ім’я користувача групи не потрібне. Проксі або імпорт сеансу не надають ані членства, ані прав адміністратора. Поточне членство не гарантує доступу до історії до приєднання.

## Імпортувати файл сеансу Telethon

Telethon SQLite, Pyrogram SQLite та Telegram Desktop TData використовують різні формати. Панель виявляє та конвертує підтримувані структури; перейменування файлу не є конвертацією. Виберіть одну сесію та відповідний файл JSON у розділі **«Файли**», а потім натисніть **«Підключити обліковий запис**». Приймається до чотирьох відповідних файлів загальним обсягом до 8 МіБ. Детальніше див. [обмеження форматів](https://phishdestroy.github.io/TgWitness/uk/docs/reference/accounts/) для TData/JSON. Функція відновлення пароля відсутня. Вхід за допомогою телефону/2FA або QR-коду створює окрему авторизацію.

Додатковий шлях командного рядка, доступний лише для Telethon, залишається у використанні:

1. Зупиніть роботу клієнта, який використовує оригінальну сесію, і створіть її точну копію. Конвертер відхиляє файли з незавершеним WAL/журналом. Належним чином закрийте оригінальний клієнт, замість того щоб видаляти ці файли, щоб обійти перевірку.
2. У середовищі TgWitness виконайте:

```
python -m tgwitness.sessions account.session --out account.tgwitness-session
```

1. У розділі **«Додати обліковий запис**»**→ «Файли**» завантажте результат або вставте його рядок і продовжуйте.
2. Перевірте відображений числовий ідентифікатор облікового запису, виберіть джерела та розпочніть спостереження.

Конвертер відкриває базу даних SQLite у режимі «тільки для читання», не виконує оновлення схеми та не надсилає мережевих запитів, а також не виводить дані сеансу. Він перевіряє версію схеми, типи таблиць, один рядок сеансу, IP/порт/дата-центр та довжину ключа. Вхідні дані CLI обмежені до 64 МіБ; текст StringSession обмежений до 4 КіБ. Конвертація через панель завантажує файли на аутентифікований сервер TgWitness, обробляє їх у пам’яті та повертає нормалізовані облікові дані до цього браузера без збереження завантажених оригіналів. Для віддаленого сервера використовуйте HTTPS.

**Перетворений файл є незашифрованим секретом доступу до облікового запису.** Зберігайте його в захищеному сховищі та ніколи не заносьте його у репозиторій і не надсилайте стороннім сервісам конвертації. TgWitness зберігає авторизовану сесію у своєму зашифрованому сховищі. Копіювання сесії не створює окремої авторизації: не запускайте одночасно клієнти з клонованими ключами авторизації та не розраховуйте на незалежну доставку оновлень.

Конвертація передає авторизацію, а не оригінальні повідомлення, кеш об’єкта чи постійний курсор оновлення. Вона не забезпечує відновлення оновлень після перезапуску процесу.

## MTProto, Telethon та проксі-сервери

MTProto — це протокол Telegram. Telethon — це клієнтська бібліотека на Python, яку використовує TgWitness. MTProxy — це транспортний проксі-сервер Telegram; SOCKS5 та HTTP CONNECT забезпечують загальні тунелі. Жоден із них не замінює аутентифікацію облікового запису.

Збережіть маршрут для кожного робочого простору в розділі **«Обліковий запис» → «Налаштування» → «Налаштування з’єднання» → «Змінити маршрут з’єднання»** перед входом у систему. Для нових робочих просторів за замовчуванням встановлено **«Автоматичний MTProxy» · публічні списки** з режимом приховування IP-адреси. Існуючі робочі простори, які явно використовували режим «Прямий», зберігають режим, що це дозволяє.

## Режими IP

Маршрут визначає тип з’єднання. Режим IP визначає, коли адреса сервера може бути розкрита. Ці налаштування не передбачають встановлення VPN та не перенаправляють весь трафік пристрою.

| Режим | Telegram | Зовнішні запити |
| --- | --- | --- |
| Hide IP (`hide`) | Використовуйте проксі-сервер; якщо жоден не працює, зачекайте. Прямого альтернативного варіанту немає. | Вимагає SOCKS5/HTTP; відхиляє запити без відповідного проксі-сервера. |
| Дозволити альтернативний варіант (`fallback`) | Автоматичний MTProxy може використовувати Direct після налаштованої затримки, а потім повернутися до робочого проксі-сервера. | Бажано використовувати налаштований зовнішній проксі-сервер або маршрут SOCKS5/HTTP облікового запису; в іншому випадку допускається використання Direct. |
| Тунель / VPN (`tunnel`) | Дозволено використання прямих маршрутів та негайного автоматичного переходу на резервний пул. | Прямий доступ дозволено, якщо не налаштовано відповідний проксі-сервер. |

Режим «Тунель/VPN» передбачає, що ви керуєте цією мережею окремо. Без діючого тунелю адресати можуть бачити власну адресу сервера. Обирайте режим відповідно до вашої фактичної мережі, а не за назвою опції.

### Оберіть шлях

| Маршрут | Налаштування | Межі |
| --- | --- | --- |
| Автоматичний MTProxy | Вбудовані списки або каталог операторів | Підтримує робочий маршрут Telegram; прямий резервний варіант залежить від режиму IP |
| Прямий | Режим тунелю/VPN | Telethon використовує мережевий маршрут хоста |
| SOCKS5 | Хост, порт, опціонально — ім’я користувача/пароль | python-socks, увімкнено віддалений DNS-адресат |
| HTTP CONNECT | Хост, порт, опціонально — ім’я користувача/пароль | Простий HTTP CONNECT; TLS до самого проксі-сервера не реалізовано |
| MTProxy | Хост, порт, секрет | Експериментальний формат передачі Telethon; 32 шестнадцяткові цифри або `dd` + 32 шестнадцяткові цифри |

Фальшиві секретні ключі TLS `ee` відхиляються. Нормалізація в Telethon 1.45 може видаляти префікс та домен, але це не реалізує функцію Fake TLS. Вставте `tg://proxy?server=…&port=…&secret=…` або `https://t.me/proxy?server=…&port=…&secret=…` та виберіть **«Заповнити поля з посилання**». Це перевіряє та заповнює поля без підключення чи збереження; перегляньте та збережіть маршрут окремо. Поля для ручного введення залишаються доступними. Див. [проксі-посилання Telegram](https://core.telegram.org/api/links#proxy-links).

### Публічні проксі-сервери, що надаються вашою інсталяцією

Вбудований список об’єднує чотири джерела: [SoliSpirit/mtproto](https://github.com/SoliSpirit/mtproto), [zakky8/mtproto-proxy-pro](https://github.com/zakky8/mtproto-proxy-pro), [kort0881/telegram-proxy-collector](https://github.com/kort0881/telegram-proxy-collector) та [3yed-61/MTP-Collector](https://github.com/3yed-61/MTP-Collector). У комплекті знімка містяться дані про кінцеві точки, атрибуцію джерел та дати завантаження. Наявність провайдера у списку не є доказом того, що проксі працює або передає кожне оновлення Telegram.

**MTProxy автоматично** перевіряє зв’язок із транспортною мережею Telegram, підтримує робочий проксі-сервер і перемикається на інший у разі його збою. Робочі простори віддають перевагу різним проксі-серверам, коли є достатня кількість робочих записів; унікальна вихідна адреса не гарантується. Проксі, що вийшли з ладу, відпочивають перед черговою спробою. Якщо жоден не працює, режим IP визначає, чи збір даних повинен чекати, чи можна використовувати пряме з’єднання. Зміна проксі не змінює обліковий запис і не стирає його журнал. Вибір маршрутів та зміни фіксуються у підписаному журналі.

Поки автоматичні маршрути активні, списки оновлюються щогодини, а перевірки трафіку виконуються за замовчуванням кожні десять хвилин. Ці інтервали можна налаштувати. **Оновлення публічних списків** вимагає оновлення; сам перегляд списку не змінює збережений ручний маршрут.

Кожна відповідь каналу обмежена 1 МіБ із восьмисекундним тайм-аутом запиту та 20-секундним загальним лімітом завантаження; перенаправлення відхиляються. Зберігається та дедуплікується до 64 сумісних записів на джерело. Парсер приймає підтримувані шістнадцяткові та base64url секрети, а також JSON-канал. Підроблені TLS-`ee`, недійсні посилання, приватні/зарезервовані IP-літерали та локальні імена хостів пропускаються. Імена хостів розпізнаються та перевіряються перед використанням, а обрана IP-адреса фіксується для цього з’єднання. Автоматичне повторне отримання знову розпізнає ім’я хоста; щоб розпізнати його знову, потрібно повторно застосувати ручний запис.

У разі невдалої, порожньої або несумісної відповіді каналу зберігається попередній знімок джерела. Оновлення є атомарними, серіалізованими та обмеженими однією спробою на хвилину для кожного робочого простору. Успішне тестування передачі даних підтверджує наявність з’єднання, а не анонімність чи повноту збору даних.

**Трафік Telegram та HTTPS-запити використовують різні маршрути.** Завантаження списків використовують окреме HTTPS-з’єднання та наданий маршрут зовнішніх запитів. «`TGWITNESS_PROXY_FEED_PROXY`» явно замінює цей маршрут проксі-сервером HTTP/SOCKS5; обидва варіанти колектора Compose перенаправляють його. Фоновий пул слідує за основною робочою областю. Жодних сесій Telegram, облікових даних API, токенів панелі чи токенів ботів не надсилається постачальникам даних. Назви постачальників, дати знімків та маршрут завантаження вказані в розділі **«Звідки походить список**».

MTProxy передає лише трафік Telegram. Операції Workspace HTTP, такі як мітки часу, сповіщення, позасайтові копії та перевірки джерел, використовують окремий SOCKS5/HTTP-проксі, якщо він налаштований, а потім — маршрут SOCKS5/HTTP облікового запису. Без жодного з них Hide IP відхиляє запит; інші режими дозволяють прямий доступ. Зовнішні запити можна вимкнути. Явно налаштований проксі для завантаження каналів залишається окремим параметром, який оператор може змінити. Незалежна служба свідків зберігає власний маршрут.

****Параметри автоматичного пулу**** У розділі **Параметри → Автоматичний MTProxy** налаштуйте поріг відмови, час очікування, заплановану ротацію, спільне використання проксі-серверів та допустиму затримку переходу на резервний сервер. | Параметр | За замовчуванням | | --- | --- | | Відключення перед заміною | 3 за 10 хвилин | | Кількість проксі, що перевіряються за одну спробу з’єднання | 3 | | Перша / максимальна пауза після збою | 10 хвилин / 6 годин | | Планова ротація | Вимкнено; перемикання при збою | | Акаунти на один проксі | 0: надавати перевагу окремим записам, ділитися за потреби. Встановіть 1, щоб чекати на ексклюзивний запис. | | Затримка до дозволеного переходу на Direct | 10 хвилин; Hide IP все ще відмовляє у Direct | | Оновлення каналу / перевірки каналу передачі | 60 / 10 хвилин; для спільного пулу застосовуються значення основної робочої області | Різні проксі-сервери не гарантують різних вихідних адрес. Ці налаштування не перекривають обмеження Telegram і не забезпечують анонімності.

Щоб замінити публічний список на власний каталог операторів, налаштуйте наведені нижче параметри заміщення. Це повністю вимикає зовнішні підписки, навіть якщо масив `proxies` порожній.

Скопіюйте [порожній каталог у папку](https://github.com/phishdestroy/TgWitness/blob/main/deploy/proxies.config.example)`proxy-config/proxies.json` та додайте свої розгорнуті публічні кінцеві точки:

```
{"format": "tgwitness-proxy-catalog-v1", "proxies": [
  {"id": "project-eu", "label": "Project EU",
   "link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"}
]}
```

Приклади значень необхідно замінити. Допускається до 32 різних записів. Автентифікований список повертає мітки/хости/порти без спільних секретів; вибір одного з них зберігає його облікові дані у сховищі робочого простору. Доступність залишається неперевіреною до проведення явного тесту транспорту. У разі неправильно сформованого каталогу залишається можливість ручної конфігурації.

Запуск у нативній середовищі: вкажіть `TGWITNESS_PROXY_CATALOG` як місцевий шлях до файлу JSON. Docker:

```
docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build
```

Накладка монтує каталог `proxy-config` у режимі «тільки для читання»; файли повинні бути доступні для читання контейнером з UID 10001. Цей каталог виключено з Git, контексту збірки Docker та архівів вихідного коду. Цей каталог налаштовує облікові записи для збору даних; [бот-свідок](https://phishdestroy.github.io/TgWitness/uk/docs/reference/witness/) використовує власний маршрут HTTP/SOCKS5, а не MTProxy.

Прямий резервний варіант регулюється режимом IP, описаним вище. Призупиніть спостереження перед зміною маршруту. Збереження розриває з’єднання зі старими клієнтами та скасовує незавершений вхід; новий клієнт використовує збережений маршрут. Прив’язка журналу/сесії до облікового запису зберігається. Налаштування замінюють попередній маршрут: під час редагування введіть облікові дані проксі-сервера заново.

Реквізити облікових даних шифруються за алгоритмом `network.enc`. API не повертає ім’я користувача, пароль або секретний ключ. Підписані записи містять тип маршруту та інформацію про наявність реквізитів облікових даних, виключаючи кінцеву точку та секретні ключі. Оператор може бачити кінцеву точку на панелі. Поля з секретними даними очищаються після збереження, блокування або перемикання робочих просторів.

**Функція «Перевірити з’єднання з Telegram»**, доступна також до входу в систему, відкриває та закриває тимчасове неавторизоване з’єднання з Telegram через маршрут. Вона не звертається до веб-сайту для перевірки IP-адреси. Успішне виконання функції підтверджує наявність транспортного з’єднання, але не означає доступ до груп, повну доставку повідомлень або анонімність.

Проксі застосовується до з’єднань клієнта Telegram, включаючи завантаження медіафайлів із серверів Telegram DC. Браузер, pip, SSH та інструменти TSA, що запускаються вручну, мають окремі маршрути. Ім’я хосту проксі може вирішуватися локально. `rdns` впливає на імена хостів призначення; Telegram часто надає числові IP-адреси DC.

SOCKS5 та звичайний HTTP CONNECT самі по собі не шифрують облікові дані проксі-сервера або тунель «клієнт-проксі». MTProto окремо захищає трафік Telegram. У ненадійній мережі використовуйте відповідний захищений канал для підключення до проксі. Приватні групи є хмарними чатами; MTProto не перетворює їх на секретні чати з наскрізним шифруванням.

## Шифрування та підписи

| Рівень | Реалізовано | Відповідальність оператора |
| --- | --- | --- |
| Трафік Telegram | Telethon MTProto | Довіра до платформи, маршрут та доступність |
| Веб-панель | Токен-носій, петлеве підключення за замовчуванням, обмеження на кількість запитів | HTTPS або SSH-тунель для віддаленого доступу |
| Секрети | Fernet для облікових даних API, сеансів, облікових даних проксі-серверів та приватного ключа для підпису | Захистіть ключ дешифрування та хост, на якому працює програма |
| Ключ сховища | Локальний ключ або зовнішній головний ключ для нової інсталяції | Окреме захищене сховище та резервне копіювання ключів |
| Повідомлення та вкладення | Зберігання даних додатка у вигляді відкритого тексту | Зашифрований диск/том |
| ZIP/JSONL/CSV/HTML | Перевірка цілісності, відсутність шифрування вмісту | Захист експортованих копій та передач |
| Походження та час | Підписаний журнал, підтвердження обробки, інструменти RFC 3161 | Довірений ключ, незалежні контрольні точки/TSA та процедура зберігання |

**Захист сховища** в обліковому записі відображає ці стани. Токен панелі є секретом доступу, а не паролем шифрування. Він надає адміністраторський доступ; [видані токени](https://phishdestroy.github.io/TgWitness/uk/docs/reference/access/) можуть бути обмежені обліковими записами та чатами. Робочі простори використовують спільний хост-процес і не є ізольованими орендарями.

Явно запущена, ізольована синтетична демо-версія може відкриватися автоматично через пряме з’єднання типу loopback. Це використовує окрему функцію, що діє протягом усього терміну існування процесу; вона не розкриває налаштований токен панелі та не надає доступу до реальних робочих просторів. Віддалені, проксі-запити або запити з інших доменів не можуть отримати/використовувати цю функцію автоматичного входу. Ця зручність не скасовує обмеження автентифікації для реальних даних облікових записів.

BitLocker, LUKS, FileVault або керований зашифрований том можуть захистити сховище в рамках відповідних моделей загроз. Адміністратор розблокованої машини, що працює, все одно може читати дані. У плануванні сховища слід враховувати файли SQLite WAL/SHM, мультимедіа, тимчасові експортовані дані, обмінну пам’ять, резервні копії та завантажені з браузера файли. Том Docker не шифрується лише тому, що це том. TgWitness не реалізує SQLCipher або шифрування об’єктів.

## Зовнішній головний ключ

Для **нової** інсталяції розмістіть головний ключ поза каталогом даних. Це не призведе до автоматичного перенесення існуючого сховища локальних ключів. Підготуйте каталог ключів, доступ до якого має лише ідентифікатор служби, а потім виконайте:

```
python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key
export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key
python -m tgwitness --data-dir /private/observations/new-case
```

PowerShell із використанням встановленого середовища проекту:

```
python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key
$env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key'
python -m tgwitness --data-dir E:\PrivateData\new-case
```

У Docker підключіть файл у режимі «тільки для читання» поза межами `/data`, наприклад, у `/run/secrets/tgwitness-master.key`, і встановіть змінну середовища на цей шлях. UID служби повинен мати права на читання цього файлу. Передавайте шлях, а не байти ключа, через файли середовища/конфігурації.

Кожен робочий простір отримує випадковий публічний солт та власний ключ Fernet, отриманий за допомогою HKDF-SHA256. `vault.external.json` зберігає метадані виведення, а не головний ключ. Відсутність або неправильність ключа призводить до збою запуску без його автоматичної заміни. Зберігайте як метадані солта, так і головний ключ для відновлення.

Усі робочі середовища походять від одного головного ключа; його компрометація впливає на всю інсталяцію. Процес, що виконується, може розшифровувати секретні дані. Це не HSM і не KDF на основі пароля. Довільні паролі, створені людиною, не приймаються замість випадкового ключа.

Зберігайте існуючий ключ для існуючих інсталяцій доти, доки не буде здійснено та перевірено цілеспрямовану міграцію. Видалення `vault.key` або заміна головного ключа може призвести до втрати доступу до сесій/ключів підпису. Зберігайте зашифровані резервні копії та ключі окремо та перевіряйте можливість відновлення в ізольованому екземплярі.

## Джерела та обсяг перевірки

Переглянуто 26 жовтня 2026 року:

- https://core.telegram.org/api/auth
- https://core.telegram.org/api/obtaining_api_id
- https://docs.telethon.dev/en/stable/basic/signing-in.html
- https://docs.telethon.dev/en/stable/concepts/sessions.html
- https://core.telegram.org/mtproto/mtproto-transports
- https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/SourceFiles/storage/storage_account.cpp
- Telethon 1.45.0: SQLiteSession, StringSession, `Connection._proxy_connect`, `TcpMTProxy.normalize_secret` та методи завантаження.

Локальні тести охоплюють фіксовані тестові набори SOCKS5/HTTP CONNECT із зворотним зв’язком, синтетичні сесії SQLite, ізоляцію маршрутів, виключення секретних даних та відмову у разі відсутності ключа. Вони не перевіряють реальну сумісність Telegram та проксі-серверів, а також поведінку MTProxy в режимі реального часу. Див. [VERIFICATION.md](https://phishdestroy.github.io/TgWitness/uk/docs/reference/verification/) та [LIVE_ACCEPTANCE.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md).