TgWitness / Documentação

O que foi testado →

Algumas partes desta página ainda estão em inglês: o original em inglês sofreu alterações após ter sido traduzido.

Referência / Coletar

Telegram · Fluxos de trabalho e operações

Operação diária do painel: modos, categorias de monitoramento, parâmetros, notificações, exportações, backup e capacidade.

TgWitness / Documentação · Implantação e recuperação

Implantação e recuperação

Para sua primeira conexão, utilize contas e formatos de sessão. Para obter uma explicação sobre versões salvas, políticas de eventos e lacunas, consulte como funciona a coleta. Este guia aborda a operação diária e a recuperação.

Uma instalação gerenciada inclui , START-HERE.html, e , START-HERE.txt e , além de seu iniciador, com o link do repositório e comandos adaptados ao seu caminho de instalação . Execute tgwitness guide --print via SSH ou tgwitness paths para localizar o diretório de dados real. Uma instalação como root no systemd armazena o estado privado em /var/lib/tgwitness-…; /opt/tgwitness contém o programa.

Para um túnel temporário gerenciado do Cloudflare, o tgwitness tunnel off desativa o acesso público enquanto o painel local e a coleta continuam em execução. O tgwitness tunnel on o habilita; o tgwitness tunnel restart cria uma nova conexão de túnel. Use o tgwitness open para ver seu endereço atual. Uma configuração explícita de desativação permanece mesmo após reinicializações do serviço. O tgwitness stop interrompe tanto o painel quanto a coleta.

Nesta página

Fluxo de trabalho do operador#

Diagrama de fluxoEscolha o armazenamento e a proteção da chave → Abra o painel com seu token; Abra o painel com seu token → Selecione um espaço de trabalho; Selecione um espaço de trabalho → Configurar rota direta ou via proxy; Configurar rota direta ou via proxy → Insira o número de telefone ou selecione arquivos / QR; Insira o número de telefone ou selecione arquivos / QR → Verifique a identidade da conta e selecione os grupos acessíveis; Verifique a identidade da conta e selecione os grupos acessíveis → Salve as políticas de eventos e anexos e, em seguida, inicie a observação; Salve as políticas de eventos e anexos e, em seguida, inicie a observação → Monitorar erros, acesso, filas e disco; Monitorar erros, acesso, filas e disco → Manter pontos de verificação independentes; Manter pontos de verificação independentes → Exportar e verificar o materialEscolha oarmazenamento e aproteção da chaveAbra o painel com seutokenSelecione um espaço detrabalhoConfigurar rota diretaou via proxyInsira o número detelefone ou selecionearquivos / QRVerifique a identidadeda conta e selecioneos grupos acessíveisSalve as políticas deeventos e anexos e, emseguida, inicie aobservaçãoMonitorar erros,acesso, filas e discoManter pontos deverificaçãoindependentesExportar e verificar omaterial
Diagrama em formato de texto
  1. Escolha o armazenamento e a proteção da chave → Abra o painel com seu token
  2. Abra o painel com seu token → Selecione um espaço de trabalho
  3. Selecione um espaço de trabalho → Configurar rota direta ou via proxy
  4. Configurar rota direta ou via proxy → Insira o número de telefone ou selecione arquivos / QR
  5. Insira o número de telefone ou selecione arquivos / QR → Verifique a identidade da conta e selecione os grupos acessíveis
  6. Verifique a identidade da conta e selecione os grupos acessíveis → Salve as políticas de eventos e anexos e, em seguida, inicie a observação
  7. Salve as políticas de eventos e anexos e, em seguida, inicie a observação → Monitorar erros, acesso, filas e disco
  8. Monitorar erros, acesso, filas e disco → Manter pontos de verificação independentes
  9. Manter pontos de verificação independentes → Exportar e verificar o material

Autorização, conectividade de transporte, acesso a um grupo e integridade da entrega são propriedades distintas. Um status de conexão verde não implica que todos os eventos tenham sido capturados.

Compartilhe o trabalho sem compartilhar a chave principal#

