tgscope

Telegram OSINT, raspagem e arquivamento.
Um aplicativo web local que roda inteiramente na sua máquina e fala apenas com o Telegram.

npm install
npm start

Em seguida, abra http://127.0.0.1:5173. A primeira execução orienta você nas credenciais da API, no login por QR e no carregamento dos seus diálogos. O Telegram é o único servidor com o qual ele fala. Não há conta para criar, nem telemetria, nem serviço no meio: o que você coleta fica em um arquivo SQLite que pertence a você.

Sucessor de telegram-scraper, telescope e Harrier, construído sobre o Telethon 1.44.

O que ele faz

Coletar

• Cada canal, grupo, tópico de fórum e chat, em todas as contas conectadas, em uma árvore selecionável com o id -100 completo ao lado do nome e um selo para a conta que o enxerga
• Cada diálogo é coletado na conta que de fato pode lê-lo, então uma seleção que abrange duas contas inicia uma execução por conta
• Mensagens com metadados completos: visualizações, encaminhamentos, reações, datas de edição, álbuns, enquetes, geo, links, cadeias de respostas, autores de postagens e a origem do encaminhamento de cada mensagem
• Grupos de fórum divididos por tópico — colete tópicos individuais em vez de grupos inteiros
• Mídia baixada em paralelo e deduplicada por SHA-256 e id de arquivo do Telegram, para que um arquivo encaminhado para cinco canais seja armazenado uma única vez
• Retoma a partir de um marcador por diálogo; o modo contínuo verifica novamente em um intervalo
• Coleções salvas reexecutam uma seleção com um clique

Investigar

• Consulte um número de telefone, @username, id de usuário ou link t.me
• Bio, flags, precisão do último visto como indicador de privacidade, chats em comum, canal pessoal
• Qualquer coisa que o Telegram escolha revelar sobre a conta: o mês em que foi registrada, o país ao qual o número de telefone pertence, quando a pessoa mudou o próprio nome ou trocou a foto, o temporizador de exclusão automática, o nome mostrado em encaminhamentos restritos. Fique ciente de que ele normalmente não revela nada disso. Esses campos vêm junto com o painel antifraude que o Telegram mostra quando um estranho escreve para você, e retornam vazios para um perfil que você consulta diretamente, portanto trate-os como um bônus em vez de algo em torno do qual planejar
• Contas comerciais de fato fornecem endereço físico, coordenadas e fuso horário
• Todas as fotos de perfil visíveis, com hash SHA-256 e hash perceptual, exibidas como uma galeria
• Hashes perceptuais são comparados entre contas, então a mesma imagem em um segundo perfil vem à tona
• Os remetentes de mensagens são registrados conforme são coletados, então um nome no navegador é um link funcional para uma consulta mesmo quando a pessoa não tem nome de usuário; "Sync members" preenche isso para tudo o que foi coletado anteriormente
• Toda consulta é capturada em um instantâneo e comparada (diff): mudanças de nome de usuário, mudanças de nome de exibição, edições de bio, fotos adicionadas ou removidas, privacidade alterada

Exportar

Requisitos

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

npm install cria o ambiente Python em server/.venv e instala os dois lados.

Onde as coisas ficam

Um único banco de dados contém tudo, e é isso que torna possíveis a pesquisa entre diálogos, a tabela compartilhada de usuários, a deduplicação de mídia e o grafo de encaminhamento.

Estrutura da mídia

Os arquivos são organizados por tipo de diálogo, depois diálogo, depois tópico de fórum, depois tipo de mídia:

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

Os nomes de diretórios combinam o identificador (handle) com o id completo, títulos não ASCII são transliterados e os nomes de arquivo são preenchidos com zeros para que sejam ordenados cronologicamente.

Limites de taxa e segurança da conta

Cada chamada ao Telegram passa por um controlador por conta com um token bucket e backoff de FloodWait, e cada leitura paginada — mensagens, diálogos, membros, fotos de perfil — espera um flood passar e é retomada em vez de falhar a execução. Três perfis:

Esperas mais longas são anunciadas no log de atividade e aguardadas; doze seguidas em uma leitura fazem o processo desistir e reportar isso.

Várias contas são suportadas. Marque uma como burner nas Configurações e as consultas de telefone serão executadas nela automaticamente, porque essa é a única operação arriscada:

Uma consulta de telefone importa o número como contato por um instante e o exclui em seguida. Se o dono já tiver seu número salvo, ele poderá ver uma notificação de "entrou no Telegram". O tgscope pergunta primeiro, todas as vezes, e o cartão do perfil registra qual conta foi usada.

Desenvolvimento

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

O backend é FastAPI sobre um núcleo Telethon, testado contra um cliente Telethon falso: o scraper, os exportadores, a estrutura da mídia e cada migração de esquema. Os testes do frontend cobrem a lógica pura por trás do navegador, aritmética de períodos, agrupamento em histogramas e a formatação de números e timestamps, e renderizam cada tela duas vezes, uma vazia e uma preenchida.

scripts/demo/ regenera docs/preview.gif a partir de dados falsos pré-carregados. Ele requer chromium e ffmpeg, não toca em nada no seu workspace real e não faz parte do aplicativo.

O código-fonte não traz comentários — a nomenclatura e a estrutura carregam o significado, e um teste garante isso.

Aspectos legais

Para pesquisa, jornalismo e investigações autorizadas. Ele usa a API oficial do Telegram por meio do Telethon e lê apenas o que sua conta já pode ver — não contorna as configurações de privacidade de ninguém. Não o use para assédio ou perseguição, respeite os termos de serviço do Telegram e observe a lei de proteção de dados que se aplica a você.

Licença MIT.