Antes de publicar código feito com IA: varra segredos no Git e no histórico

Um projeto feito com ajuda de IA pode funcionar perfeitamente e ainda carregar uma chave de API, um token de teste, uma senha de banco ou um arquivo .env. Apagar a linha antes do envio não encerra o problema: se o valor entrou em um commit anterior, ele pode continuar no histórico do Git mesmo quando já não aparece na pasta atual.

Neste guia, você vai revisar os arquivos atuais, confirmar o que o Git rastreia, executar duas varreduras locais com Gitleaks e separar detecção de correção. O resultado esperado é uma decisão documentada antes do primeiro push público: nenhum achado conhecido sem triagem, credenciais reais revogadas ou rotacionadas e prevenção configurada para os próximos commits.

Resultado esperado

Ao final, você terá quatro evidências: o estado do repositório antes da publicação, uma lista de arquivos sensíveis rastreados ou ignorados, uma varredura dos arquivos presentes e uma varredura do histórico Git. O objetivo não é obter a frase “zero problemas” a qualquer custo. É reconhecer achados, distinguir segredo real de falso positivo e impedir que uma credencial válida saia do ambiente local.

Este procedimento não publica, não envia e não reescreve o histórico. As etapas são deliberadamente locais. Se a varredura encontrar um segredo real em commits já compartilhados, a contenção vem antes da limpeza: revogar ou rotacionar, verificar uso indevido, comunicar os responsáveis e só então decidir se a história precisa ser reescrita.

Pré-requisitos

• uma cópia local do repositório que será revisado;
• Git instalado e acessível no terminal;
• permissão para examinar o código e seus commits;
• Gitleaks obtido pela página oficial de releases ou por um método oficial descrito pelo projeto;
• acesso ao responsável por cada credencial, caso seja necessária revogação;
• uma janela sem push automático, deploy ou sincronização do repositório.

git --version
gitleaks version

Não execute um binário recebido de fonte desconhecida só para verificar outro projeto. Se você precisa avaliar a origem do instalador no Windows, use o guia Instalador de IA no Windows: confira assinatura, hash e reputação.

Entenda os três lugares que precisam ser verificados

O diretório de trabalho contém os arquivos que você vê agora. A área de preparação, ou index, contém o que entrará no próximo commit. O histórico contém versões registradas em commits anteriores, inclusive linhas que já foram apagadas do diretório atual.

Essa separação explica por que uma única busca no Explorador de Arquivos é insuficiente. Um .env pode ter sido removido da pasta, mas continuar em um commit. Uma chave também pode estar na área de preparação sem ter sido commitada. E um arquivo ignorado pode não ser o único local em que o mesmo valor foi copiado.

Passo 1: pare pushes e confirme o repositório certo

Abra o terminal dentro do projeto e confirme a raiz que o Git reconhece:

git rev-parse --show-toplevel
git remote -v
git status --short

Leia a saída antes de avançar. O primeiro comando evita varrer a pasta errada. O segundo mostra destinos configurados, mas não envia nada. O terceiro expõe arquivos modificados, novos e preparados. Se houver automação que faz push ou deploy ao salvar, desative esse fluxo de forma autorizada durante a triagem.

Não inclua a saída completa de remote -v em documentação pública sem revisar URLs. Configurações antigas podem conter nomes internos ou, em casos inadequados, credenciais incorporadas.

Passo 2: descubra o que já está rastreado

Liste os caminhos conhecidos pelo Git e procure nomes que costumam concentrar configuração sensível:

git ls-files | Select-String -Pattern '(^|/)([.]env($|[.])|.*[.]pem$|.*[.]pfx$|.*[.]key$|credentials|secrets?)'

O comando procura nomes, não o conteúdo. Um resultado não prova vazamento, e ausência não prova segurança. Projetos usam nomes variados e segredos também aparecem em código, exemplos, logs, notebooks, arquivos de configuração e testes.

Revise ainda o que está preparado para o próximo commit:

git diff --cached --name-only
git diff --cached

O segundo comando pode mostrar valores sensíveis no terminal. Faça a revisão em ambiente privado, não compartilhe a tela e não copie a saída inteira para uma IA. Se o diff revelar uma credencial, remova-a da área de preparação e do arquivo antes de continuar.

