Guias de Segurança
Detenha segredos antes do commit com o gitleaks: pegue vazamentos de chave de API antes do push
Comite uma chave de API por acidente e ela fica no histórico do Git, vazada para sempre. Como o gitleaks detém segredos em dois portões — um hook de pre-commit e o CI — mais o passo de revogação que a detecção sozinha não conclui.
Para: qualquer pessoa usando Git em desenvolvimento solo ou de equipe pequena, preocupada com "e se eu comitar uma chave de API por acidente?" Sem mecânica de invasor aqui — apenas a maquinaria para impedir que segredos vazem do seu próprio repositório.
A visão deste site: o .gitignore sozinho não protege segredos
"Meu .env está no .gitignore, então estou bem" é uma fala comum — e tem brechas. O .gitignore só impede que arquivos novos sejam rastreados; ele não consegue pegar segredos já comitados, os adicionados às pressas com git add -f, ou nomes inesperados como .env.local.bak. Ele bloqueia só parte da entrada. Você precisa de algo que de fato olhe o conteúdo dos commits e sinalize "strings com cara de segredo" — um detector. É para isso que o gitleaks serve.
Por que deter "antes do commit"
Segredos são perigosos porque o Git mantém o histórico para sempre. Apague-o do arquivo mais recente e ele permanece em commits passados. E no momento em que é enviado, esse histórico é copiado para outras máquinas, servidores e logs de CI.
Então a defesa de segredos é, na verdade, sobre prevenção antes do vazamento, não recuperação depois dele. É a mesma ideia do inventário "não deixe segredos num diretório público" (→ o inventário da raiz web), levada para o mundo do código.
Onde os portões ficam
No caminho que um segredo percorre do código ao mundo, você pode colocar dois portões: no momento do commit local e logo antes de ele ser compartilhado (CI).
segredo no código
chave de API, chave, token
portão 1: pre-commit
detecta & aborta localmente no commit
portão 2: CI / cron
detecta após o push, antes do merge/deploy
público / compartilhado
daqui em diante, trate como vazado
Como integrar o gitleaks
Varra o histórico existente primeiro
gitleaks detect. Expulsar segredos dormindo em commits passados é o primeiro trabalho. Qualquer coisa encontrada aqui é, como abaixo, presumida como precisando de revogação.Monte o portão 1 com um hook de pre-commit
gitleaks protect --staged em cada commit para abortar na hora qualquer commit que contenha um segredo. Adicione-o a um framework de pre-commit (.pre-commit-config.yaml) para que a mesma verificação se aplique a todos, localmente.Monte o portão 2 no CI / cron
gitleaks detect como um job de CI — ou, em setups auto-hospedados, como uma varredura periódica — para pegar o que escapa (a mesma mentalidade de monitoramento por máquina das auditorias de dependências).Ajuste falsos positivos no .gitleaks.toml
.gitleaks.toml. A prática certa é não "silenciar", mas "registrar por que é seguro" — uma exclusão sem justificativa é a semente do próximo incidente.Na detecção, 'revogar' vem primeiro; reescrever o histórico vem depois
Quando você encontra um segredo que foi comitado e enviado, a prioridade máxima é revogar e reemitir (rotacionar) essa chave ou token. Apagá-lo do histórico com git filter-repo importa, mas é só limpeza para "parar de se espalhar mais". Suponha que um segredo que chegou a um repo público, a um fork, a um log de CI ou ao clone de outra pessoa é irrecuperável — invalide-o primeiro, depois limpe o histórico. Inverta a ordem e ele é usado enquanto você ainda está apagando.
Confiar no .gitignore
- só impede novo rastreamento
- segredos já comitados passam direto
- impotente contra
git add -fou nomes de arquivo estranhos - não consegue verificar "eu não quis adicionar isso"
gitleaks (detecção + prática de revogação)
- de fato inspeciona a árvore de trabalho e o conteúdo do histórico
- o detém em dois portões: pre-commit e CI
- na detecção, um procedimento que vai até a revogação
- falsos positivos excluídos com uma justificativa registrada
O que este site faz
Este site é construído sobre uma fundação de manter segredos totalmente fora do Git — strings de conexão e chaves de API vivem só em configuração protegida no servidor (um arquivo env com permissão restrita), nunca em texto puro no repo ou em notas de handoff (→ manter segredos fora do git / Git auto-hospedado vs GitHub). Além disso, sobrepomos detectores no pressuposto de que humanos sempre escorregam. O design garante "não coloque", e uma varredura como o gitleaks pega "entrou mesmo assim" — essas duas camadas são a defesa deste site contra vazamentos de segredo. O princípio de lidar com segredos em si é contínuo com arquivos .env e segredos e armazenando senhas com segurança.
Leia a seguir
- Inventário: você está deixando segredos num diretório público
- Auto-hospedagem: manter segredos fora do git / Git auto-hospedado vs GitHub
- Glossário: o que é o ".env" — o que acontece quando um arquivo env vaza
- Ferramenta: scanner de vazamento de segredos (cole e verifique)
FAQ
QO que é o gitleaks?
Uma ferramenta gratuita que varre a árvore de trabalho e o histórico de commits de um repositório Git para detectar se segredos — chaves de API, chaves privadas, tokens — foram comitados. Ele encontra 'strings com cara de segredo' com regras de regex e entropia de string (aleatoriedade), e pode rodar como um hook de pre-commit ou no CI para verificações automáticas.
QColocar no .gitignore não protege os segredos?
Não o suficiente. O .gitignore só impede 'novo rastreamento' — ele não consegue detectar segredos já comitados, nem os adicionados à força com git add -f. Ele bloqueia só parte do acidente, então combine-o com um detector como o gitleaks tanto no pre-commit quanto no CI.
QE se eu acidentalmente comitei e enviei um segredo?
Trate esse segredo como vazado. A prioridade máxima não é reescrever o histórico, mas revogar e rotacionar (reemitir) a chave ou token exposto. Suponha que um segredo que chegou a um repo público ou a um log não pode ser chamado de volta — invalide-o primeiro, depois limpe o histórico e adicione a prevenção (gitleaks).