TgWitness / Documentazione

Cosa è stato testato →

Riferimento / Sicurezza e progetto

Telegram · Sicurezza e trattamento dei dati

Modello di minaccia, modello di accesso, dati sensibili inattivi, esposizione di rete, importazione delle sessioni e modalità di segnalazione di una vulnerabilità.

TgWitness / Documentazione · Implementazione e ripristino

Implementazione e ripristino

Questa pagina descrive l’accesso, l’archiviazione e la protezione della rete in un’area di lavoro locale o su server. Per la raccolta su un GitHub Runner o in una macchina virtuale riservata Intel TDX, consultare le modalità di verifica, che aggiungono controlli sull’ambiente di raccolta. Le connessioni agli account, le notifiche, i timestamp, le copie fuori sede e i testimoni hanno le proprie impostazioni di instradamento.

Area In sintesi
Accesso Chiave amministratore più accesso limitato ad account/chat, sette autorizzazioni e sessioni revocabili; localhost come impostazione predefinita
Segreti inattivi La sessione, la coppia API, la chiave di firma e le impostazioni del proxy sono crittografate con Fernet
Messaggi e contenuti multimediali File nell’area di lavoro, protetti dalla crittografia del disco o del volume e dai permessi sui file dell’host
Integrità Catena di hash SHA-256 e firma Ed25519 su ogni registrazione
Tempo esterno Le ricevute RFC 3161 e OpenTimestamps, i post dei testimoni datati da Telegram e l’attestazione di GitHub; i checkpoint conservati, i record dei testimoni e le misurazioni Intel TDX costituiscono verifiche a supporto. Il verificatore segnala quali condizioni di prova soddisfano

Per le segnalazioni di vulnerabilità, si prega di consultare la politica sulla sicurezza.

In questa pagina

Modello di accesso#

Il token del pannello principale garantisce il controllo completo. Altri utenti possono ricevere un accesso limitato: aree di lavoro e chat selezionate, autorizzazioni, scadenza, restrizioni IP, limiti di accesso e sessioni revocabili. Un accesso limitato a una chat non può eseguire operazioni sull’intera area di lavoro anche se l’autorizzazione è selezionata. Ogni area di lavoro dispone di un proprio registro, un proprio vault e una propria chiave di firma all’interno di un unico processo; la separazione tra gli utenti sull’host deriva dagli account del sistema operativo.

Il pannello è in ascolto su localhost per impostazione predefinita. L’accesso tramite browser scambia un token di accesso con una credenziale di sessione; il browser lo invia come token bearer. Esso viene conservato in sessionStorage anziché in un cookie di autenticazione. Il blocco o la disconnessione cancellano la sessione del browser. La chiusura del browser o la fine della sessione non interrompono la raccolta.

I token emessi e le credenziali di sessione vengono conservati sotto forma di hash nel deposito crittografato. La revoca pone fine alle sessioni associate; le modifiche alle autorizzazioni hanno effetto sulle successive richieste. I file scaricati non possono essere recuperati. L’amministratore può limitare anche le proprie sessioni del browser, ma gli script che utilizzano direttamente il token del pannello principale mantengono l’accesso completo e aggirano tali limiti delle sessioni del browser.

L’autenticazione non riuscita è soggetta a limitazioni di frequenza in base all’indirizzo del client. Le restrizioni IP utilizzano l’ indirizzo rilevato dall’applicazione; si raccomanda di verificare il comportamento del reverse proxy prima di fare affidamento su di esso. Le credenziali di Witness rimangono credenziali separate, di sola lettura, relative a checkpoint e integrità del sistema.

Accesso alla demo#

/api/demo-access è un bootstrap volutamente non autenticato per una demo sintetica isolata e avviata in modo esplicito. Emette una funzionalità separata valida per la durata del processo, mai il token del pannello reale né un override di TGWITNESS_TOKEN. L’emissione e l’utilizzo richiedono un peer di loopback e un host, senza intestazioni inoltrate né richieste cross-origin. Ulteriori spazi di lavoro o una sessione autorizzata disabilitano questo percorso. Gli spazi di lavoro attivi non emettono mai tale capacità. La demo non può collegare account né modificare le impostazioni di raccolta.

Contenuti dei pannelli ed esportazioni#

Il pannello non utilizza font esterni, strumenti di analisi, risorse CDN né contenuti multimediali remoti incorporati. Il testo proveniente da Telegram viene inserito come testo, non come HTML. Gli allegati scaricati vengono forniti come allegati binari. Le esportazioni in formato JSONL conservano le stringhe originali; l’HTML le sostituisce con caratteri di escape; alle celle CSV che potrebbero diventare formule viene anteposto un apostrofo.

Le esportazioni escludono i segreti di autenticazione e firma, ma contengono deliberatamente i metadati di origine raccolti, gli identificatori ed eventualmente contenuti personali o sensibili. Nei metadati di origine non elaborati possono essere presenti hash di accesso a Telegram e riferimenti ai file.

