TgWitness / Documentazione

Cosa è stato testato →

Riferimento / Configurazione

Telegram · Guida rapida

Tutte le modalità di installazione e avvio di TgWitness: pacchetto per Windows, Python, Docker e la demo sintetica, con i primi controlli.

TgWitness / Documentazione

Introduzione

Inglese · Русский · Ucraino · Español · Portoghese (Brasile) · Türkçe · العربية · فارسی · Urdu · Hindi · Bahasa Indonesia · Tiếng Việt · Cinese semplificato

TgWitness è un’applicazione autonoma per il monitoraggio dei gruppi e dei canali di Telegram a cui i vostri account possono accedere. Funziona in locale con una propria directory di dati.

È la tua prima visita? Esplora la demo prima di collegare un account. Scegli una guida per proxy, testimoni, esportazioni o configurazione del server. GitHub Actions capture (anteprima) esegue un’acquisizione nel tuo fork GitHub invece che in un’installazione locale.

Installazione e avvio#

Il programma di installazione guidata include la propria versione di Python e verifica gli hash dei pacchetti e le firme di rilascio prima dell’installazione. Eseguendolo nuovamente si aggiorna un’installazione esistente.

Linux / macOS:

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

Windows (PowerShell o Prompt dei comandi):

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

Su un server Ubuntu, eseguire come root per installare un servizio in background; su un desktop, eseguire come utente normale. Su Ubuntu il programma di installazione visualizza l’indirizzo del pannello e la chiave di accesso; su macOS e Windows il pannello locale si apre nel browser. Proseguire alla sezione Connetti Telegram qui sotto. La sezione Installa, verifica e aggiorna tratta le opzioni di accesso al server, la verifica dello script prima dell’esecuzione, gli aggiornamenti e la rimozione.

Altri metodi#

Le versioni su GitHub, il codice sorgente e Docker sono alternative al programma di installazione. I download portatili diventano disponibili dopo la pubblicazione di una build di rilascio:

Host Nessuna installazione richiesta Dalla fonte: Python 3.11+ Docker: Engine/Desktop con Compose 2.20+
Windows Estrarre TgWitness-<version>-windows-amd64-portable.zip dai rilasci di GitHub, fare doppio clic su TgWitness.cmd Fare doppio clic su Start.cmd Fare doppio clic su scripts\Docker.cmd
Linux / macOS — sh start.sh sh scripts/docker-start.sh

Per i metodi basati sul codice sorgente, scarica ed estrai il ramo main corrente oppure clona il repository:

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

Start.cmd propone di installare Python 3.12 per il tuo utente Windows se non viene trovato un Python adatto (tramite winget o il programma di installazione firmato di python.org). start.sh mostra il comando di installazione esatto per la tua distribuzione Linux o macOS se Python è assente. Il primo avvio da sorgente crea .venv e installa automaticamente le dipendenze.

Docker compila l’applicazione e la avvia in background; non è necessario un host Python. scripts\Docker.cmd e scripts/docker-start.sh visualizzano l’indirizzo del pannello e il token quando il container è in stato di funzionamento. I comandi Docker equivalenti su ogni host supportato sono:

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

Apra http://127.0.0.1:8787. Utilizzi il token generato dall’helper di Docker o dal secondo comando Docker, oppure consulti il file data/live/panel-token.txt per un’installazione portatile o dal codice sorgente. Prosegua alla sezione «Connetti Telegram» qui sotto. Le installazioni native e Docker utilizzano archivi separati; l’avvio di Docker non importa un registro nativo esistente.

Per quanto riguarda il server, l’implementazione comprende l’HTTPS automatico, il riavvio, le immagini pubblicate, gli aggiornamenti e i backup.

Esplorate l’interfaccia#

  1. Eseguire TgWitness-Demo.cmd nel pacchetto portatile, scripts\Demo.cmd in una cartella sorgente di Windows oppure sh start.sh --demo su Linux/macOS. L’esecuzione dal sorgente crea innanzitutto .venv e installa le dipendenze.
  2. http://127.0.0.1:8787 aperto.
  3. La demo locale apre automaticamente il registro di esempio. Non è necessaria alcuna copia del token per l’accesso locale diretto.

I messaggi di dimostrazione sono fittizi. La modalità demo non consente di collegare un account Telegram reale.

Collegare Telegram#

