TRUFFLEHOG: ENCONTRANDO SEGREDOS VAZADOS EM REPOSITÓRIOS GIT

O que é o TruffleHog

Cometer um arquivo .env no GitHub é um erro clássico de desenvolvimento — em um processo seletivo técnico, esse deslize sozinho já é motivo de reprovação. Se já aconteceu com você, aconteceu com muita gente. É por isso que ferramentas de varredura de segredos existem: o dado que ninguém quer publicar acaba publicado, e permanece acessível mesmo depois de removido.

O TruffleHog é a ferramenta de referência para esse problema. Ela examina repositórios Git e todo o seu histórico de commits procurando segredos que foram adicionados por acidente — chaves de API, tokens, senhas e outros dados sensíveis. A detecção combina duas frentes: verificação por alta entropia, que aponta strings com a aparência estatística de um segredo, e expressões regulares de alto sinal, que casam padrões conhecidos de credenciais.

O ponto central é o histórico: um desenvolvedor pode remover a chave do commit mais recente, mas ela continua viva no passado do Git, recuperável a qualquer momento. Com uma credencial válida em mãos, o acesso a serviços ocorre com pouco ruído — sem exploits, sem autenticação forçada, sem alerta imediato.

A ferramenta pode ser apontada para um único repositório, para um caminho local ou, usando as APIs do GitHub e GitLab, para muitos projetos de uma vez. Nas versões atuais, ela também classifica o que encontra e faz verificação ao vivo: confirma se a credencial realmente funciona contra o serviço ao qual pertence.

Há um detalhe de instalação que gera confusão frequente e precisa ser esclarecido de saída: o pacote Python trufflehog do PyPI não é a ferramenta atual da Truffle Security. É a versão 2.2.1 do projeto original, publicada pela última vez em 2021 e mantida em forma legada. A ferramenta atual, com subcomandos git, github e filesystem e verificação ao vivo de credenciais, instala-se pelo script oficial de releases do GitHub. Os dois formatos de linha de comando são diferentes — e este artigo mostra os dois.

Instalação

A demonstração de referência trabalha sobre duas ferramentas: o git-dumper, para reconstruir localmente um repositório a partir de um diretório .git exposto na web, e o próprio TruffleHog. No Kali Linux, o git-dumper instala-se pelo pip3:

pip3 install git-dumper

O TruffleHog da versão 2 também existe como pacote pip, e é essa forma que a demonstração usa para a varredura inicial do dump:

pip3 install trufflehog

Atenção aqui, porque a distinção importa: o pacote Python e o release do GitHub não são a mesma ferramenta. O pacote trufflehog do PyPI corresponde à versão 2.2.1 legada do projeto — entropia e regex sobre diffs, sem verificação ao vivo. O release atual, mantido pela Truffle Security, traz os subcomandos e a verificação de credenciais. Confira qual dos dois está no seu PATH antes de interpretar um resultado.

O fluxo desta demonstração é: usar o git-dumper quando houver um diretório .git exposto e então rodar o TruffleHog contra esse dump. Diretórios .git acessíveis por HTTP continuam sendo uma ocorrência comum em servidores mal configurados.

Dump de um repositório exposto

Alguns servidores deixam o diretório .git inteiro aberto. Quando isso acontece, o navegador exibe o próprio índice de arquivos do repositório, como na captura da demonstração de referência abaixo — tudo visível: HEAD, config, branches/, os objetos.

Reconstruindo com git-dumper

Com o índice acessível, basta entregar ao git-dumper a URL do diretório e a pasta local de destino:

git-dumper http://<DOMINIO>/.git dump

O git-dumper percorre o índice e baixa os arquivos do repositório para a pasta indicada, exibindo o progresso de cada requisição.

Dump sem listagem de diretório

Outros sites bloqueiam a listagem de diretórios, mas continuam servindo os arquivos individuais. A captura a seguir, da mesma demonstração, mostra o conteúdo de um arquivo config de um .git acessível dessa forma: a seção [remote "origin"] expõe a URL interna do repositório e a seção [user] revela o e-mail de quem commita.

Coletando objetos por nome conhecido

Mesmo sem índice, o git-dumper consegue puxar todos os objetos, commits e referências que consegue alcançar:

git-dumper http://<DOMINIO>/.git/ dump

Dessa vez a saída mostra requisições de arquivos específicos — hooks, objetos, HEAD — com status 200 e 404, até completar o dump. Tudo o que o git-dumper alcançar fica armazenado na pasta de dump: é esse repositório reconstruído que o TruffleHog vai examinar.

Analisando o repositório com TruffleHog

Com o dump em disco, roda-se o TruffleHog contra a pasta. Por padrão, a ferramenta executa a detecção baseada em entropia sobre os diffs de commits. Ela ajuda, mas não deve ser o único modo que você conhece — na demonstração de referência, a combinação de regex com entropia desligada devolveu mais resultados:

trufflehog --regex --entropy NO dump

A saída aponta o motivo de cada achado (Reason), a data do commit, o hash e o caminho do arquivo dentro do repositório.

Credenciais de banco no dump

Entre os arquivos examinados, a demonstração encontrou credenciais de banco de dados — senha embutida em URL de conexão mysql, com caminho de arquivo, branch e commit registrados junto ao achado.

Release atual e modo filesystem

A partir daqui, a demonstração troca para o release atual da ferramenta — instalado pelo script oficial de releases do GitHub, direto em /usr/local/bin:

curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin

Com o binário atual em disco, a varredura do dump passa a usar o modo filesystem, apontando diretamente para a pasta:

trufflehog filesystem /home/<USUARIO>/Documents/dump

Esse modo é adequado para ajustar varreduras, mas costuma gerar mais ruído e falsos positivos — na captura, os achados aparecem como unverified, com motivo verification issue: lookup e o caminho do objeto dentro de .git/objects. Vale conhecer o comportamento e calibrar a leitura dos resultados.

Outras formas de analisar repositórios

Dependendo de qual versão está instalada, há flags que mudam o que a varredura devolve. Os exemplos a seguir, do release atual, usam o repositório público de chaves de teste mantido pela própria Truffle Security.

Para varrer um repositório remoto exibindo resultados verificados e não verificados:

trufflehog git https://github.com/trufflesecurity/test_keys --results=verified,unknown

O resultado verified significa que o TruffleHog confirmou a credencial ao vivo contra a API do serviço emissor — AWS, GitHub e outros. Unknown cobre tanto os achados de alta entropia quanto os de regex que não puderam ser confirmados.

Saída em JSON

O mesmo scan com saída em JSON, que registra fonte, detector, decodificador e o campo Verified de cada achado:

trufflehog git https://github.com/trufflesecurity/test_keys --results=verified,unknown --json

Varredura de organização

No GitHub, a varredura de repositórios de uma organização inteira é feita com a flag --org=, conforme a documentação oficial da ferramenta.

Issues e pull requests

Issues e pull requests também são terreno de vazamento. A varredura que inclui comentários de issues e de PRs:

trufflehog github --repo=https://github.com/trufflesecurity/test_keys --issue-comments --pr-comments

O que aparece nas discussões

Essa varredura revira issues, comentários, corpo das PRs e comentários de revisão — discussões técnicas frequentemente carregam credenciais que nunca chegaram ao código. Entre os resultados, a demonstração destaca uma chave privada OpenSSH publicada em discussão, com commit, e-mail e arquivo de origem registrados no achado.

Repositório local com file://

E para um repositório Git local, aponte a varredura para o caminho com o esquema file://:

trufflehog git file://test_keys --results=verified,unknown

O cenário típico é o de uma máquina de desenvolvimento comprometida com múltiplos projetos em disco. Como a demonstração mostrou, a chance de encontrar algo local é pelo menos tão alta quanto no GitHub — os dois caminhos existem, e é preciso varrer os dois.

Perspectiva defensiva

Do lado de quem defende, o TruffleHog é a mesma ferramenta operando com o objetivo invertido: revelar o que está exposto antes que um adversário encontre. Executar trufflehog git file:// no repositório local antes de cada push funciona como teste de vazamento caseiro; em escala, a ferramenta entra em pipelines de CI como gate de merge — a própria documentação oficial sugere o uso com --fail, que devolve código de erro 183 quando encontra credencial válida, bloqueando a entrega.

O lado operacional do vazamento é o que costuma escapar: a remoção do segredo do branch atual não o remove do histórico. Corrigir exige rotação da credencial — revogar e reemitir a chave vazada — porque o commit antigo continua recuperável por qualquer pessoa com acesso ao repositório, e em repositórios públicos por qualquer pessoa na internet.

Na perspectiva de detecção de exposição externa, há três superfícies para monitorar: o diretório .git de servidores web (que não deve existir na raiz de publicação — a listagem exibida na demonstração é o sintoma), os repositórios públicos dos desenvolvedores (um pentest externo da demonstração achou acesso a banco justamente em projetos pessoais públicos de funcionários) e as discussões do GitHub (issues, PRs e comentários, que as varreduras com --issue-comments --pr-comments cobrem). Para vazamentos já consumados, o histórico de uso da credencial fica registrável nos logs do serviço emissor.

Limitações

Este artigo é documental: descreve a ferramenta, seus comandos e os resultados conforme a documentação oficial e o material de referência, sem execução própria nesta ocasião. Os resultados citados são os da demonstração de referência, não testes independentes.

Quanto à ferramenta: a versão legada instalada pelo PyPI e o release atual não são intercambiáveis — os comandos e a saída diferem entre as duas, e a verificação ao vivo só existe no release atual. O modo filesystem tende a mais ruído e falsos positivos, e os resultados precisam de triagem. Achados unknown não são credenciais confirmadas: são candidatas cuja verificação falhou por erro de rede ou API, e exigem validação manual antes de qualquer conclusão.

Considerações éticas

A varredura de segredos opera sobre repositórios públicos ou ambientes autorizados — pentest contratado, CTF, auditoria do próprio acervo. Um diretório .git exposto e um repositório público são, tecnicamente, informação acessível; usar a credencial encontrada contra o serviço de terceiros é outra coisa, e é aí que está a fronteira: autenticar-se com chave alheia é acesso não autorizado.

O padrão de uso correto segue o mesmo fluxo da demonstração: relatar o achado, rotacionar a credencial se ela for sua, notificar o responsável se não for. Bug bounty e divulgação responsável são o caminho profissional para vazamentos descobertos em código de terceiros.

Conclusão

O caso que fecha a demonstração de referência resume o valor da ferramenta: em um pentest externo com vários serviços acessíveis e nenhuma credencial à vista, os projetos pessoais de alguns desenvolvedores — mantidos públicos no GitHub — acabaram entregando um par de credenciais válido e, com ele, o acesso a um banco de dados.

Arquivos sensíveis às vezes são expostos sem que quem publicou perceba. Somos humanos e erramos — ofensiva ou defensivamente, o ponto é o mesmo: o TruffleHog existe para tornar esse erro visível, do lado de quem o cometeu e de quem vai explorá-lo.