tgscope

OSINT, scraping e archiviazione per Telegram.
Una web app locale che funziona interamente sulla tua macchina e comunica solo con Telegram.

npm install
npm start

Poi apri http://127.0.0.1:5173. Al primo avvio vieni guidato attraverso le credenziali API, un accesso tramite QR e il caricamento dei tuoi dialoghi. Telegram è l'unico server con cui comunica. Non c'è nessun account da creare, nessuna telemetria e nessun servizio intermedio: ciò che raccogli resta in un file SQLite di tua proprietà.

Successore di telegram-scraper, telescope e Harrier, basato su Telethon 1.44.

Raccogli	Canali, gruppi e argomenti dei forum su più account, con media, deduplicazione e ripresa
Indaga	Numero di telefono, @username, id o link t.me per un profilo, ogni foto storica e un diff rispetto all'ultima volta
Esporta	Dieci formati, da un semplice CSV a un bundle di prove con hash
Funziona su	Node 18+, Python 3.12+, SQLite. Un database, una cartella, nessun servizio

Cosa fa

Raccogli

• Ogni canale, gruppo, argomento di forum e chat, su ogni account connesso, in un unico albero selezionabile con l'id completo -100 accanto al nome e un badge per l'account che lo vede
• Ogni dialogo viene raccolto sotto l'account che può effettivamente leggerlo, quindi una selezione che abbraccia due account avvia un'esecuzione per account
• Messaggi con metadati completi: visualizzazioni, inoltri, reazioni, date di modifica, album, sondaggi, geo, link, catene di risposte, autori dei post e la fonte di inoltro di ogni messaggio
• Gruppi forum suddivisi per argomento — raccogli singoli argomenti anziché interi gruppi
• Media scaricati in parallelo e deduplicati tramite SHA-256 e file id di Telegram, così un file inoltrato a cinque canali viene memorizzato una sola volta
• Ripresa da un watermark per dialogo; la modalità continua ricontrolla a intervalli
• Le raccolte salvate rieseguono una selezione con un clic

Indaga

• Cerca un numero di telefono, @username, id utente o link t.me
• Bio, flag, precisione dell'ultimo accesso come indicatore di privacy, chat in comune, canale personale
• Qualsiasi cosa Telegram scelga di rivelare sull'account: il mese di registrazione, il paese a cui appartiene il numero di telefono, quando la persona si è rinominata l'ultima volta o ha cambiato foto, il suo timer di auto-eliminazione, il nome mostrato sugli inoltri limitati. Attenzione: di solito non rivela nulla di tutto ciò. Quei campi viaggiano insieme al pannello anti-truffa che Telegram mostra quando uno sconosciuto ti scrive, e tornano vuoti per un profilo che cerchi direttamente, quindi trattali come un bonus anziché qualcosa su cui fare affidamento
• Gli account business forniscono in modo affidabile un indirizzo stradale, coordinate e un fuso orario
• Ogni foto del profilo visibile, con hash SHA-256 e un hash percettivo, mostrata come galleria
• Gli hash percettivi vengono confrontati tra account, così la stessa immagine su un secondo profilo emerge
• I mittenti dei messaggi vengono registrati man mano che vengono raccolti, così un nome nel browser è un link funzionante a una ricerca anche quando la persona non ha un username; "Sync members" lo completa per qualsiasi cosa raccolta in precedenza
• Ogni ricerca viene salvata come snapshot e confrontata: cambi di username, cambi di nome visualizzato, modifiche alla bio, foto aggiunte o rimosse, privacy modificata

Esporta

Formato	Cosa ottieni
csv	Un file per dialogo
json / jsonl	Metadati completi; JSONL trasmette riga per riga
xlsx	Fogli per messaggi, media, partecipanti e reazioni
html	Report autonomo: statistiche, attività, principali mittenti, fonti di inoltro, tabella ricercabile
markdown	Lo stesso report in formato testo
gexf / edges	Grafo degli inoltri per Gephi e Maltego
sqlite	Un database autonomo dei soli dialoghi selezionati
bundle	ZIP con dati, media, un manifest di hash SHA-256 e il log della raccolta

Requisiti

• Node.js 18+
• Python 3.12+
• Credenziali API da my.telegram.org/apps

npm install crea l'ambiente Python sotto server/.venv e installa entrambi i lati.

Dove si trovano le cose

Cosa	Dove
Config	~/.config/tgscope/config.json (modalità 600)
Database	~/.local/share/tgscope/tgscope.db (WAL, FTS5)
Media	~/.local/share/tgscope/media/
Esportazioni	~/.local/share/tgscope/exports/<timestamp>-<label>/

Un unico database contiene tutto, ed è ciò che rende possibili la ricerca trasversale tra dialoghi, la tabella utenti condivisa, la deduplicazione dei media e il grafo dei forward.

Struttura dei media

I file sono organizzati per tipo di dialogo, poi per dialogo, poi per argomento del forum, poi per tipo di media:

media/
├── channels/technews_-1001234567890/
│   ├── photos/00004711-8001-conference-slides.jpg
│   └── documents/00004802-8210-quarterly-report.pdf
├── groups/pythondev_-1009876543210/
│   ├── general/photos/…
│   └── help/voice/00000004-9004-voice.ogg
└── profiles/123456789/000-5544332211.jpg

I nomi delle directory combinano l'handle con l'id completo, i titoli non ASCII vengono traslitterati e i nomi dei file sono riempiti con zeri in modo da ordinarsi cronologicamente.

Limiti di frequenza e sicurezza dell'account

Ogni chiamata a Telegram passa attraverso un governatore per account con un token bucket e un backoff FloodWait, e ogni lettura paginata - messaggi, dialoghi, membri, foto del profilo - attende che un flood si esaurisca e riprende invece di far fallire l'esecuzione. Tre profili:

Profilo	Worker media	Intervallo tra richieste	Attese assorbite silenziosamente
stealth	1	1,6 s	fino a 180 s
balanced	4	0,35 s	fino a 90 s
fast	8	nessuno	fino a 45 s

Le attese più lunghe vengono annunciate nel registro delle attività e attese fino alla scadenza; dodici di fila su una singola lettura fanno desistere e lo segnalano.

Sono supportati più account. Contrassegnane uno come burner nelle Impostazioni e le ricerche per numero di telefono verranno eseguite automaticamente su di esso, perché è l'unica operazione rischiosa:

Una ricerca per numero di telefono importa il numero come contatto per un momento e poi lo elimina di nuovo. Se il proprietario ha già il tuo numero salvato, potrebbe vedere una notifica "si è unito a Telegram". tgscope chiede prima, ogni volta, e la scheda del profilo registra quale account ha utilizzato.

Sviluppo

npm test                    # 92 backend and 42 frontend tests, no network needed
npm run build               # production bundle of the client

Il backend è FastAPI su un core Telethon, testato contro un client Telethon fittizio: lo scraper, gli esportatori, il layout dei media e ogni migrazione dello schema. I test del frontend coprono la logica pura alla base del browser, l'aritmetica dei periodi, il raggruppamento in istogrammi e la formattazione di numeri e timestamp, e renderizzano ogni schermata due volte, una vuota e una popolata.

scripts/demo/ rigenera docs/preview.gif da dati fittizi preimpostati. Richiede chromium e ffmpeg, non tocca nulla nel tuo workspace reale e non fa parte dell'app.

Il codice sorgente non contiene commenti — denominazione e struttura veicolano il significato, e un test lo impone.

Note legali