Abra Mais ferramentas → Acesso para atribuir um token próprio a um revisor ou analista. Escolha as contas e os chats que eles podem abrir e, em seguida, permita a visualização, a exportação ou ações operacionais. Um operador que inicia/interrompe a coleta precisa de acesso a todo o espaço de trabalho; um revisor pode ser limitado a um único chat. Limites de sessão, validade e regras de IP são independentes da autorização da conta do Telegram. Consulte Acesso e permissões.

Utilize “Sessões abertas” para encerrar uma conexão ou revogar o acesso a fim de encerrar todas as suas sessões. O console do administrador reúne as atividades dos processos atuais em todas as áreas de trabalho. O encerramento da sessão mantém a coleta em execução.

Modos de execução#

Modo Ação Comportamento
Demonstração scripts\Demo.cmd ou --demo Dados sintéticos; conexões com contas reais desativadas
Observação Iniciar observação Registre as atualizações entregues para fontes selecionadas
Resumo histórico Bate-papos → Ações no bate-papo → Carregar histórico Até 500 mensagens atuais; sem reconstrução de todas as alterações anteriores
Pausa Observação sobre a pausa Interromper a coleta, mantendo os dados e as tarefas em fila
Revisão/transferência Exportações ZIP, JSONL/CSV/HTML, ponto de verificação, recibo de processamento e solicitação de carimbo de data/hora
Várias contas Áreas de trabalho ou o botão superior + Qualquer número de espaços de trabalho separados em um único processo

O acesso à demonstração local é aberto automaticamente, sem a necessidade de inserção manual de token. Ele utiliza um recurso válido durante toda a duração do processo, restrito exclusivamente ao acesso direto por loopback a uma demonstração sintética isolada; o token do painel principal não é divulgado. Espaços de trabalho reais e o acesso à demonstração remota ou via proxy mantêm a autenticação por token. O acesso à demonstração não concede nenhuma autorização no Telegram.

Categorias de monitoramento#

Configurações de monitoramento por conta com dados de origem sintéticos

Em Mais ferramentas → Fontes → Gravação → Escolha quais alterações preservar, selecione mensagens novas, edições, avisos de exclusão, atualizações de reações e eventos de associação de forma independente. A configuração padrão mantém todas as categorias. Mensagens, edições e exclusões mantêm o contexto original ao desativar atualizações separadas de reações/membros. Todas as atividades visíveis restauram todas as cinco. As predefinições alteram o formulário; pressione Salvar configurações de gravação para aplicar.

A política salva se aplica a todas as fontes selecionadas naquele espaço de trabalho. Outros espaços de trabalho mantêm suas próprias configurações. Cada alteração efetiva registra valores assinados de “antes” e “depois” ; a política atual também é incluída nos recibos de processo e nos registros de início de observação . Desativar uma categoria não exclui observações anteriores. Reativá-la não recupera as alterações perdidas. Nesta versão, não há substituição de categoria por grupo.

Mantenha as novas mensagens ativadas quando o conteúdo anterior for relevante: um aviso de exclusão não pode recuperar texto que nunca foi capturado. Registros operacionais/de cobertura e outros eventos de serviço em grupo são sempre retidos. Instantâneos explícitos do histórico são separados da seleção de categorias em tempo real e podem incluir mensagens de serviço. Essas configurações não ocultam metadados de reações/membros incorporados a um objeto do Telegram que, de outra forma, teria sido capturado.

Um instantâneo do histórico pode colocar anexos na fila enquanto estiver em pausa. Inicie a observação para processá-los. Estar na fila não significa que foram baixados. Um arquivo original indisponível não é substituído por uma versão editada mais recente; os resultados são registrados separadamente.

O botão “Lock” limpa o acesso do navegador e os campos secretos, mas mantém a coleta em execução. Fechar uma aba também mantém o processo em execução. Interromper o processo ou serviço em Python interrompe a coleta, independentemente do estado do navegador.

Um espaço de trabalho adicional pode ser excluído assim que um arquivo ZIP ou contêiner ASiC-E assinado, que inclua seu diário e suas anotações do Case Board, for baixado na íntegra. Preparar o arquivo não é suficiente: um registro fora dos eventos de configuração ou uma anotação adicionada após o download mantém a opção Excluir indisponível.