[!AVVISO] Utilizzare account dedicati. Telegram può limitare o bannare definitivamente gli account per volumi di richieste che ritiene eccessivi, indipendentemente dal client. Collegare account predisposti per l’ osservazione anziché quelli personali o di valore, e creare un ID API / hash su un account dedicato.

  1. Se la demo nativa è in esecuzione, la interrompa ed esegua Start.cmd o sh start.sh. In caso contrario, mantenga in esecuzione l’installazione live avviata in precedenza.
  2. Utilizza il token del pannello per effettuare l’accesso. Si aprirà un nuovo spazio di lavoro per la configurazione iniziale. Scegli Solo download, Segui chat o Prove per un caso.
  3. Verificare il controllo della connessione. Se necessario, configurare il proprio proxy; le impostazioni di connessione rimangono disponibili dopo la configurazione.
  4. In Connect Telegram, selezionare un numero di telefono, un codice QR, i file dell’account (TData, .session, StringSession, JSON dell’account) oppure una chiave di autorizzazione completa. Completare la conferma di Telegram, il codice e la password di autenticazione a due fattori quando richiesto.
  5. Verifica l’account visualizzato, seleziona le chat e controlla le tue impostazioni. Completa dalla schermata finale. Per l’opzione Solo download, Avvia esportazione avvia un’esportazione una tantum e apre la sezione Esportazioni per mostrarne lo stato di avanzamento; non attiva il monitoraggio continuo.

Dopo la configurazione, la voce Chats → Scegli modifica le chat selezionate. Le impostazioni controllano la raccolta e i file; Altri strumenti → Fonti fornisce l’elenco dettagliato delle fonti a livello Standard o Esperto. La guida al pannello descrive le sei sezioni principali e i relativi controlli contestuali.

L’ID API + Hash è facoltativo: l’area di lavoro utilizza la coppia salvata o importata, oppure una coppia funzionante dal pool integrato. Per utilizzare la propria app, incollare una coppia API ID:API Hash nel campo ID API. Per la chiave di autenticazione, incollare tutti i 512 caratteri esadecimali e selezionare l’ID DC fornito. L’ID utente è facoltativo e viene verificato se inserito.

Le credenziali API identificano la vostra applicazione; di per sé non autorizzano un account. I gruppi privati non richiedono un nome utente pubblico, ma il vostro account deve disporre dei diritti di accesso.

Per gli account esistenti, consultare i formati degli account e delle sessioni: il pannello accetta Telethon StringSession, Telethon/Pyrogram SQLite, TData ZIP a account singolo e JSON degli account supportati. Selezionare insieme una sessione e il relativo file JSON, premere Verifica file, quindi Connetti account. È disponibile anche l’accesso tramite QR con le stesse impostazioni API opzionali. TDLib, le sessioni bot e gli inventari degli account in formato CSV/JSON non sono supportati.

Per più account, usa Account → Importazione degli account e seleziona i relativi file di sessione supportati. I file JSON associati vengono abbinati in base al nome base; ogni account importato ottiene il proprio spazio di lavoro. Consulta importazione in blocco e gruppi di account.

Per aggiungere un altro account, premere il segno + accanto al selettore degli account oppure utilizzare Account → Aggiungi account. Gli spazi di lavoro dispongono di sessioni, giornali, chiavi, fonti e code separate. Il cambio di vista lascia in esecuzione gli altri collettori. Lo stesso account Telegram non può essere assegnato a due spazi di lavoro in questa installazione. Non esiste un numero fisso di spazi di lavoro; essi condividono un unico processo, pertanto la capacità dipende dalla macchina.

Il token del pannello live protegge l’accesso alle vostre autorizzazioni Telegram e al materiale salvato; è separato dalle credenziali dell’API di Telegram. Solo una demo locale avviata esplicitamente e a cui si accede direttamente ottiene l’accesso automatico. Una demo remota o tramite proxy continua a utilizzare data/demo/panel-token.txt.

