TgWitness / Dokumentacja

Co zostało przetestowane →

Odniesienie / Konfiguracja

Telegram · Szybki start

Wszystkie sposoby instalacji i uruchomienia TgWitness: pakiet dla systemu Windows, Python, Docker oraz syntetyczna wersja demonstracyjna wraz z wstępnymi testami.

TgWitness / Dokumentacja

Pierwsze kroki

Język angielski · Русский · Ukraiński · Español · Português (Brasil) · Türkçe · العربية · فارسی · Urdu · हिन्दी · Bahasa Indonesia · Tiếng Việt · Chiński uproszczony

TgWitness to samodzielna aplikacja służąca do monitorowania grup i kanałów w serwisie Telegram, do których mają Państwo dostęp za pośrednictwem swoich kont. Działa ona lokalnie, korzystając z własnego katalogu danych.

Pierwsza wizyta? Zapoznaj się z wersją demonstracyjną przed podłączeniem konta. Wybierz przewodnik dotyczący serwerów proxy, świadków, eksportów lub konfiguracji serwera. GitHub Actions capture (wersja zapoznawcza) uruchamia proces przechwytywania w Twoim własnym forku na GitHubie zamiast w lokalnej instalacji.

Zainstaluj i uruchom#

Instalator z przewodnikiem zawiera własną wersję języka Python i przed instalacją sprawdza skróty pakietów oraz podpisy wydania. Ponowne uruchomienie programu aktualizuje istniejącą instalację.

Linux / macOS:

curl -fsSL https://get.destroy.tools/install.sh | bash

Windows (PowerShell lub wiersz poleceń):

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"

Na serwerze z systemem Ubuntu uruchom program jako root, aby zainstalować usługę działającą w tle; na komputerze stacjonarnym uruchom program jako zwykły użytkownik. W systemie Ubuntu instalator wyświetla adres panelu i klucz dostępu; w systemach macOS i Windows lokalny panel otwiera się w przeglądarce. Kontynuuj w sekcji Połącz z Telegramem poniżej. Sekcja Instalacja, weryfikacja i aktualizacja obejmuje opcje dostępu do serwera, sprawdzanie skryptu przed jego uruchomieniem, aktualizacje oraz usuwanie.

Inne metody#

Wersje na GitHubie, kod źródłowy i Docker stanowią alternatywę dla instalatora. Pliki do pobrania w wersji przenośnej stają się dostępne po opublikowaniu kompilacji wydania:

Host Nie wymaga instalacji Źródło: Python 3.11+ Docker: Engine/Desktop z Compose w wersji 2.20 lub nowszej
Windows Proszę pobrać plik „TgWitness-<version>-windows-amd64-portable.zip” z sekcji „GitHub Releases”, a następnie kliknąć dwukrotnie plik „TgWitness.cmd” Proszę dwukrotnie kliknąć Start.cmd Proszę dwukrotnie kliknąć scripts\Docker.cmd
Linux / macOS — sh start.sh sh scripts/docker-start.sh

W przypadku metod opartych na kodzie źródłowym pobierz i rozpakuj bieżącą gałąź main lub sklonuj repozytorium:

git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness

Skrypt Start.cmd proponuje instalację Pythona 3.12 dla użytkownika systemu Windows, jeśli nie zostanie znaleziony odpowiedni Python (przez winget lub podpisany instalator z python.org). Skrypt start.sh wypisuje dokładne polecenie instalacyjne dla danej dystrybucji systemu Linux lub systemu macOS, jeśli brakuje Pythona. Pierwsze uruchomienie ze źródeł automatycznie tworzy środowisko .venv i instaluje zależności.

Docker kompiluje aplikację i uruchamia ją w tle; nie jest wymagane środowisko Python na hostie. Polecenia `scripts\Docker.cmd` i `scripts/docker-start.sh` wyświetlają adres panelu oraz token, gdy kontener działa poprawnie. Odpowiednie polecenia Docker na każdym obsługiwanym hoście to:

docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt

Otwórz stronę http://127.0.0.1:8787. Proszę użyć tokenu wygenerowanego przez narzędzie pomocnicze Docker lub drugiego polecenia Docker, albo odczytać plik data/live/panel-token.txt w przypadku instalacji przenośnej lub źródłowej. Proszę przejść do sekcji „Połącz z Telegramem” poniżej. Instalacje natywne i w środowisku Docker korzystają z oddzielnych przestrzeni dyskowych; uruchomienie Docker nie powoduje zaimportowania istniejącego dziennika z instalacji natywnej.

W przypadku serwera wdrożenie obejmuje automatyczne włączenie protokołu HTTPS, restart, publikowane obrazy, aktualizacje oraz kopie zapasowe.

Zapoznaj się z interfejsem#

  1. Należy uruchomić plik „TgWitness-Demo.cmd” w pakiecie przenośnym, „scripts\Demo.cmd” w folderze źródłowym systemu Windows lub „sh start.sh --demo ” w systemie Linux/macOS. Uruchomienie z folderu źródłowego powoduje najpierw utworzenie pliku „.venv ” oraz zainstalowanie zależności.
  2. Otwórz stronę http://127.0.0.1:8787.
  3. Lokalna wersja demonstracyjna automatycznie otwiera przykładowy dziennik. Do bezpośredniego dostępu lokalnego nie jest wymagana kopia tokenu.

Wiadomości demonstracyjne są fikcyjne. Tryb demonstracyjny nie umożliwia połączenia z prawdziwym kontem w Telegramie.

Połącz się z Telegramem#

[!OSTRZEŻENIE] Należy korzystać z dedykowanych kont. Telegram może ograniczyć lub trwale zablokować konta z powodu ilości żądań, które uzna za nadmierną, niezależnie od klienta. Należy podłączać konta przeznaczone do obserwacji, a nie konta osobiste lub cenne, oraz utworzyć identyfikator API / skrót na dedykowanym koncie.

  1. Jeśli uruchomiona jest natywna wersja demonstracyjna, należy ją zatrzymać i uruchomić plik Start.cmd lub sh start.sh. W przeciwnym razie należy pozostawić uruchomioną instalację na żywo, o której mowa powyżej.
  2. Użyj tokenu panelu, aby się zalogować. Otworzy się nowy obszar roboczy z opcjami pierwszej konfiguracji. Wybierz opcję Tylko pobierz, Śledź czaty lub Dowody dla danej sprawy.
  3. Sprawdź test połączenia. W razie potrzeby skonfiguruj własny serwer proxy; ustawienia połączenia pozostają dostępne po zakończeniu konfiguracji.
  4. W aplikacji Connect Telegram proszę wybrać numer telefonu, kod QR, pliki konta (TData, .session, StringSession, plik JSON konta) lub kompletny klucz autoryzacyjny. Po wyświetleniu prośby proszę wprowadzić potwierdzenie z aplikacji Telegram, kod oraz hasło do uwierzytelniania dwuetapowego.
  5. Sprawdź wyświetlone konto, wybierz czaty i przejrzyj ustawienia. Zakończ z ostatniego ekranu. W przypadku opcji Tylko pobierz przycisk Rozpocznij eksport uruchamia jednorazowy eksport i otwiera okno Eksporty, aby pokazać jego postęp; nie włącza to ciągłej obserwacji.

Po skonfigurowaniu opcja Czaty → Wybierz zmienia wybrane czaty. Ustawienia kontrolują gromadzenie danych i pliki; opcja Więcej narzędzi → Źródła udostępnia szczegółową listę źródeł na poziomie standardowym lub eksperckim. Przewodnik po panelu opisuje sześć głównych sekcji i ich elementy sterujące kontekstowe.

API ID + Hash jest opcjonalne: obszar roboczy wykorzystuje zapisaną lub zaimportowaną parę, lub parę roboczą z wbudowanej puli. Aby użyć własnej aplikacji, wklej jedną parę API ID:API Hash do pola API ID. W polu Auth key wklej wszystkie 512 znaków szesnastkowych i wybierz podany identyfikator DC. Identyfikator użytkownika jest opcjonalny i zostanie sprawdzony, jeśli zostanie wprowadzony.