Quando o painel recebe o próprio arquivo, ele contabiliza a exportação somente após ter recebido todos os bytes e, em seguida, reporta o tamanho para POST /api/exports/{id}/received; um download que é interrompido não é contabilizado. Com um seletor de salvamento do navegador (Acesso ao Sistema de Arquivos), o painel reporta a exportação após o arquivo ser gravado e fechado. Sem ela, o painel encaminha o arquivo recebido para a seção de downloads do navegador e não consegue verificar se o navegador o manteve, por exemplo, quando a caixa de diálogo de salvamento é cancelada; o painel, então, informa que o download foi iniciado, e não que o arquivo foi salvo. Um arquivo que o navegador baixa por conta própria (uma exportação maior do que o buffer do navegador do painel) e um download feito por outro cliente HTTP são contabilizados quando o servidor tiver enviado a resposta completa. O sistema operacional e um proxy reverso armazenam em buffer vários megabytes de uma resposta; portanto, para esses downloads, o servidor não consegue detectar uma interrupção perto do final. A menos que o painel indique que o arquivo foi salvo, verifique o arquivo baixado antes de excluí-lo. Uma exportação em grupo é contabilizada para suas contas quando é baixada logo após ser preparada; baixá-la novamente a partir de Exportações preparadas não conta.

Antes da exclusão, o painel exibe o formato, o tamanho, o tempo de preparação e o SHA-256 do último arquivo assinado baixado e solicita a confirmação de que esse arquivo está salvo fora da área de trabalho. O servidor recusa o comando ` DELETE /api/profiles/{id}` se o parâmetro `kept_copy` não estiver definido com esse SHA-256 (ou com `confirmed`, no caso de um arquivo baixado antes do registro da impressão digital).

A exclusão de um espaço de trabalho adicional interrompe seu coletor e remove seus dados locais. Se um arquivo bloqueado ou um erro no sistema de arquivos interromper a remoção, o painel relatará a falha e manterá o espaço de trabalho listado como indisponível (DeletionPending). Feche os programas que estejam mantendo seus arquivos e tente novamente a exclusão. Reiniciar o TgWitness mantém esse espaço de trabalho desativado e não recria seu diário ou suas chaves parcialmente removidos. Uma exclusão bem-sucedida é registrada somente após a remoção do diretório; cópias exportadas ou armazenadas em backup separadamente permanecem sujeitas à sua própria política de retenção.

Notificações#

Abra Configurações → Notificações e cópia externa → Destinos de notificação, ou Mais ferramentas → Extras → Notificações → Configurar. O TgWitness usa o Apprise para enviar alertas para o Matrix, Telegram, Discord, Slack, ntfy, e-mail e outros serviços compatíveis. Você pode adicionar vários destinos a um único espaço de trabalho.

  1. Insira uma URL de destino do Apprise por linha. Utilize o catálogo de serviços e os formatos de URL correspondentes ao seu serviço.
  2. Ative a opção “Enviar notificações” e, em seguida, selecione alertas de problemas, alterações nos chats monitorados e um resumo diário. A hora do resumo utiliza a hora do servidor.
  3. Ative a opção “Incluir trechos curtos” se desejar que o texto salvo de mensagens excluídas e editadas apareça nos alertas.
  4. Clique em “Salvar notificações” e, em seguida, em “Enviar teste” para verificar a entrega.

Para seu próprio receptor, utilize o webhook JSON do Apprise. Por exemplo, jsons://notify.example.org/tgwitness envia JSON por HTTPS para esse ponto de extremidade. Este é um exemplo fictício; substitua-o pelo seu próprio destino.

Os destinos e as configurações pertencem ao espaço de trabalho selecionado. As notificações de alteração abrangem suas fontes monitoradas, incluindo bate-papos recém-adicionados. O sino na barra superior também lista problemas recentes e alterações nos bate-papos.

Na demonstração, os controles de notificação estão visíveis, mas o envio está desativado. Configure a entrega em um espaço de trabalho real. As notificações utilizam a rota Direct, SOCKS5 ou HTTP desse espaço de trabalho; o MTProxy não pode transmiti-las. Destinos que não sejam HTTP, como o SMTP, exigem uma rota direta.