Revisione ed esportazione#

  • Registro: ricerca e filtraggio delle osservazioni in base alla fonte e al tipo di evento.
  • Selezioni un evento per esaminarne la registrazione originale, l’attribuzione e le versioni salvate.
  • I dettagli delle modifiche mostrano i contenuti disponibili prima e dopo. I dettagli delle cancellazioni mostrano l’ ultimo contenuto acquisito, se presente; un autore sconosciuto rimane tale.
  • Formati di esportazione: ZIP firmato, JSONL, CSV e HTML offline.
  • Esportazione completa della chat (Chat → Esporta chat, oppure Esportazioni → Cattura o esporta una chat): scarica l’intera cronologia visibile di una chat come pacchetto firmato contenente chat.json (stile Telegram-export) e un file leggibile chat.html. Le chat private funzionano se l’account è membro. Si tratta di un’istantanea attuale, non di una ricostruzione di messaggi cancellati o modificati in precedenza. Verifica una copia con python verify.py chat-export.zip --fingerprint TRUSTED_SHA256.
  • Punto di controllo: mantenere i confini del registro firmato al di fuori del collettore.
  • Scaricare la ricevuta di esecuzione firmata: conservare la registrazione del programma e della versione del collettore.
  • Preparazione della richiesta di timestamp: preparare una richiesta offline all’autorità di timestamp; seguire le istruzioni contenute nel file TIMESTAMP.md per ottenere e verificare la risposta.
  • Verifica del registro: controllate le firme degli eventi e i collegamenti della catena. L’esportazione in formato ZIP verifica anche i file multimediali.

I browser supportati salvano esportazioni di grandi dimensioni direttamente in un file a scelta. Gli altri browser memorizzano nel buffer al massimo 128 MiB. Mentre il server è in esecuzione, la CLI di streaming supporta download di dimensioni maggiori senza memorizzare l’intera risposta nel buffer:

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

Per un altro spazio di lavoro, aggiungere --profile ID utilizzando Esportazioni → ID spazio di lavoro. Per un server remoto, aggiungere --url https://your-server. Il limite di trasferimento predefinito è di 5 GiB; --max-mib lo modifica. Il contenuto ZIP firmato ha un limite di verifica separato di 4 GiB non compressi per impostazione predefinita (Altre opzioni → Parametri lo aumenta; verificare tali archivi con verify.py --max-gib N). Verificare l’archivio utilizzando una copia attendibile del verificatore, un’ impronta digitale della chiave conservata in modo indipendente e, come requisito minimo per la prova, il certificato radice dell’ autorità di marcatura temporale (--tsa-ca).

Verificare l’installazione#

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

--check verifica le dipendenze locali, il supporto alla firma, lo spazio di archiviazione, la configurazione delle chiavi e l’indirizzo di ascolto. Non installa nulla né si connette a Telegram. Una porta occupata potrebbe indicare che è in esecuzione un’altra istanza. Utilizzi un altro --port oppure interrompa prima l’istanza in corso.

Il programma di avvio si installa in .venv. I comandi ausiliari python -m tgwitness... devono utilizzare .venv\Scripts\python.exe su Windows o .venv/bin/python su Linux/macOS, a meno che tale ambiente non sia già attivato.

Sessioni, protezione e funzionamento#

Una sessione Telethon SQLite chiusa e coerente .session può essere convertita localmente con python -m tgwitness.sessions account.session --out account.tgwitness-session, quindi caricata in Altri strumenti → Account → File. Sono disponibili anche l’importazione diretta dei file e l’accesso tramite codice QR. Vedere CONNECTION-SECURITY.md per i formati di accesso, SOCKS5, HTTP CONNECT, MTProxy e le chiavi master esterne.

La funzione «Pausa osservazione» interrompe la raccolta. La funzione «Blocca» chiude solo l’accesso tramite browser. La chiusura di una scheda lascia in esecuzione il processo di raccolta. L’arresto del processo interrompe la raccolta; un’istantanea della cronologia non è in grado di ricostruire tutte le modifiche o le cancellazioni mancanti. Scoprite come funziona la raccolta in relazione alle politiche sugli eventi, alle code degli allegati, all’isolamento degli account e al comportamento in caso di riavvio.

Le sessioni e i segreti sono crittografati. Il contenuto dei messaggi, i file multimediali e le esportazioni richiedono un disco o un volume crittografato. Verificare le firme del registro rispetto a una chiave attendibile e conservare i checkpoint separatamente. Esaminare i record di acquisizione, le ricevute temporali esterne e le attestazioni ambientali per la modalità di raccolta selezionata.

Si prega di consultare il file OPERATIONS.md per le operazioni di backup e ripristino, il file DEPLOYMENT.md per l’hosting e la directory deploy/ per esempi di utilizzo del servizio. Il pannello installato include inoltre una guida alla configurazione offline all’indirizzo /guide.html.

La verifica effettiva e i limiti rimanenti sono riportati nei file VERIFICATION.md e READINESS.md.