Passo 3: configure o .gitignore sem confundir prevenção com limpeza

Adicione ao .gitignore somente padrões compatíveis com o projeto. Um exemplo comum é manter um modelo sem valores reais e ignorar variantes locais:

.env
.env.*
!.env.example
*.pem
*.pfx
*.key

A documentação oficial do gitignore é explícita: as regras valem para arquivos intencionalmente não rastreados. Um arquivo que já está sob controle do Git não deixa de existir no index ou no histórico só porque seu nome entrou no .gitignore.

git check-ignore -v --no-index .env

Se o projeto precisa de nomes de variáveis, crie .env.example com valores vazios ou claramente fictícios. Não transforme uma credencial real em exemplo e não invente um token com formato que possa ser confundido com valor válido.

Passo 4: varra os arquivos presentes com Gitleaks

O repositório oficial do Gitleaks distingue o comando dir, voltado a diretórios e arquivos, do comando git, voltado ao histórico. Comece pelo estado presente:

gitleaks dir --redact .

--redact evita imprimir o valor detectado na saída. Ainda assim, trate o terminal como material sensível, pois nomes de arquivo, regra e localização podem revelar contexto. Não salve um relatório dentro da pasta do projeto sem planejar como ele será protegido e excluído do versionamento.

O modo dir pode encontrar arquivos não rastreados e mudanças ainda sem commit. Ele não substitui a próxima etapa, porque a pasta atual não contém todas as versões que já passaram pelo Git.

Passo 5: varra o histórico completo do Git

gitleaks git --redact .

Segundo a documentação do projeto, o modo git usa patches do git log -p para procurar segredos no passado e no presente. Sem um intervalo manual, a implementação atual percorre o histórico disponível do repositório local. Isso só alcança refs e objetos presentes nessa cópia. Uma clonagem superficial, uma branch não buscada ou um fork externo podem manter material que você não possui localmente.

Não troque automaticamente para os comandos antigos detect ou protect encontrados em tutoriais desatualizados. O README oficial informa que eles foram descontinuados a partir da série 8.19 e direciona para git, dir e stdin.

Passo 6: interprete cada achado sem expor o valor

Um achado normalmente informa regra, arquivo, linha, commit e impressão digital. Use esses metadados para localizar o responsável e a origem. Não copie o campo do segredo para uma planilha, ticket ou conversa.

• credencial real e ativa: contenção imediata com o provedor;
• credencial real, mas aparentemente inativa: confirme no provedor e preserve evidência da revogação;
• valor de teste controlado: documente por que não concede acesso e considere um padrão menos ambíguo;
• falso positivo: registre a regra, o contexto e a decisão antes de criar uma exceção;
• não verificável: escale ao proprietário, sem presumir que está seguro.

Ferramentas de detecção usam padrões e contexto. Elas podem não reconhecer um segredo personalizado e podem sinalizar texto que não autentica nada. Por isso, “nenhum achado” não equivale a “nenhum segredo”, e “achado” ainda precisa de triagem humana.

Passo 7: revogue ou rotacione antes de limpar

A orientação de remediação de segredos vazados do GitHub prioriza revogar o valor no provedor. Apagar o texto do código não impede o uso de uma chave que continua válida.

Para um segredo real, registre proprietário, sistema afetado, escopo e dependências. Gere uma nova credencial com o menor privilégio necessário, atualize o serviço de forma controlada e revogue a antiga. Depois, revise logs do provedor e do repositório para procurar uso não autorizado. Se você não tem acesso ao provedor, envolva imediatamente quem tem.

Não teste se uma chave funciona chamando a API sem autorização. A fonte de verdade para validade é o próprio provedor e os controles administrativos da conta.

Passo 8: remova o valor do estado atual

Substitua segredos em código por referências a variáveis de ambiente, cofre de segredos ou mecanismo aprovado pela equipe. Remova arquivos sensíveis do rastreamento atual e mantenha apenas modelos sem valores. Em seguida, repita:

git status --short
git diff --cached
gitleaks dir --redact .
gitleaks git --redact .