Layout do painel#

Espaço de trabalho de conexão utilizando dados sintéticos

O diário apresenta observações, pesquisas e filtros. Uma edição abre as versões capturadas; uma exclusão abre o conteúdo anterior, se disponível. Atribuições desconhecidas permanecem explícitas. As contagens estão disponíveis na seção “Visão geral”; os detalhes da aquisição permanecem no guia local.

Abra uma mensagem editada para comparar suas versões com Alterações no texto ou Lado a lado; Dados brutos mostra os campos salvos. Alterações em links ocultos e botões de bots aparecem separadamente. Abra a pré-visualização de um anexo para inspecionar imagens, áudios ou vídeos salvos; o botão de download mantém o original preservado disponível.

O modo Live atualiza o diário e os chats conforme os registros chegam. Pause-o durante a revisão ou use o botão de novos eventos quando estiver pronto; a coleta continua em execução. Ctrl/Cmd+K encontra ações do painel e pesquisa no diário.

Mais ferramentas → Fontes contém o escopo da observação (chats selecionados, uma pasta do Telegram ou toda a conta), chats acessíveis de todos os tipos, fontes selecionadas com estrelas de prioridade, configurações de anexos e reavaliação, além de instantâneos do histórico. Fontes privadas são selecionadas por diálogo/ID sem um link público. O status de acesso descreve a verificação mais recente, não permissões permanentes.

Filtre as fontes, marque suas caixas de seleção e, em seguida, ative, pause ou marque todas como prioritárias de uma só vez. Na lista de chats disponíveis, Adicionar selecionados usa a sua seleção; Adicionar todos os resultados usa a busca e o filtro de tipo atuais.

A seção “Bate-papos → Pessoas” lista todos aqueles cujas mensagens foram salvas; com os perfis das pessoas ativados para o bate-papo, um clique abre o perfil dessa pessoa com links para os registros do diário.

Mais ferramentas → Extras → A testemunha independente cria tokens de testemunha somente leitura, mostra quando cada testemunha verificou pela última vez e fornece os comandos e opções para executar uma (testemunha independente).

Mais ferramentas → A seção Parâmetros contém todos os limites e ritmos do espaço de trabalho que não constam em outra página: quantos diálogos são lidos, com que frequência a lista de bate-papos é relida, intervalos de heartbeat e de ponto de verificação , o buffer de inicialização, como as novas verificações distribuem suas solicitações (primeiro atraso, bate-papos por passagem, pausa entre chats, mensagens recuperadas e solicitadas novamente), reserva de disco, tempos limite e novas tentativas de downloads, o que os perfis de usuários procuram (incluindo suas próprias expressões regulares), tamanho e frequência das notificações, limites de snapshot, ZIP e download no navegador, e tempos limite e novas tentativas do cliente do Telegram. Cada campo mostra seu intervalo e valor padrão; os campos alterados são marcados e podem ser restaurados um por um ou todos juntos. Cada alteração é registrada como parameters.changed com os valores antes e depois, e os registros de início da observação indicam os valores em vigor. Os valores passam a valer a partir de seu próximo uso; os tempos limite e novas tentativas do cliente, a partir da próxima conexão. Intervalos de nova verificação, tipos e tamanhos de anexos, evidências e intervalos de cópia externa permanecem em suas próprias páginas e podem assumir qualquer valor dentro de seu intervalo, não apenas as predefinições.

O ícone de sino na barra superior lista problemas e alterações recentes nos chats monitorados; as mensagens não lidas são contabilizadas até serem marcadas como lidas. As alterações são agrupadas por chat e por hora (“12 excluídas, 1 editada, 0 não encontradas”), e problemas como o logout ou disco cheio permanecem na lista, independentemente do volume de atividade nos chats.