Dane uwierzytelniające API identyfikują Państwa aplikację; same w sobie nie uprawniają one do korzystania z konta. Grupy prywatne nie wymagają publicznej nazwy użytkownika, jednak Państwa konto musi posiadać do nich dostęp.

W przypadku istniejących kont zapoznaj się z formatami kont i sesji: panel obsługuje Telethon StringSession, Telethon/Pyrogram SQLite, pliki ZIP z danymi TData dla pojedynczego konta oraz obsługiwane pliki JSON z danymi konta. Wybierz sesję wraz z towarzyszącym jej plikiem JSON, naciśnij Sprawdź pliki, a następnie Połącz konto. Dostępne jest również logowanie za pomocą kodu QR z tymi samymi opcjonalnymi ustawieniami API. TDLib, sesje botów oraz wykazy kont w formacie CSV/JSON nie są obsługiwane.

W przypadku kilku kont użyj opcji Konta → Importowanie kont i wybierz obsługiwane pliki sesji. Towarzyszące pliki JSON są parowane na podstawie nazwy bazowej; każde zaimportowane konto otrzymuje własny obszar roboczy. Zobacz import zbiorczy i grupy kont.

Aby dodać kolejne konto, naciśnij przycisk + obok selektora kont lub skorzystaj z opcji Konta → Dodaj konto. Obszary robocze mają oddzielne sesje, dzienniki, klucze, źródła i kolejki. Przełączanie widoków nie powoduje zatrzymania działania pozostałych kolektorów. To samo konto Telegram nie może być przypisane do dwóch obszarów roboczych w tej instalacji. Nie ma ustalonej liczby obszarów roboczych; współdzielą one jeden proces, więc ich wydajność zależy od komputera.

Token panelu na żywo zabezpiecza dostęp do Państwa uprawnień w Telegramie oraz zapisanych materiałów; jest on odrębny od danych uwierzytelniających do API serwisu Telegram. Tylko wyraźnie uruchomiona, bezpośrednio dostępna lokalna wersja demonstracyjna otrzymuje automatyczny wpis. Wersja demonstracyjna zdalna lub korzystająca z serwera proxy nadal wykorzystuje token data/demo/panel-token.txt.

Przeglądanie i eksportowanie#

  • Dziennik: wyszukiwanie i filtrowanie obserwacji według źródła i typu zdarzenia.
  • Proszę wybrać zdarzenie, aby sprawdzić jego oryginalny zapis, informacje o autorstwie oraz zapisane wersje.
  • Szczegóły edycji pokazują treść przed i po zmianie. Szczegóły usunięcia pokazują ostatnią zarejestrowaną treść, o ile taka istnieje; tożsamość nieznanego podmiotu pozostaje nieznana.
  • Formaty eksportu: podpisane pliki ZIP, JSONL, CSV oraz HTML do użytku offline.
  • Pełny eksport czatu (Czaty → Eksportuj czat lub Eksporty → Przechwytuj lub eksportuj jeden czat): pobierz całą widoczną historię jednego czatu jako podpisany pakiet zawierający plik chat.json (w stylu eksportu Telegramu) oraz czytelny plik chat.html. Czaty prywatne działają, gdy konto jest członkiem grupy. Jest to aktualna migawka, a nie rekonstrukcja usuniętych lub wcześniej edytowanych wiadomości. Zweryfikuj kopię za pomocą polecenia python verify.py chat-export.zip --fingerprint TRUSTED_SHA256.
  • Punkt kontrolny: należy zachować granicę podpisanego dziennika poza kolektorem.
  • Pobierz podpisane potwierdzenie uruchomienia: zachowaj zapis dotyczący programu i wersji narzędzia zbierającego dane.
  • Przygotowanie żądania znaku czasu: należy przygotować żądanie offline skierowane do serwisu generującego znaki czasu; należy postępować zgodnie z instrukcją zawartą w pliku TIMESTAMP.md w celu uzyskania i zweryfikowania odpowiedzi.
  • Weryfikacja dziennika: sprawdzenie podpisów zdarzeń i ogniw łańcucha. Eksport do pliku ZIP obejmuje również pliki multimedialne.