Uma nova varredura do histórico ainda pode encontrar o valor antigo, e isso é esperado até uma decisão sobre limpeza histórica. O passo confirma que você não deixou uma segunda cópia no estado atual e que o próximo commit não reintroduz o problema.

Quando considerar reescrever o histórico

A página Removendo dados sensíveis de um repositório alerta que reescrever a história altera hashes, pode invalidar assinaturas, afetar pull requests, exigir force push e permitir recontaminação por clones antigos. A própria documentação recomenda avaliar se a revogação já mitigou o risco antes de iniciar essa operação.

Não há um comando universal seguro para executar às pressas. A decisão depende de branches, tags, forks, clones, proteções, integrações e exigências de conformidade. Faça backup recuperável, defina responsáveis, pause contribuições, coordene colaboradores e use o procedimento oficial adequado. Em repositório corporativo, envolva segurança e administração da plataforma.

Este guia para no diagnóstico e na contenção. Ele não autoriza force push nem exclusão de refs.

Ative prevenção antes do próximo push

O Gitleaks pode ser integrado a pre-commit ou CI, mas o controle precisa usar uma versão revisada e uma configuração mantida. Comece executando manualmente os modos dir e git até entender os achados do projeto. Depois, configure bloqueio para novas inclusões e trate exceções como código revisável, não como atalho.

No GitHub, a proteção de push pela linha de comando pode bloquear segredos compatíveis antes que o push seja aceito. Ela é uma camada adicional, não substitui a revisão local nem cobre todos os formatos personalizados.

Também mantenha agentes e ferramentas de IA com acesso mínimo. O guia Como revisar permissões antes de conectar agentes de IA a arquivos e contas ajuda a reduzir a chance de uma ferramenta ler pastas de credenciais fora do escopo.

Erros comuns

“Adicionei ao .gitignore, então está resolvido”: não está. Arquivos já rastreados não são afetados, e commits anteriores continuam existindo.

“Apaguei a chave no último commit”: a chave pode continuar válida e no histórico. Revogue ou rotacione no provedor.

“O Gitleaks não encontrou nada”: isso reduz incerteza, mas não prova ausência de segredos personalizados, codificados ou fora das refs locais.

“Vou colocar o relatório no repositório”: relatórios podem carregar contexto sensível. Armazene-os fora da árvore versionada, com acesso restrito e retenção definida.

“É um repositório privado”: privacidade do repositório não transforma credencial exposta em prática segura. Colaboradores, integrações, clones e falhas de configuração ampliam o alcance.

“Vou pedir para a IA confirmar o token”: não envie o valor. Use o provedor da credencial e a equipe autorizada.

O que este procedimento não cobre

A varredura não substitui inventário de cofres, revisão de permissões, análise de dependências, busca em issues, pull requests, wikis, artefatos de CI, pacotes publicados, backups, forks ou logs. Também não garante que todos os objetos remotos estejam na cópia local.

Ela não avalia se o código gerado por IA é seguro, apenas procura indícios de segredos. Para testar comportamento de scripts com canais restritos, consulte Código de IA no Windows Sandbox: rede desligada e arquivos somente leitura.

Checklist antes de publicar o repositório

• a raiz e os remotos do repositório foram confirmados;
• push e deploy automáticos ficaram pausados durante a triagem;
• arquivos rastreados e mudanças preparadas foram revisados;
• o .gitignore protege novos arquivos, sem ser tratado como limpeza histórica;
• gitleaks dir --redact . foi executado no estado atual;
• gitleaks git --redact . foi executado no histórico disponível;
• cada achado tem classificação e responsável;
• nenhum valor sensível foi copiado para IA, ticket ou relatório aberto;
• credenciais reais foram revogadas ou rotacionadas no provedor;
• serviços dependentes foram atualizados e testados;
• logs foram revisados quando havia risco de uso indevido;
• reescrita de histórico, se necessária, tem plano e coordenação próprios;
• pre-commit, CI ou proteção de push serão usados como camadas adicionais;
• uma segunda varredura confirmou o estado após a correção.

O ponto de parada correto é claro: se existe um achado não triado ou uma credencial real ainda válida, o repositório não está pronto para publicação. A IA pode acelerar a criação do código, mas a fronteira de segurança continua humana: descobrir o que foi versionado, conter o que vazou e só então liberar o push.