Segreti inattivi#

Le credenziali dell’API di Telegram, la sessione e la chiave di firma sono crittografate con Fernet. Per i messaggi e i file multimediali locali, la crittografia è garantita dal disco o dal volume dell’host; l’area di lavoro memorizza file ordinari. Le esportazioni possono utilizzare un ZIP AES-256 protetto da password, mentre le copie esterne utilizzano AES-256-GCM.

La chiave del vault è impostata di default sulla directory dei dati protetti. Utilizzare un file esterno contenente la chiave principale riportato di seguito per memorizzarla separatamente. Su Unix, i nuovi file delle chiavi private utilizzano la modalità 0600 e le nuove directory dei dati utilizzano la modalità 0700; su Windows, impostare gli ACL della directory per l’account di servizio e gli amministratori autorizzati. I permessi esistenti della directory vengono mantenuti.

Chiave master esterna#

Per una nuova directory dei dati, TGWITNESS_VAULT_KEY_FILE può fornire una chiave master casuale esterna. HKDF-SHA256 e un salt casuale separato generano una chiave Fernet diversa per ogni area di lavoro. Il file vault.external.json deve essere conservato per il ripristino. Chiavi master mancanti o errate causano un errore di chiusura. I vault locali esistenti non vengono migrati in modo silenzioso. Il pannello visualizza la modalità di archiviazione delle chiavi selezionata. La crittografia del disco protegge i file di messaggi e multimediali locali in entrambe le modalità; per i dettagli sulla configurazione, consultare connessione e protezione dei dati.

Proxy e percorsi di rete#

La configurazione del proxy è crittografata nel vault. Le password e i segreti di MTProxy non vengono restituiti dall’API né registrati nei registri delle prove. Ogni area di lavoro sceglie il proprio percorso Telegram e una modalità IP.

L'opzione "Nascondi l'indirizzo" disabilita il fallback diretto su Telegram e richiede un proxy per le richieste HTTP esterne. La modalità fallback selezionata esplicitamente consente l'accesso diretto a Telegram dopo un certo ritardo; la modalità tunnel/VPN consente percorsi diretti. La scelta della modalità tunnel non comporta l'installazione né la verifica di una VPN. Queste impostazioni non controllano tutto il traffico del computer, i browser, i gestori di pacchetti o la risoluzione DNS dell'host proxy locale.

MTProxy gestisce esclusivamente il traffico Telegram. Le richieste esterne possono avvalersi di un proxy SOCKS5/HTTP separato, del percorso SOCKS5/HTTP dell’area di lavoro o di un percorso diretto autorizzato; in alternativa, possono essere disabilitate. Il witness indipendente dispone di proprie impostazioni di trasporto. La normale autenticazione SOCKS5/HTTP CONNECT non è crittografata dai protocolli proxy stessi. I segreti TLS falsi di MTProxy non sono ancora supportati.

Accesso e importazione delle sessioni#

I file .tgwitness-session convertiti contengono una chiave di autorizzazione in testo chiaro fino a quando non vengono caricati e archiviati nel vault. L’interfaccia CLI offline accetta schemi Telethon revisionati. L’importazione tramite pannello accetta inoltre Pyrogram SQLite, il moderno formato ZIP TData a account singolo e input JSON documentati. È autenticata, limitata a quattro file / 8 MiB, ed elabora i caricamenti in memoria senza estrazione dell’archivio né salvataggio dei file originali. Le credenziali normalizzate vengono restituite esclusivamente al browser autenticato richiedente; vengono salvate nel vault crittografato dopo l’autorizzazione riuscita su Telegram. Protegga i file originali e quelli convertiti ed eviti che client concorrenti clonino un’autorizzazione.

L’elaborazione dei dati verifica i checksum dei contenitori, gli hash di decrittografia locale e le lunghezze delle strutture. Un codice di accesso locale fornito per la versione Desktop viene utilizzato temporaneamente e non viene memorizzato. Il parser limitato supporta i formati Desktop che convalida e rifiuta gli altri. Le immagini QR vengono generate localmente, contengono token di accesso a Telegram di breve durata e non vengono mai inviate a un servizio di rendering esterno. Il blocco, il cambio di area di lavoro, un nuovo accesso e le modifiche al percorso annullano i tentativi QR in sospeso. Il ricaricamento o la chiusura di una scheda può lasciare un tentativo in sospeso fino alla scadenza. Un accesso tramite QR riuscito impone comunque il vincolo dell’account. I corpi delle API ordinarie rimangono limitati a 16 KiB; il percorso di importazione autenticato accetta fino a 12 MiB di JSON codificato, applicando separatamente il limite più basso per il file decodificato.