Obsługiwane przeglądarki zapisują duże pliki eksportowe bezpośrednio do wybranego pliku. Inne przeglądarki buforują maksymalnie 128 MiB. Gdy serwer działa, interfejs CLI do strumieniowego przesyłania danych obsługuje większe pliki do pobrania bez konieczności buforowania całej odpowiedzi:

python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

Aby dodać inny obszar roboczy, należy użyć opcji --profile ID, korzystając z menu Eksportuj → Identyfikator obszaru roboczego. W przypadku serwera zdalnego należy dodać opcję --url https://your-server. Domyślny limit transferu wynosi 5 GiB; opcja --max-mib pozwala go zmienić. Podpisana zawartość pliku ZIP ma domyślnie oddzielny limit weryfikacji wynoszący 4 GiB w postaci nieskompresowanej (opcja Więcej narzędzi → Parametry pozwala go zwiększyć; archiwa takie należy weryfikować za pomocą verify.py --max-gib N). Archiwum należy zweryfikować przy użyciu zaufanej kopii weryfikatora, niezależnie przechowywanego odcisku klucza oraz, jako minimum wymagane do celów dowodowych, certyfikatu głównego urzędu czasoprzestrzennego (--tsa-ca).

Sprawdź instrukcję instalacji#

python start.py --setup-only
python start.py --check
python start.py --check --json

--check sprawdza lokalne zależności, obsługę podpisywania, pamięć masową, konfigurację kluczy oraz adres nasłuchujący. Nie instaluje żadnych elementów ani nie łączy się z Telegramem. Zajęty port może oznaczać, że działa inna instancja. Proszę użyć innego --port lub najpierw ją zatrzymać.

Program uruchamiający instaluje się w katalogu .venv. Polecenia pomocnicze python -m tgwitness... muszą korzystać z .venv\Scripts\python.exe w systemie Windows lub .venv/bin/python w systemach Linux/macOS, o ile dane środowisko nie zostało już aktywowane.

Sesje, zabezpieczenia i działanie#

Zamknięty, spójny plik Telethon SQLite .session można przekonwertować lokalnie za pomocą polecenia python -m tgwitness.sessions account.session --out account.tgwitness-session, a następnie załadować w sekcji Więcej narzędzi → Konto → Pliki. Dostępne są również bezpośredni import plików oraz logowanie za pomocą kodu QR. Informacje na temat formatów logowania, SOCKS5, HTTP CONNECT, MTProxy oraz zewnętrznych kluczy głównych można znaleźć w pliku CONNECTION-SECURITY.md.

Wstrzymanie obserwacji powoduje zatrzymanie gromadzenia danych. Zablokowanie ogranicza jedynie dostęp przez przeglądarkę. Zamknięcie karty nie powoduje zakończenia działania procesu gromadzenia danych. Zatrzymanie procesu przerywa gromadzenie danych; migawka historii nie pozwala na odtworzenie wszystkich pominiętych edycji lub usunięć. Zapoznaj się z zasadami działania gromadzenia danych w odniesieniu do reguł zdarzeń, kolejek załączników, izolacji kont oraz zachowania przy ponownym uruchomieniu.

Sesje i sekrety są szyfrowane. Treść wiadomości, multimedia i eksporty wymagają zaszyfrowanego dysku lub woluminu. Należy zweryfikować podpisy dziennika względem zaufanego klucza i przechowywać punkty kontrolne oddzielnie. Należy przejrzeć zapisy przechwyconych danych, zewnętrzne potwierdzenia czasu oraz poświadczenia środowiska dla wybranego trybu gromadzenia danych.

Proszę zapoznać się z plikiem OPERATIONS.md w sprawie tworzenia kopii zapasowych i przywracania danych, z plikiem DEPLOYMENT.md w sprawie hostingu oraz z katalogiem deploy/ zawierającym przykłady usług. Zainstalowany panel zawiera również przewodnik po konfiguracji w trybie offline dostępny pod adresem /guide.html.

Rzeczywisty stan weryfikacji oraz pozostałe ograniczenia zostały opisane w plikach VERIFICATION.md i READINESS.md.