Referência / Configuração
Telegram · Conexão, proxies e proteção de dados
Autenticação, conjuntos automáticos de proxies, modos de IP, política de fallback, solicitações externas e armazenamento de segredos.
TgWitness / Documentação · Implantação e recuperação
Este documento descreve o comportamento do TgWitness0.9.3 e seus limites. Autenticação, acesso à fonte, conectividade de rede e integridade da captura são estados distintos. Para etapas de login, formatos de arquivo e contas múltiplas, comece com formatos de contas e sessões. Para políticas de eventos e comportamento de reinício, consulte como funciona a coleta.
Configuração guiada da conexão#
Em Mais ferramentas → Conta → Rota de conexão, o administrador pode escolher Esta conta, Um grupo de contas ou Todas as contas e, em seguida, selecionar uma rota. A opção Revisar seleção lista as contas afetadas. A opção Preparar e verificar testa a rota proposta sem alterar a rota salva. A opção Aplicar conexão verificada valida a visualização, pausa a observação, se necessário, salva a rota e retoma a observação que já estava em andamento. A coleta nunca é iniciada em uma conta que estava inativa anteriormente. Os downloads do histórico permanecem pausados e podem ser retomados separadamente. Pause as exportações ativas antes de alternar.
Alterações em grupos mantêm as contas em suas respectivas rotas por padrão. Desmarque essa opção somente quando a visualização listar as alterações desejadas. O aplicativo relata o resultado de cada conta; não se trata de uma transação do tipo “tudo ou nada” entre bancos de dados. Uma mudança malsucedida restaura as configurações anteriores daquela conta. Uma falha na retomada é exibida explicitamente. As visualizações expiram após dez minutos e alterações nas configurações de conexão ou na participação em grupos exigem uma nova verificação.
A função “Apply” reutiliza um resultado de pré-verificação bem-sucedido por até 90 segundos, desde que sua rota, modo e política permaneçam inalterados. Um túnel gerenciado ainda deve ter o mesmo processo em execução. Resultados mais antigos, processos de túnel alterados e rotas automáticas do pool do MTProxy são verificados novamente. O registro assinado do aplicativo mantém a hora original da verificação e registra a reutilização e sua idade. Cada pré-verificação encerra seu cliente temporário não autenticado; o coletor se conecta usando sua própria sessão autorizada.
| Rota | O que o TgWitness gerencia |
|---|---|
| Direto | Conexões a partir do host; uma VPN de host externo não é detectada nem imposta. |
| VPN | Um perfil WireGuard de túnel completo por conta, executado por um processo SOCKS5 no espaço do usuário local. Nenhuma interface de host ou driver é instalado. |
| Meu proxy | Credenciais SOCKS5, HTTP CONNECT ou MTProxy. Um URL pode preencher os campos SOCKS5/HTTP. Ao selecionar várias contas, esse proxy inserido é compartilhado. |
| MTProto público | O pool existente atribui rotas Telegram. As solicitações externas ficam desativadas até que um proxy externo adequado seja configurado nas configurações avançadas. |
| WARP | Um túnel local separado para cada conta selecionada, com registro no WARP e um perfil do WireGuard mantido no cofre dessa conta. |
A verificação da rota atual utiliza um transporte Telegram novo e não autenticado, e não a
sessão da conta. Ela abre uma conexão de transporte pela rota até o
centro de dados da conta e realiza uma ida e volta não autenticada pelo MTProto
(req_pq_multi); não cria nenhuma chave de autorização e não utiliza nenhuma conta. A
latência relatada é o tempo de conexão somado à ida e volta, e a verificação
registra ambas as partes separadamente. Para rotas compatíveis com HTTP, ela também solicita
o rastreamento HTTPS da Cloudflare por essa rota e exibe o IP de saída relatado,
o país, o status do WARP e a hora da verificação. A preparação do WARP falha, a menos que o rastreamento
relate que o WARP está ativo. Essas verificações prévias relatam a conectividade da rota e a
saída observada. Analise os registros capturados por meio dos resultados de aquisição e
verificação do arquivo. Um processo local em execução, por si só, não constitui uma verificação de saída bem-sucedida.
O painel mantém uma média móvel das últimas cinco verificações. Uma rota é considerada lenta quando
a média ultrapassa 5 segundos ou quando três verificações consecutivas ultrapassam esse valor, e
fica indisponível após duas verificações malsucedidas consecutivas; network.slow_route e
network.route_recovered registra as alterações. Para uma rota WARP lenta, o Re-roll WARP
reinicia o túnel da conta em relação a outros pontos finais do Cloudflare WARP, mantém o
mais rápido e registra network.warp_rerolled com os tempos antes e depois;
A Nova identidade WARP registra um novo dispositivo WARP e o mantém apenas quando ele for
mais rápido. O endereço do proxy local, a conta do Telegram e sua sessão permanecem os
mesmos; as conexões do Telegram se reconectam por meio do túnel reiniciado. Uma rota WARP
lenta é reiniciada automaticamente no máximo uma vez a cada 30 minutos; quando isso
não ajudar, novos reinícios aguardam a intervenção do operador.
WARP e WireGuard portáteis#
Esta é uma integração não oficial do WARP utilizando wgcf 2.3.1 e wireproxy 1.1.3 . O administrador aceita explicitamente a configuração antes do primeiro download ou do registro no WARP. Essas conexões de configuração vão diretamente para o GitHub e o Cloudflare e revelam o IP da máquina. O tráfego normal da conta mantém sua rota existente até o aplicativo. O Cloudflare escolhe o endereço de saída e o país; túneis separados podem compartilhar um endereço de saída. A seleção de país, a rotação periódica de IP e um kill switch de VPN para todo o host não são fornecidos por esse recurso.
Downloads de auxiliares compatíveis: Linux e macOS x86-64/ARM64, e Windows x86-64.
Os artefatos são verificados em relação aos hashes SHA-256 incluídos no código-fonte revisado,
e os executáveis armazenados em cache são verificados novamente antes da execução. Nenhum auxiliar é adicionado ao
PATH, instalado como serviço do sistema ou recebe um ouvinte público. Todos os arquivos ficam
no diretório portable-routes/ do espaço de trabalho e em entradas criptografadas do cofre.
O ouvinte de loopback SOCKS5 requer credenciais geradas de forma independente.
Perfis privados e credenciais de conta WARP são criptografados com o cofre do espaço de trabalho existente. Durante a execução, o auxiliar precisa de uma configuração em texto simples exclusiva do proprietário; ela é removida em uma parada normal. Uma falha no host pode deixar esse arquivo para trás na pasta de dados exclusiva do proprietário. Isso não criptografa o disco nem protege contra o administrador. O supervisor fecha o túnel se o pipe pai do painel desaparecer. Um túnel com falha nunca habilita um fallback direto. A reinicialização do painel restaura um túnel selecionado; tentativas de inicialização com falha são repetidas com um atraso limitado. Parar o túnel também pausa a observação e mantém o estado de parada. Iniciar o túnel inicia o túnel; retome a observação separadamente quando estiver pronto.
Os perfis do WireGuard enviados devem conter uma interface e um par, rotas IPv4 e IPv6 completas, e não devem conter hooks, includes, substituições de ambiente ou listeners adicionais. Os endereços de endpoints públicos são resolvidos e fixados antes da inicialização. Utilize uma VPN externa ou o gateway SOCKS5 para OpenVPN/IPsec e endpoints privados.
Métodos de autenticação#
O ID da API e o hash da API identificam um aplicativo; eles não substituem o login da conta. Eles são opcionais no TgWitness. Prioridade: um par inserido no formulário, em seguida, um proveniente de um arquivo JSON de conta importado, depois o par salvo no espaço de trabalho e, por fim, o conjunto integrado de 50 pares públicos, testados em ordem aleatória com rotação automática quando o Telegram recusa um. Apenas o par do Telegram Desktop (2040) é enviado com uma descrição correspondente do cliente Telegram Desktop. Seu próprio par, obtido nas Ferramentas de Desenvolvimento de API em my.telegram.org, pode ser usado com todas as suas contas; cada conta continua tendo sua própria autorização.
| Método | Requisitos | Suporte ao TgWitness |
|---|---|---|
| Telefone, código, autenticação de dois fatores (2FA) opcional | Acesso à conta; par de API opcional | Login no painel |
| Chave de autenticação HEX + ID DC | Chave completa de 512 caracteres e DC 1–5 | Guia “Chave de autenticação direta”; o ID do usuário opcional é verificado antes que a autorização seja salva |
| Telethon StringSession | Uma sequência de sessão válida | Login no painel |
Telethon SQLite .session |
Texto conciso e consistente | Importação direta de esquemas por meio de painel 7/8; CLI offline opcional |
Pyrogram SQLite .session |
Sessão de usuário de produção encerrada | Importação direta de esquemas por meio do painel 2/3 |
| Telegram Desktop TData ZIP | Uma conta moderna; senha local, caso esteja protegida | Conversão na memória com verificações de checksum e descriptografia |
| JSON da conta | Campos suportados de API/sessão/chave | Os metadados, por si só, preenchem as credenciais da API; ainda é necessário um login por sessão/chave ou por telefone/QR code |
| Login via QR | Confirmação de um aplicativo autorizado do Telegram | Geração local de QR, validade/nova tentativa, 2FA opcional |
| TDLib / Pyrogram StringSession | Outros formatos específicos de bibliotecas | Não suportado |
| Token do bot | Um bot com seu próprio modelo de acesso/atualização | Não utilizado por este coletor |
O Telegram escolhe a forma de entrega do código, incluindo se deve enviar SMS. Um hash de API não pode restaurar uma sessão revogada nem substituir uma senha de 2FA esquecida. O TgWitness não armazena códigos de login nem a senha de 2FA do Telegram no disco.
Para uma fonte privada, a conta já deve ter acesso. Um nome de usuário de grupo é desnecessário. Um proxy ou importação de sessão não concede nem direito de participação nem direitos de administrador. As configurações do chat determinam se os membros veem o histórico anterior à sua adesão.
Importar um arquivo de sessão do Telethon#
O Telethon SQLite, o Pyrogram SQLite e o TData do Telegram Desktop utilizam formatos diferentes. O painel detecta e converte as estruturas compatíveis; renomear um arquivo não é considerado uma conversão. Selecione uma sessão e seu arquivo JSON correspondente na seção Arquivos, pressione Verificar arquivos e, em seguida, Conectar conta. São aceitos até quatro arquivos correspondentes e 8 MiB no total. Consulte os limites de formato para obter detalhes sobre TData/JSON. Não há recuperação de senha. O login por telefone/2FA ou QR gera uma autorização separada.
O caminho opcional da linha de comando exclusivo para o Telethon continua disponível:
- Encerre a sessão do cliente original e crie uma cópia consistente. O conversor rejeita arquivos com um WAL/diário incompleto. Feche o cliente original adequadamente, em vez de excluir esses arquivos para contornar a verificação.
- No ambiente do TgWitness, execute:
python -m tgwitness.sessions account.session --out account.tgwitness-session
- Em “Adicionar conta” → “Arquivos”, carregue o resultado ou cole sua sequência de caracteres e continue.
- Verifique o ID numérico da conta exibido, selecione as fontes e inicie a observação.
O arquivo convertido é uma senha de acesso à conta não criptografada. Mantenha-o em um armazenamento protegido e nunca o envie para um serviço de conversão de terceiros. O TgWitness armazena a sessão autorizada em seu cofre criptografado. Copiar uma sessão não cria uma autorização separada: não execute clientes simultâneos com chaves de autenticação clonadas e não presuma que as atualizações sejam entregues de forma independente.
A conversão transfere a autorização, não as mensagens originais, o cache da entidade ou um cursor de atualização persistente. Ela não garante a recuperação das atualizações após reinicializações do processo.
MTProto, Telethon e proxies#
MTProto é o protocolo do Telegram. Telethon é a biblioteca cliente em Python utilizada pelo TgWitness. MTProxy é um proxy de transporte do Telegram; SOCKS5 e HTTP CONNECT fornecem túneis gerais. Nenhum deles substitui a autenticação da conta.
Salve a rota para cada espaço de trabalho em Mais ferramentas → Conta → Configurações → Configurações de conexão → Alterar rota de conexão antes de fazer login. Os novos espaços de trabalho têm como padrão o MTProxy Automático · listas públicas com a opção Ocultar o endereço. Os espaços de trabalho existentes que usavam explicitamente o modo Direto mantêm um modo que permite isso.
Os arquivos são lidos por meio de conexões distintas daquela utilizada para a leitura de mensagens, assim como fazem os aplicativos oficiais. No próprio centro de dados da conta, reutiliza-se a chave de autorização da conta com uma nova sessão MTProto; para outro centro de dados, cria-se uma chave que é autorizada enquanto a conta está conectada e é mantida apenas na memória. Cada conexão de arquivo utiliza a mesma rota da conta. Seu número por centro de dados é limitado por Parâmetros → Desempenho → Conexões de arquivo por centro de dados do Telegram; o valor 0 indica que os arquivos são lidos apenas pela conexão principal da conta. No máximo, cinco conexões do Telegram são estabelecidas simultaneamente em todas as contas de uma instalação.
Modos de IP#
A rota escolhe a conexão. O modo IP, a proteção de IP na seção “Conta” do painel, determina quando o endereço do servidor pode ser exposto. Esses controles não instalam uma VPN nem redirecionam todo o tráfego da máquina.
| Modo | Telegram | Solicitações externas |
|---|---|---|
Ocultar o endereço (hide) |
Utilize um proxy; aguarde caso nenhum funcione. Não há alternativa direta. | Requer SOCKS5/HTTP; rejeita solicitações sem um proxy adequado. |
Recorra ao Direct apenas como último recurso (fallback) |
O MTProxy automático pode utilizar o Direct após o atraso configurado e, em seguida, retornar a um proxy em funcionamento. | Prefira um proxy externo configurado ou a rota SOCKS5/HTTP da conta; caso contrário, a conexão direta é permitida. |
Servidor atrás de um túnel ou VPN (tunnel) |
São permitidas rotas diretas e o recurso automático imediato ao pool de reserva. | O acesso direto é permitido quando não houver nenhum proxy configurado. |
O modo de túnel ou VPN pressupõe que você gerencie essa rede separadamente. Sem um túnel em funcionamento, os destinatários podem ver o endereço do próprio servidor. Selecione o modo de acordo com sua rede real, e não com o nome da opção.
Escolha um caminho#
| Rota | Configurações | Limites |
|---|---|---|
| MTProxy automático | Listas integradas ou um catálogo de operadores | Mantém uma rota funcional do Telegram; o recurso alternativo direto depende do modo IP |
| Direto | Modo Tunnel ou VPN | O Telethon utiliza a rota de rede do anfitrião |
| SOCKS5 | Servidor, porta, nome de usuário/senha opcionais | python-socks, DNS de destino remoto habilitado |
| HTTP CONNECT | Servidor, porta, nome de usuário/senha opcionais | HTTP CONNECT simples; o TLS para o próprio proxy não está implementado |
| MTProxy | Servidor, porta, chave secreta | Transporte experimental do Telethon; 32 dígitos hexadecimais ou dd + 32 dígitos hexadecimais |
Segredos TLS falsos do tipo ee são rejeitados. A normalização do Telethon 1.45 pode remover um prefixo
e um domínio, mas isso não implementa o TLS falso. Cole tg://proxy?server=…&port=…&secret=…
ou https://t.me/proxy?server=…&port=…&secret=… e selecione “Preencher campos a partir do link”.
Isso valida e preenche os campos sem se conectar ou salvar; revise e salve a
rota separadamente. Os campos manuais permanecem disponíveis. Consulte os links de proxy do Telegram.
Proxies públicos fornecidos pela sua instalação#
A lista integrada reúne sete fontes: SoliSpirit/mtproto, zakky8/mtproto-proxy-pro, kort0881/telegram-proxy-collector, 3yed-61/MTP-Collector, Therealwh/MTPproxyLIST, KhodeJav/telegram-proxy-collector e tgmtproxy/telegram-mtproto-proxy-list. O snapshot incluído contém informações sobre os endpoints, atribuição das fontes e datas de download. As listagens são dados de entrada; as verificações de conectividade abaixo determinam quais proxies serão utilizados.
O MTProxy automático verifica a conectividade de transporte do Telegram, mantém um proxy em funcionamento e muda para outro quando ele falha. Os espaços de trabalho preferem proxies diferentes quando há entradas funcionais suficientes disponíveis; os proxies podem compartilhar um endereço de saída. Proxies com falha permanecem inativos antes de uma nova tentativa. Se nenhum funcionar, o modo IP determina se a coleta deve aguardar ou se pode usar uma conexão direta. A troca de proxies não altera a conta nem apaga seu diário. As escolhas e alterações de rota são registradas no diário assinado.
Enquanto as rotas automáticas estiverem ativas, as listas são atualizadas a cada hora e as verificações de transporte são executadas a cada dez minutos por padrão. Esses intervalos são configuráveis. A atualização de listas públicas solicita uma atualização; a simples visualização da lista não altera uma rota manual salva.
O tráfego do Telegram e as solicitações HTTPS utilizam rotas diferentes. Os downloads de listas utilizam uma
conexão HTTPS separada e a rota de solicitação externa fornecida.
O TGWITNESS_PROXY_FEED_PROXY substitui explicitamente essa rota por um proxy HTTP/SOCKS5;
ambas as variantes do coletor Compose a encaminham. O pool em segundo plano segue o espaço de trabalho principal.
Nenhuma sessão do Telegram, credenciais de API, token de painel ou token de bot é enviada aos provedores de feed.
Os nomes dos provedores, as datas dos instantâneos e a rota de download aparecem na seção “De onde vem a lista”.
Um MTProxy transporta apenas tráfego do Telegram. Operações HTTP do espaço de trabalho, como registros de data e hora, notificações, cópias externas e verificações de fonte, utilizam um proxy SOCKS5/HTTP separado quando configurado; caso contrário, utilizam a rota SOCKS5/HTTP da conta. Na ausência de ambos, a opção “Ocultar endereço” recusa a solicitação; os outros modos permitem a conexão direta. Solicitações externas podem ser desativadas. Um proxy de download de feed explicitamente configurado permanece como uma substituição separada do operador. O serviço de testemunha independente mantém sua própria rota.
Para serviços privados gerenciados por operadores, a configuração existente do ambiente de servidor
TGWITNESS_ALLOW_PRIVATE_DESTINATIONS=1 permite destinos privados e mantém
a resolução do nome de host no lado do proxy. Ela não pode ser ativada a partir do painel. O modo somente público
rejeita destinos .onion antes de consultar o resolvedor público; os serviços onion do Tor
exigem essa configuração explícita de destino privado e um proxy adequado.
Esse comportamento do DNS se aplica a operações HTTP externas, não ao transporte do Telegram.
A Cloudflare documenta o endpoint JSON do DNS.
Parâmetros automáticos do pool
Em Mais ferramentas → Parâmetros → MTProxy automático, configure o limite de falha, o tempo de espera, a rotação planejada, o compartilhamento de proxy e o atraso de fallback permitido.
| Controle | Padrão |
|---|---|
| Desconecta antes da substituição | 3, em 10 minutos |
| Proxies testados por tentativa de conexão | 3 |
| Primeiro / intervalo máximo após falha | 10 minutos / 6 horas |
| Rotação planejada | Desativado; ativar em caso de falha |
| Contas por proxy | 0: dar preferência a entradas separadas, compartilhar quando necessário. Definir 1 para aguardar uma entrada exclusiva. |
| Atraso antes do fallback direto permitido | Minutos 10; Ocultar o endereço ainda recusa o Direct |
| Verificações de atualização/transporte do feed | Minutos 60/10; os valores da área de trabalho principal se aplicam ao pool compartilhado |
Proxies diferentes podem compartilhar um endereço de saída. Os limites do Telegram se aplicam a todas as rotas.
Para substituir a lista pública pelo seu próprio catálogo de operadoras, configure a substituição abaixo.
Isso desativa totalmente as assinaturas externas, inclusive quando a matriz proxies estiver vazia.
Copie o catálogo vazio
para proxy-config/proxies.json
e adicione seus endpoints públicos implantados:
{"format": "tgwitness-proxy-catalog-v1", "proxies": [
{"id": "project-eu", "label": "Project EU",
"link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"}
]}
Os valores de exemplo devem ser substituídos. São aceitas até 32 entradas distintas. A lista autenticada retorna rótulos/hosts/portas sem segredos compartilhados; ao selecionar um, suas credenciais são salvas no cofre da área de trabalho. A disponibilidade permanece não testada até que seja realizado um teste de transporte explícito. Um catálogo malformado permite a configuração manual.
Execução nativa: defina TGWITNESS_PROXY_CATALOG como o caminho JSON local. Docker:
docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build
A sobreposição é montada como proxy-config em modo somente leitura; os arquivos devem ser legíveis pelo UID 10001 do contêiner.
Esse diretório está excluído do Git, do contexto de compilação do Docker e dos arquivos-fonte. Este
catálogo configura as contas de coleta; o bot testemunha utiliza sua própria
rota HTTP/SOCKS5, e não o MTProxy.
O fallback direto é regido pelo modo IP descrito acima. Suspenda a observação antes de alterar uma rota. Ao salvar, os clientes antigos são desconectados e os logins inacabados são cancelados; um novo cliente utiliza a rota salva. A vinculação entre o diário e a sessão da conta permanece. As configurações substituem a rota anterior: digite novamente as credenciais do proxy ao editá-la.
As credenciais são criptografadas em network.enc. A API não retorna o nome de usuário,
a senha ou o segredo. Os registros assinados contêm o tipo de rota e se as credenciais
estão presentes, excluindo o endpoint e os segredos. O operador pode visualizar o endpoint
no painel. Os campos de segredos são apagados após salvar, bloquear ou alternar entre espaços de trabalho.
O teste de conexão com o Telegram, também disponível antes do login, abre e fecha uma conexão temporária não autorizada com o Telegram por meio da rota. Ele não entra em contato com um site de verificação de IP. O sucesso do teste confirma a conectividade de transporte, não o acesso a grupos, a entrega completa ou o anonimato.
O proxy se aplica às conexões do cliente do Telegram, incluindo downloads de mídia dos servidores de dados (DC) do Telegram.
O navegador, o pip, o SSH e as ferramentas TSA acionadas manualmente seguem rotas separadas.
O nome do host do proxy pode ser resolvido localmente. O rdns afeta os nomes de host de destino;
o Telegram frequentemente fornece endereços IP numéricos dos servidores de dados (DC).
O SOCKS5 e o HTTP CONNECT simples, por si só, não criptografam as credenciais do proxy nem o túnel cliente-proxy. O MTProto protege separadamente o tráfego do Telegram. Use um canal seguro apropriado para o proxy em uma rede não confiável. Grupos privados são bate-papos na nuvem protegidos pelo MTProto em trânsito; os bate-papos secretos de ponta a ponta são um tipo de bate-papo separado, registrado pelo módulo de bate-papo secreto.
Criptografia e assinaturas#
| Camada | Implementado | Responsabilidade do operador |
|---|---|---|
| Tráfego do Telegram | Telethon MTProto | Confiança, rota e disponibilidade da plataforma |
| Painel da web | Token de portador, configuração padrão de loopback, limites de solicitações | HTTPS ou túnel SSH para acesso remoto |
| Segredos | Fernet para credenciais de API, sessão, credenciais de proxy e chave privada de assinatura | Proteja a chave de descriptografia e o servidor em execução |
| Chave do cofre | Chave local ou chave mestra externa para uma nova instalação | Armazenamento protegido e backup de chaves separados |
| Mensagens e anexos | Armazenamento de aplicativos em texto simples | Disco/volume criptografado |
| ZIP/JSONL/CSV/HTML | Verificações de integridade, sem criptografia de conteúdo | Proteja cópias exportadas e transferências |
| Proveniência e data | Registro assinado, comprovante de processo, ferramentas RFC 3161 | Chave confiável, pontos de verificação independentes/TSA e procedimento de custódia |
A proteção de armazenamento na seção “Conta” exibe esses estados. O token do painel é um segredo de acesso, não uma senha de criptografia. Ele concede acesso de administrador; os tokens emitidos podem ter seu escopo restrito a contas e chats. Os espaços de trabalho compartilham o processo anfitrião e não são locatários isolados.
O BitLocker, o LUKS, o FileVault ou um volume criptografado gerenciado podem proteger o armazenamento de acordo com seus respectivos modelos de ameaças. Um administrador de uma máquina em execução e desbloqueada ainda pode ler os dados. Inclua SQLite WAL/SHM, mídia, exportações temporárias, swap, backups e downloads do navegador no planejamento de armazenamento. Um volume do Docker não é criptografado simplesmente por ser um volume.
Chave mestra externa#
Para uma nova instalação, coloque a chave mestra fora do diretório de dados. Isso não migra automaticamente um cofre de chaves local já existente. Prepare um diretório de chaves acessível apenas à identidade do serviço e, em seguida, execute:
python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key
export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key
python -m tgwitness --data-dir /private/observations/new-case
PowerShell, utilizando o ambiente de projeto instalado:
python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key
$env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key'
python -m tgwitness --data-dir E:\PrivateData\new-case
No Docker, monte o arquivo como somente leitura fora de /data, por exemplo, em
/run/secrets/tgwitness-master.key, e defina a variável de ambiente com esse caminho.
O UID do serviço deve ter permissão de leitura. Transmita o caminho, e não os bytes da chave, por meio de
arquivos de ambiente/configuração.
Cada espaço de trabalho recebe um “salt” público aleatório e sua própria chave Fernet, derivada por meio do
HKDF-SHA256. O vault.external.json armazena os metadados de derivação, não a chave mestra.
Uma chave ausente ou incorreta impede a inicialização, sem substituí-la silenciosamente. Guarde tanto os
metadados do “salt” quanto a chave mestra para fins de recuperação.
Todos os espaços de trabalho derivam da mesma chave mestra; seu comprometimento afeta toda a instalação. O processo em execução pode descriptografar segredos. Trata-se de um HSM ou KDF de senha. Senhas definidas arbitrariamente por usuários não são aceitas no lugar de uma chave aleatória.
Mantenha a chave existente para instalações já em uso até que uma migração planejada seja
implementada e verificada. A exclusão de vault.key ou a substituição de uma chave mestra pode comprometer
o acesso a sessões/chaves de assinatura. Mantenha backups criptografados e chaves separadamente e
teste a recuperação em uma instância isolada.