I codici di accesso e le password di verifica in due passaggi di Telegram non vengono memorizzati in modo permanente. Lo stato del numero di telefono o dell’hash del codice viene mantenuto in memoria durante l’autorizzazione. Le sessioni di Telegram consentono l’accesso all’account; non caricare mai su GitHub una directory di dati, una sessione, un token, una chiave del vault o una chiave di firma privata.

Registri e trasmissione#

La risposta predefinita di convalida dell’API viene sostituita in modo che non ripeta i valori delle credenziali. La registrazione degli accessi all’applicazione è disabilitata. Non configurare un proxy inverso per registrare le intestazioni di autorizzazione o i corpi delle richieste. Il pannello è in ascolto su localhost; l’accesso remoto passa attraverso il tunnel SSH fornito, Cloudflare Tunnel o Caddy HTTPS, quindi i token e le chiavi di accesso viaggiano all’interno di SSH o TLS.

Integrità e tempo esterno#

I controlli di verifica confrontano le firme dei record, la catena di hash, gli allegati e il manifesto di esportazione con la chiave del collettore. Una firma valida indica che i byte non sono stati modificati da quando sono stati firmati. Ogni area di lavoro crea la propria chiave di firma al primo avvio e mostra la propria impronta digitale nel pannello e in ogni esportazione. L’operatore comunica l’impronta digitale al destinatario tramite un canale separato e --fingerprint blocca la chiave.

Un record modificato, inserito o rimosso interrompe la catena di hash o una firma, e il verificatore lo segnala. I timestamp esterni e un “witness” fissano inoltre il journal al di fuori dell’ area di lavoro. I trigger SQLite sulla tabella del journal impediscono semplicemente all’applicazione di sovrascrivere o cancellare un record per errore. TGWITNESS_VAULT_KEY_FILE mantiene la chiave del vault al di fuori di una copia della directory dei dati.

Le ricevute RFC 3161 e OpenTimestamps, nonché i post dei testimoni le cui date vengono lette dal verificatore su Telegram, collegano il prefisso del giornale che coprono a un’ora stabilita da una terza parte. Un round drand inserito nel giornale dimostra che i record successivi ad esso sono stati creati non prima della pubblicazione di quel round. Anche un’attestazione GitHub verificata riporta l’ora verificata della propria firma, che collega l’intero archivio a un’ora esterna. Un checkpoint viene firmato con la chiave del collettore e vincola i record fino a quel momento a partire dal momento in cui il destinatario lo ha ottenuto, tramite un altro canale. Un testimone dimostra che una seconda chiave ha conservato l’intestazione del giornale; il record di controllo delle chiavi del custode indica chi detiene quella chiave. Entrambi sono controlli di supporto; il requisito minimo è l’ora fornita da una terza parte. GitHub Actions o una distribuzione Intel TDX aggiungono la provenienza del flusso di lavoro o le misurazioni hardware dell’ambiente di raccolta.

Ogni risposta di verifica elenca le condizioni delle prove indicando come ciascuna è stata verificata, raggruppate in base al loro ruolo nel minimo:

Ruolo Condizione
Obbligatorio Integrità; chiave del firmatario fissata con --fingerprint; data e ora esterne relative all’ultimo record (ricevuta RFC 3161 verificata con --tsa-ca, ricevuta OpenTimestamps confermata con --check-bitcoin, post del testimone letto da t.me con --channel, sigillo Bitcoin del testimone o attestato GitHub verificato)
Funzionalità aggiuntive, non incluse nel minimo richiesto Testimone con chiave propria; checkpoint conservato; esecuzione della raccolta attestata

Il requisito minimo per la prova consiste nel soddisfacimento di tutte e tre le condizioni richieste relative all’ultimo record esportato; un ciclo di raccolta verificato e certificato aggiunge il attested profilo. L'ultima riga riporta il risultato e la risposta indica le opzioni che soddisferebbero le condizioni mancanti. Senza --fingerprint la riga finale inizia con EVIDENCE: minimum not met · missing: confirmed signer key. Quando i timestamp verificati coprono solo i record precedenti, la risposta indica il record fino al quale vale il requisito minimo. --require evidence oppure --require attested termina con il codice 2 quando il profilo non viene raggiunto per l’intera esportazione, e un controllo richiesto sulla riga di comando che non può essere eseguito viene segnalato come non effettuato con lo stesso codice. Ogni rapporto riporta le stesse condizioni con il loro stato in quella copia e il comando che le verifica . I livelli di garanzia e --strict rimangono disponibili; il formato delle prove elenca i controlli per ciascuna modalità di raccolta.

Se sospetta un problema#

Mantenere la directory dei dati originale e utilizzare una copia separata per l’analisi. Segnalare la versione interessata, l’operazione e i passaggi riproducibili tramite la politica di sicurezza, mantenendo riservati i dati dell’account e le credenziali.