tgscope

OSINT, scraping e arquivamento do Telegram.
Um aplicativo web local que é executado inteiramente na sua máquina e se comunica apenas com o Telegram.

npm install
npm start

Em seguida, abra http://127.0.0.1:5173. A primeira execução guia você pelas credenciais da API, por um login via QR code e pelo carregamento dos seus diálogos. O Telegram é o único servidor com o qual ele se comunica. Não há conta a criar, nem telemetria, nem serviço intermediário: o que você coleta permanece em um arquivo SQLite que pertence a você.

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

Coletar	Canais, grupos e tópicos de fórum em várias contas, com mídia, deduplicação e retomada
Investigar	Telefone, @username, id ou link t.me para um perfil, todas as fotos históricas e um diff desde a última vez
Exportar	Dez formatos, de um CSV simples a um pacote de evidências com hash
Executa em	Node 18+, Python 3.12+, SQLite. Um banco de dados, uma pasta, nenhum serviço

O que ele faz

Coletar

• Todos os canais, grupos, tópicos de fórum e chats, em todas as contas conectadas, em uma árvore selecionável com o id -100 completo ao lado do nome e um selo da conta que o enxerga
• Cada diálogo é coletado sob a conta que realmente consegue 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 resposta, autores de posts 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 pelo file id do Telegram, de modo que um arquivo encaminhado para cinco canais é armazenado uma única vez
• Retomada a partir de uma marca d'água por diálogo; o modo contínuo reverifica em intervalos
• Coletas 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 acesso como indicador de privacidade, chats em comum, canal pessoal
• Qualquer coisa que o Telegram escolha divulgar sobre a conta: o mês em que foi registrada, o país ao qual pertence seu número de telefone, quando a pessoa renomeou a si mesma pela última vez ou trocou sua foto, seu temporizador de exclusão automática, o nome exibido em encaminhamentos restritos. Esteja avisado de que ele normalmente não divulga nada disso. Esses campos acompanham o painel anti-golpe que o Telegram exibe quando um estranho escreve para você, e voltam vazios para um perfil que você consulta diretamente, então trate-os como um bônus em vez de algo com que contar
• Contas comerciais fornecem de forma confiável um endereço, coordenadas e um fuso horário
• Todas as fotos de perfil visíveis, com hash SHA-256 e um hash perceptual, exibidas como uma galeria
• Hashes perceptuais são comparados entre contas, então a mesma imagem em um segundo perfil aparece
• Os remetentes de mensagens são registrados à medida que são coletados, então um nome no navegador é um link funcional para uma consulta mesmo quando a pessoa não tem username; "Sync members" preenche isso para qualquer coisa coletada anteriormente
• Cada consulta é capturada em snapshot e comparada por diff: mudanças de username, mudanças de nome de exibição, edições de bio, fotos adicionadas ou removidas, privacidade alterada

Exportar

Formato	O que você obtém
csv	Um arquivo por diálogo
json / jsonl	Metadados completos; JSONL transmite linha a linha
xlsx	Planilhas para mensagens, mídia, participantes e reações
html	Relatório autônomo: estatísticas, atividade, principais remetentes, origens de encaminhamento, tabela pesquisável
markdown	O mesmo relatório em texto
gexf / edges	Grafo de encaminhamentos para Gephi e Maltego
sqlite	Um banco de dados autônomo apenas dos diálogos selecionados
bundle	ZIP com dados, mídia, um manifesto de hashes SHA-256 e o log de coleta

Requisitos

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

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

Onde as coisas ficam

O quê	Onde
Configuração	~/.config/tgscope/config.json (modo 600)
Banco de dados	~/.local/share/tgscope/tgscope.db (WAL, FTS5)
Mídia	~/.local/share/tgscope/media/
Exportações	~/.local/share/tgscope/exports/<timestamp>-<label>/

Um banco de dados guarda tudo, o que torna possível a busca entre diálogos, a tabela de usuários compartilhada, a deduplicação de mídia e o grafo de encaminhamentos.

Layout de mídia

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

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

Os nomes de diretório combinam o 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

Toda chamada ao Telegram passa por um governador por conta com um token bucket e backoff de FloodWait, e toda leitura paginada - mensagens, diálogos, membros, fotos de perfil - aguarda o fim de um flood e retoma em vez de falhar a execução. Três perfis:

Perfil	Workers de mídia	Intervalo entre requisições	Esperas absorvidas silenciosamente
stealth	1	1,6 s	até 180 s
balanced	4	0,35 s	até 90 s
fast	8	nenhum	até 45 s

Esperas mais longas são anunciadas no log de atividades e aguardadas até o fim; doze seguidas em uma mesma leitura fazem o processo desistir e reportar o ocorrido.

Múltiplas 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 momento e o exclui novamente. Se o proprietário já tiver seu número salvo, ele pode ver uma notificação de "entrou no Telegram". O tgscope pergunta primeiro, sempre, e o cartão de 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, o layout de mídia e todas as migrações de schema. 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 outra preenchida.

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

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

Legal