Detectando segredos vazados antes do commit com Gitleaks

Objetivo

Uma vez que uma API key ou token entra num commit, ela fica na história do repositório — remover o arquivo depois não apaga o segredo do histórico do git. Gitleaks resolve a parte que dá pra prevenir: escaneia o diff de cada commit em busca de padrões conhecidos de segredo (chaves AWS, tokens do GitHub, credenciais de banco, etc.) e bloqueia o commit antes dele existir.

Este guia mostra como rodar o Gitleaks como pre-commit hook local. Não cobre a varredura completa do histórico de um repositório já existente nem a integração no CI — isso fica para um próximo artigo.

Premissas

• Git instalado e um repositório local para testar.
• Python 3 com pip, para instalar o framework pre-commit.
• Os comandos abaixo seguem a documentação oficial do Gitleaks e do pre-commit, mas não foram executados neste ambiente — confira a versão mais recente do Gitleaks na página de releases antes de aplicar, já que o binário e as flags de CLI mudam entre versões.

Implementação

Instalar o framework pre-commit

pip install pre-commit

Configurar o hook do Gitleaks

Crie um arquivo .pre-commit-config.yaml na raiz do repositório:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks

Confira a página de releases antes de usar esse rev — diferente de um go install ...@latest, o pre-commit exige uma revisão fixa, e ela não se atualiza sozinha. Vale revisitar esse valor periodicamente (ex.: via Dependabot ou Renovate).

Instale o hook para que ele rode automaticamente em todo git commit:

pre-commit install

A partir daqui, todo commit passa pelo Gitleaks antes de ser criado. Se ele encontrar algo que parece um segredo no diff, o commit é rejeitado e nada é enviado ao histórico do repositório.

Lidando com falsos positivos

Chaves de exemplo em documentação, fixtures de teste e hashes às vezes disparam o Gitleaks sem ser um segredo real. Para esses casos, crie um .gitleaks.toml com uma regra de allowlist específica em vez de desabilitar o hook inteiro:

[allowlist]
  paths = [
    '''fixtures/.*''',
  ]

Evite usar allowlist ampla demais (ex.: ignorar um diretório inteiro de código de produção) — isso anula o propósito do hook.

Validação

Para confirmar que o hook está funcionando, adicione uma linha com um padrão de segredo conhecido (por exemplo, uma string no formato de uma AWS access key) em um arquivo de teste e tente commitar:

git add arquivo-de-teste.txt
git commit -m "teste"

O hook deve interromper o commit e apontar o arquivo e a linha onde o padrão foi encontrado. Remova o segredo de teste do arquivo antes de seguir — não deixe esse conteúdo, mesmo fictício, num commit real.

Limitações relevantes

• Não cobre commits já existentes. O pre-commit hook só age em commits novos. Para escanear o histórico de um repositório que já existe, é preciso rodar gitleaks detect apontando para o histórico completo — um passo separado, fora do escopo deste guia.
• É um hook local, não uma barreira. Qualquer pessoa pode pular a checagem com git commit --no-verify ou simplesmente não ter o hook instalado. Para um controle que não dependa de cada desenvolvedor configurar o ambiente, o mesmo scan precisa rodar no CI, no servidor, não só localmente.
• Segredo commitado e depois removido continua exposto. Se algo passar do hook e for commitado antes de ser pego, revogar a credencial é mais importante do que limpar o histórico do git.

Próximo passo

Depois que o hook estiver rodando localmente, o passo seguinte é replicar a mesma varredura no pipeline de CI — assim o controle não depende de cada máquina ter o pre-commit instalado e atualizado.