Mais ferramentas → A criação da conta começa no campo do número de telefone. Continuar leva diretamente à inserção do código, solicitando credenciais de API apenas quando estiverem ausentes. QR e importação de arquivos são abas alternativas. As credenciais de API salvas são reutilizadas apenas dentro de seu próprio espaço de trabalho. A tela de entrada não possui barra lateral, estatísticas ou seções de configuração. O ícone Configurações abre os controles de API, proxy, armazenamento e contas adicionais. Um novo espaço de trabalho abre a configuração inicial ; após o login, um espaço de trabalho com fontes e registros salvos abre a seção “Chats ”. Alterar a rota requer a pausa na observação e cancela o login inacabado. Um diário existente não pode ser vinculado silenciosamente a uma conta diferente do Telegram.

A exportação verifica a integridade do diário e gera arquivos portáteis. Seu ID de área de trabalho pode ser passado para a CLI de download. Cada exportação fixa um prefixo completo do diário; eventos posteriores são incluídos em uma exportação subsequente. Os filtros de pesquisa não alteram o escopo do pacote. Informações detalhadas sobre assinatura e cobertura estão na seção Verificação e evidências.

O painel exibe o status do coletor, mídias em fila/com falha, as mídias pendentes mais antigas, espaço livre em disco, pausas nas solicitações e fontes cujo acesso não está confirmado na seção “Integridade do coletor”. Esses detalhes aparecem inicialmente recolhidos e ocultos na seção “Conta”. Um cartão de configuração mostra a próxima etapa: conectar uma conta, escolher fontes ou iniciar a observação. A lista de contas é um instantâneo no momento do carregamento; o espaço de trabalho selecionado é atualizado periodicamente. Este não é um monitor de SLA multiprocessos.

A interface usa recursos locais e renderização de texto para o conteúdo de origem. Os layouts de desktop e estreitos no Chromium foram testados.

Ambientes de implantação#

Ambiente Instalação Status da verificação
PC/servidor Windows Python 3.11+, scripts\Setup.cmd/Start.cmd, diretório de dados privado Testado localmente no Windows/Python 3.12
Servidor Linux/VPS Ambiente virtual Python (venv), usuário de serviço dedicado, HTTPS/SSH Exemplos de código, CI e systemd são fornecidos; não executados neste servidor
macOS Venv do Python, processo em primeiro plano ou agente de usuário Exemplo do `launchd` fornecido; é necessária uma verificação separada da instalação
Docker/Compose Volume persistente, um trabalhador São fornecidas a definição e a verificação de tempo de execução da CI; o Docker não está disponível localmente
Navegador do celular Conecte-se ao painel protegido em um servidor em funcionamento Layout estreito baseado no Chromium testado; o coletor não funciona no iOS/Android

Portabilidade significa que não há exigência de serviço em nuvem ou compilação de front-end. Cada alvo ainda precisa de dependências compatíveis de Python/criptografia, disco local e acesso à rede. Consulte o arquivo DEPLOYMENT.md e os modelos de serviço.

Os espaços de trabalho compartilham CPU, memória e um ciclo de eventos. Para isolamento de processos, utilize instâncias, portas, diretórios de dados e autorizações de conta distintas. Não há um painel unificado entre instâncias separadas. Nunca direcione vários workers para um único banco de dados.

Verificações iniciais e exportações#

Execute python start.py --check antes de iniciar um ambiente preparado. Adicione --json para verificações legíveis por máquina ou passe os parâmetros pretendidos --data-dir, --host e --port. O comando verifica os pré-requisitos sem login no Telegram ou criação de um diário. A verificação do diário é executada durante a inicialização do aplicativo, e a disponibilidade para captura é exibida no painel. Uma porta ocupada pode ser simplesmente uma instância já existente.

Os navegadores compatíveis com a API de Acesso ao Sistema de Arquivos salvam as exportações por meio de um fluxo gravável. Outros navegadores armazenam em buffer no máximo 128 MiB. Utilize a CLI de streaming para exportações maiores ou para navegadores sem streaming de arquivos:

python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

