Referência / Configuração
Telegram · Introdução rápida
Todas as formas de instalar e executar o TgWitness: pacote para Windows, Python, Docker e a demonstração sintética, com as primeiras verificações.
Inglês · Русский · Ucraniano · Espanhol · Português (Brasil) · Türkçe · العربية · فارسی · Urdu · Hindi · Bahasa Indonesia · Tiếng Việt · Chinês simplificado
O TgWitness é um aplicativo independente para monitorar grupos e canais do Telegram aos quais suas contas têm acesso. Ele é executado localmente com seu próprio diretório de dados.
É sua primeira visita? Explore a demonstração antes de conectar uma conta. Escolha um guia para proxies, testemunhas, exportações ou configuração de servidor. O GitHub Actions capture (pré-visualização) executa uma captura em seu próprio fork do GitHub, em vez de uma instalação local.
Instale e inicie#
O instalador guiado inclui seu próprio Python e verifica os hashes dos pacotes e as assinaturas de versão antes da instalação. Executá-lo novamente atualiza uma instalação existente.
Linux / macOS:
curl -fsSL https://get.destroy.tools/install.sh | bash
Windows (PowerShell ou Prompt de Comando):
powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"
Em um servidor Ubuntu, execute como root para instalar um serviço em segundo plano; em um desktop, execute como seu usuário normal. No Ubuntu, o instalador exibe o endereço do painel e a chave de acesso; no macOS e no Windows, o painel local abre no seu navegador. Continue em Conectar o Telegram abaixo. A seção Instalar, verificar e atualizar aborda as opções de acesso ao servidor, a verificação do script antes de executá-lo, as atualizações e a remoção.
Outros métodos#
Lançamentos no GitHub, o código-fonte e o Docker são alternativas ao instalador. Os downloads portáteis ficam disponíveis após a publicação de uma versão de lançamento:
| Hospedagem | Nada instalado | Fonte: Python 3.11+ | Docker: Engine/Desktop com Compose 2.20+ |
|---|---|---|---|
| Windows | Extraia o TgWitness-<version>-windows-amd64-portable.zip das versões do GitHub e clique duas vezes no TgWitness.cmd |
Clique duas vezes em Start.cmd |
Clique duas vezes em scripts\Docker.cmd |
| Linux / macOS | — | sh start.sh |
sh scripts/docker-start.sh |
Para os métodos a partir do código-fonte, baixe e extraia a branch main atual
ou clone o repositório:
git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness
O Start.cmd oferece a instalação do Python 3.12 para o seu usuário do Windows caso nenhuma versão
adequada do Python seja encontrada (via winget ou pelo instalador assinado do python.org). O start.sh exibe
o comando exato de instalação para a sua distribuição Linux ou macOS se o Python estiver ausente.
A primeira execução a partir do código-fonte cria o .venv e instala as dependências automaticamente.
O Docker compila o aplicativo e o inicia em segundo plano; não é necessário um host Python.
scripts\Docker.cmd e scripts/docker-start.sh exibem o endereço do painel e o token quando
o contêiner está em bom estado. Os comandos equivalentes do Docker em todos os hosts compatíveis são:
docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt
Acesse http://127.0.0.1:8787. Utilize o token gerado pelo auxiliar do Docker ou pelo segundo comando do Docker, ou consulte o arquivo data/live/panel-token.txt para uma instalação portátil ou de código-fonte. Continue na seção “Conectar o Telegram” abaixo. As instalações nativas e via Docker utilizam armazenamento separado; iniciar o Docker não importa um diário nativo existente.
No que diz respeito ao servidor, a implantação abrange HTTPS automático, reinicialização, imagens publicadas, atualizações e backups.
Explore a interface#
- Execute o
arquivo `TgWitness-Demo.cmd`
no pacote portátil, o `scripts\Demo.cmd`
na pasta de origem do Windows
ou o `
sh start.sh --demo` no Linux/macOS. Ao executar o arquivo de origem, o sistema cria primeiro o `.venv` e instala as dependências. - Acesse http://127.0.0.1:8787.
- A demonstração local abre automaticamente o diário de amostra. Não é necessária nenhuma cópia do token para acesso local direto.
As mensagens de demonstração são fictícias. O modo de demonstração não permite conectar uma conta real do Telegram.
Conectar-se ao Telegram#
[!AVISO] Use contas dedicadas. O Telegram pode restringir ou banir permanentemente contas por volumes de solicitações que considere excessivos, independentemente do cliente. Conecte contas preparadas para observação, em vez de contas pessoais ou valiosas, e crie um ID de API / hash em uma conta dedicada.
- Caso a demonstração nativa esteja em execução, interrompa-a e execute o Start.cmd ou o
sh start.sh. Caso contrário, mantenha em execução a instalação ao vivo iniciada acima. - Use o token do painel para fazer login. Um novo espaço de trabalho é aberto na primeira configuração. Escolha Apenas baixar, Acompanhar chats ou Evidências para um caso.
- Verifique a conexão. Configure seu próprio proxy, se necessário; as configurações de conexão permanecem disponíveis após a instalação.
- No Connect Telegram, escolha um número de telefone, um código QR, arquivos de conta (TData,
.session, StringSession, JSON da conta) ou uma chave de autorização completa. Preencha a confirmação do Telegram, o código e a senha de duas etapas quando solicitado. - Verifique a conta exibida, escolha os chats e revise suas configurações. Conclua na tela final. Para a opção Apenas baixar, Iniciar exportação inicia uma exportação única e abre a seção Exportações para mostrar seu andamento; isso não habilita a observação contínua.
Após a configuração, Bate-papos → Escolher altera os bate-papos selecionados. Configurações controla a coleta e os arquivos; Mais ferramentas → Fontes fornece a lista detalhada de fontes nos níveis Padrão ou Avançado. O guia do painel descreve as seis principais seções e seus controles contextuais.
O ID da API + Hash é opcional: o espaço de trabalho usa seu par salvo ou importado,
ou um par ativo do conjunto integrado. Para usar seu próprio aplicativo, cole um
par API ID:API Hash no campo ID da API. Para a chave de autenticação, cole todos os 512 caracteres hexadecimais
e selecione o ID do DC fornecido. O ID do usuário é opcional e é verificado caso seja inserido.
As credenciais da API identificam seu aplicativo; elas não autorizam uma conta por si só. Grupos privados não exigem nome de usuário público, mas sua conta deve ter acesso.
Para contas existentes, consulte os formatos de contas e sessões: o painel aceita Telethon StringSession, Telethon/Pyrogram SQLite, TData ZIP de conta única e JSON de conta compatível. Selecione uma sessão e seu JSON correspondente juntos, clique em Verificar arquivos e, em seguida, em Conectar conta. O login por QR também está disponível com as mesmas configurações opcionais da API. TDLib, sessões de bots e inventários de contas em CSV/JSON não são suportados.
Para várias contas, use Contas → Importar contas e selecione os arquivos de sessão compatíveis. Os arquivos JSON complementares são pareados pelo nome-base; cada conta importada recebe seu próprio espaço de trabalho. Veja importação em massa e grupos de contas.
Para adicionar outra conta, pressione + ao lado do seletor de contas ou use Contas → Adicionar conta. Os espaços de trabalho possuem sessões, diários, chaves, fontes e filas separadas. A troca de visualizações mantém os outros coletores em execução. A mesma conta do Telegram não pode ser atribuída a dois espaços de trabalho nesta instalação. Não há um número fixo de espaços de trabalho; eles compartilham um único processo, portanto a capacidade depende da máquina.
O token do painel ao vivo protege o acesso às suas autorizações do Telegram e ao material salvo;
ele é independente das credenciais da API do Telegram. Apenas uma demonstração local iniciada explicitamente
e acessada diretamente recebe acesso automático. Uma demonstração remota ou via proxy continua utilizando o
data/demo/panel-token.txt.
Revisão e exportação#
- Registro: pesquise e filtre observações por fonte e tipo de evento.
- Selecione um evento para examinar seu registro original, atribuição e versões salvas.
- Os detalhes da edição mostram o conteúdo disponível antes e depois. Os detalhes da exclusão mostram o último conteúdo capturado, se houver; um agente desconhecido permanece desconhecido.
- Formatos de exportação: ZIP assinado, JSONL, CSV e HTML offline.
- Exportação completa do chat (Chats → Exportar chat, ou Exportações → Capturar ou exportar um
chat): baixe todo o histórico visível de um chat
como um pacote assinado com
chat.json(estilo de exportação do Telegram) e um arquivo legívelchat.html. Chats privados funcionam quando a conta é membro. Trata-se de um instantâneo atual, não de uma reconstrução de mensagens excluídas ou editadas anteriormente. Verifique uma cópia compython verify.py chat-export.zip --fingerprint TRUSTED_SHA256. - Ponto de verificação: mantenha o limite do registro assinado fora do coletor.
- Baixe o comprovante de execução assinado: preserve o registro do programa e da versão do coletor.
- Prepare uma solicitação de carimbo de data e hora: prepare uma solicitação offline para uma autoridade de carimbo de data e hora; siga as instruções do arquivo TIMESTAMP.md para obter e verificar uma resposta.
- Verificar o registro: verifique as assinaturas dos eventos e os elos da cadeia. A exportação em ZIP também verifica os arquivos de mídia.
Os navegadores compatíveis salvam exportações de grande porte diretamente em um arquivo escolhido. Outros navegadores armazenam em buffer no máximo 128 MiB. Enquanto o servidor estiver em execução, a CLI de streaming suporta downloads maiores sem armazenar toda a resposta em buffer:
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
Para outro espaço de trabalho, adicione --profile ID usando Exportações → ID do espaço de trabalho.
Para um servidor remoto, adicione --url https://your-server. O limite padrão de transferência é de
5 GiB; --max-mib altera esse valor. O conteúdo ZIP assinado tem um limite de verificação separado de 4 GiB descompactado
por padrão (Mais ferramentas → Parâmetros aumenta esse limite; verifique esses arquivos com
verify.py --max-gib N). Verifique o arquivo usando uma cópia confiável do verificador, uma
impressão digital da chave mantida de forma independente e, no mínimo para fins de evidência, o certificado raiz da
autoridade de carimbo de data/hora (--tsa-ca).
Verifique a instalação#
python start.py --setup-only
python start.py --check
python start.py --check --json
O --check verifica dependências locais, suporte à assinatura, armazenamento, configuração de chaves e
o endereço de escuta. Ele não instala nada nem se conecta ao Telegram. Uma porta
ocupada pode significar que outra instância está em execução. Utilize um --port diferente ou interrompa-a primeiro.
O iniciador é instalado no .venv. Os comandos auxiliares python -m tgwitness... devem
utilizar o .venv\Scripts\python.exe no Windows ou o .venv/bin/python no Linux/macOS,
a menos que esse ambiente já esteja ativado.
Sessões, proteção e operação#
Um .session do Telethon SQLite, fechado e consistente, pode ser convertido localmente com
python -m tgwitness.sessions account.session --out account.tgwitness-session e, em seguida,
carregado em Mais ferramentas → Conta → Arquivos. A importação direta de arquivos e o login por QR também estão disponíveis. Consulte
CONNECTION-SECURITY.md para formatos de login, SOCKS5,
HTTP CONNECT, MTProxy e chaves-mestre externas.
A pausa na observação interrompe a coleta. O bloqueio apenas interrompe o acesso pelo navegador. Fechar uma aba mantém o processo de coleta em execução. Interromper o processo interrompe a coleta; um instantâneo do histórico não pode reconstruir todas as edições ou exclusões perdidas. Veja como funciona a coleta em relação a políticas de eventos, filas de anexos, isolamento de contas e comportamento de reinício.
Sessões e segredos são criptografados. O conteúdo das mensagens, mídias e exportações exigem um disco ou volume criptografado. Verifique as assinaturas do diário em relação a uma chave confiável e mantenha os pontos de verificação separadamente. Analise os registros de captura, recibos de tempo externos e atestados de ambiente para o modo de coleta selecionado.
Leia o arquivo OPERATIONS.md para informações sobre backup/restauração, o arquivo DEPLOYMENT.md
para hospedagem e a pasta deploy/ para exemplos de uso do serviço. O painel instalado
também inclui um guia de configuração offline em /guide.html.
A verificação efetiva e as limitações remanescentes estão registradas nos arquivos VERIFICATION.md e READINESS.md.