Adicione --profile ID em “Exports” para um espaço de trabalho secundário. Utilize --url https://server para acesso remoto. O HTTP simples é aceito apenas para destinos de loopback. O token é lido a partir de um arquivo e enviado em um cabeçalho, não sendo exibido nem inserido em uma URL. Redirecionamentos são recusados. Destinos existentes não são sobrescritos. As transferências com falha removem seu arquivo parcial temporário. O SHA-256 relatado é uma soma de verificação da transferência; verifique o arquivo ZIP assinado separadamente com uma impressão digital/ponto de verificação confiável.

Backup, restauração e interrupções#

  1. Pause a observação e interrompa o processo de forma limpa.
  2. Copie todo o diretório de dados: bancos de dados, WAL/SHM, se houver, mídia, credentials.enc, signing.enc, network.enc, chaves/metadados do cofre, token, pontos de verificação e todos os diretórios profiles/.
  3. Para o modo de chave externa, preserve separadamente a chave mestra e mantenha cada vault.external.json. A geração de uma nova chave não permite recuperar os segredos antigos.
  4. Restaure enquanto o destino estiver parado; configure a chave original, restrinja o acesso e verifique a integridade antes de retomar.
  5. Registre o tempo de inatividade e os resultados da verificação. O tempo de inatividade permanece como uma lacuna registrada; um instantâneo do histórico adiciona o estado após ele.

Evidence ZIPs exclude sessions/private keys and are not full service backups. tgwitness backup FOLDER makes the same copy while the panel keeps running and leaves out the search index, which rebuilds itself; see Updates and backups. Four things are protected differently:

O que Proteção
Arquivos exportados sem senha (padrão) Assinado, de modo que as alterações são detectáveis; defina uma senha para criptografar a exportação
Arquivos exportados com senha Caso defina uma senha, a exportação finalizada será mantida inalterada em um arquivo ZIP com criptografia AES-256 do WinZip, que pode ser aberto pelo 7-Zip e pelo WinRAR; a senha não é armazenada (tratamento de provas)
O banco de dados do registro e os anexos salvos no disco Um disco ou volume criptografado e as permissões da pasta
Sessões do Telegram e chaves de assinatura Criptografado no diretório de dados (credentials.enc, signing.enc, network.enc)

Um backup completo corresponde ao diretório de dados suspenso descrito acima, e não a uma exportação. Utilize armazenamento protegido e um mecanismo de transferência controlado para ambos. As exportações temporárias do servidor ficam armazenadas no diretório temporary-exports/ de cada espaço de trabalho; as respostas concluídas são eliminadas, e os arquivos de exportação interrompidos são removidos na próxima inicialização, enquanto o bloqueio da instância desse espaço de trabalho estiver ativo.

Após um evento de restauração de conexão, o coletor solicita as atualizações perdidas a partir da posição de atualização salva. Tarefas de mídia persistentes e a posição de atualização do Telegram sobrevivem à reinicialização; consulte o formato de evidência.

Capacidade e retenção#

Limites padrão, todos alteráveis em Mais ferramentas → Parâmetros: as primeiras 1,000 caixas de diálogo, 500 mensagens por instantâneo, 4 GiB de conteúdo ZIP assinado não compactado (arquivos maiores requerem verify.py --max-gib N128) e um fallback do navegador de 128 MiB. Anexos ocupam de 1 a 2,000 MiB por tipo em Mais ferramentas → Fontes → Gravação → Anexos. A CLI de download tem como padrão 5 GiB transferidos. O espaço em disco disponível pode ser um limite inferior. Reserve espaço para diários, mídia, WAL, exportações temporárias e backups. As exportações utilizam o volume de dados em vez do diretório 512 MiB /tmp do Compose.

Meça eventos por segundo, tempo de espera na fila, bytes de mídia e latência do disco, em vez de contar apenas os grupos. A entrega em tempo real é medida no coletor em execução. Não há exclusão automática de retenção. Remover o final de um diário invalida sua relação com os pontos de verificação retidos.

As reverificações prioritárias já existem: fontes marcadas com estrela são reverificadas a cada 15 minutos por padrão, as demais a cada 6 horas (veja níveis de reverificação). As exportações protegidas por senha funcionam como descrito acima. O acesso restrito está documentado em acesso e permissões. Veja READINESS.md, LIVE_ACCEPTANCE.md e VERIFICATION.md.