Detenha segredos antes do commit com o gitleaks: pegue vazamentos de chave de API antes do push

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.

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), aplicada ao código.

Em quais etapas detectar segredos

No caminho que um segredo percorre do código ao mundo, você pode colocar duas verificações: no momento do commit local e logo antes de ele ser compartilhado (CI).

Como integrar o gitleaks

Qual comando usar (v8.19.0 e posteriores)

O gitleaks reorganizou seus comandos na v8.19.0. Os antigos detect e protect ainda rodam, mas estão descontinuados e não aparecem mais na ajuda. Para uma configuração nova, use estes:

O gitleaks sai com código 1 quando encontra pelo menos um vazamento e 0 quando não encontra nenhum, então jobs de CI e cron podem falhar com base nesse código de saída. Adicione --redact para que o segredo em si nunca vá parar na saída nem nos logs.

Exemplo de configuração: hook de pre-commit e GitHub Actions

Com o framework pre-commit, coloque este arquivo na raiz do repositório. Defina rev como a versão mais recente ao adicioná-lo (v8.30.1 em outubro de 2026).

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks

Além de gitleaks (compilado com Go), o id pode ser gitleaks-docker (roda no Docker) ou gitleaks-system (usa um gitleaks já instalado na máquina). Depois, cada pessoa roda isto na própria máquina:

pip install pre-commit        # install pre-commit itself
pre-commit install            # register the hook in this repo (once per clone)
pre-commit run --all-files    # check every file once, right after registering
pre-commit autoupdate         # run now and then to move rev to a newer release

Para CI no GitHub, existe uma GitHub Action oficial. Ela precisa do histórico completo, então faça o checkout com fetch-depth: 0.

# .github/workflows/gitleaks.yml
name: gitleaks
on:
  pull_request:
  push:
  schedule:
    - cron: "0 4 * * *"
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

Para repositórios de uma conta de organização, a Action precisa de uma chave de licença (GITLEAKS_LICENSE). O README oficial diz que a chave é gratuita em gitleaks.io e não é necessária para contas pessoais. Num servidor Git auto-hospedado ou num CI que não seja o do GitHub, rodar gitleaks git --redact dentro do job faz a mesma coisa.

Onde verificar: quatro pontos comparados

Qualquer verificação isolada deixa uma brecha. Colocar lado a lado o que cada uma detém, e onde ela vaza, mostra por que combiná-las.

A proteção de push do GitHub para usuários vem ligada por padrão em pushes para repositórios públicos. É uma rede de segurança gratuita, mas não detém commits locais, e chaves em formatos não suportados ou strings de conexão montadas à mão podem passar (mais em por que credenciais expostas no GitHub continuam válidas, em inglês). O gitleaks cobre a etapa anterior a isso e tudo o que está fora do GitHub.

Como verificar a sua própria configuração

Configurar uma vez não significa que está rodando. No seu próprio repositório, verifique isto em ordem.

Lidando com falsos positivos

Chaves de teste fictícias e exemplos na documentação costumam ser sinalizados. Há três formas de excluí-los; use a mais estreita que resolva.

• Por linha: adicione um comentário gitleaks:allow naquela linha
• Por achado: adicione a impressão digital (fingerprint) mostrada na saída ao .gitleaksignore na raiz do repositório (o README marca isso como experimental)
• Por arquivo ou padrão: adicione à allowlist no .gitleaks.toml

Se você escrever o seu próprio .gitleaks.toml, coloque useDefault = true sob [extend] para manter as regras padrão. Uma configuração só com regras próprias descarta, sem avisar, as chaves que as regras padrão teriam pegado.

Se um repositório antigo tem muitos achados existentes, passe um relatório anterior para --baseline-path para que só achados novos sejam reportados. Mas revogue primeiro as chaves desse relatório. Colocar uma chave na baseline não a torna segura.

Erros comuns e como corrigi-los

• Achar que o arquivo de configuração basta: o hook não faz nada até alguém rodar pre-commit install. Faça todos rodarem e rode a mesma verificação no CI como segunda camada.
• Acostumar-se com --no-verify: torne a verificação do CI uma condição obrigatória para o merge, para que um hook pulado ainda seja pego.
• Imprimir segredos nos logs do CI: adicione --redact. Logs de CI também são lidos por muita gente.
• Varrer um clone raso (shallow clone) no CI: só o commit mais recente é verificado e segredos no histórico passam despercebidos. Defina fetch-depth: 0.
• Parar depois de apagar do histórico: o próprio guia do GitHub coloca revogar ou rotacionar o segredo como primeiro passo. Cópias em forks, clones e caches não podem ser removidas.
• Colocar uma chave real na allowlist como "falso positivo": escreva o motivo num comentário e confira na revisão.

Um caso real: uma chave de acesso deixada pública

Em 7 de outubro de 2022, a Toyota Motor Corporation anunciou que parte do código-fonte do site para usuários do seu serviço de carro conectado T-Connect tinha ficado pública no GitHub. Segundo o anúncio da empresa:

• Em dezembro de 2017, a empresa contratada que desenvolvia o site enviou por engano parte do código-fonte para uma conta do GitHub configurada como pública
• O código continha uma chave de acesso ao servidor de dados que armazenava informações de clientes
• O código foi tornado privado em 15 de setembro de 2022, e a chave de acesso foi trocada em 17 de setembro
• 296.019 endereços de e-mail e números de controle de clientes foram afetados. Os logs de acesso não mostraram uso por terceiros, mas a empresa disse que não podia descartar isso por completo

São cerca de cinco anos entre o envio e a remoção. E aconteceu fora dos repositórios da própria empresa, na conta de uma contratada. Um scanner nos seus próprios repos não alcança todos os lugares para onde o seu código vai parar; então limite também o que cada chave pode fazer e rotacione chaves periodicamente. E mesmo aqui, a chave foi trocada dois dias depois de o código ser retirado: encontre, depois substitua a chave.

Um repositório privado também não é lugar seguro para segredos. No caso da CAMPFIRE em 2026, segundo a empresa, uma credencial do GitHub usada indevidamente foi o ponto de partida, e informações visíveis no GitHub foram usadas para obter credenciais de nuvem (→ o vazamento da CAMPFIRE, em inglês). Mantenha segredos fora de repos privados também e varra-os com o gitleaks periodicamente.

O que este site faz

A regra básica deste site é 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 é o mesmo de arquivos .env e segredos e armazenando senhas com segurança.

Leia a seguir

• Configurações do GitHub: Como configurar a autenticação de dois fatores no GitHub
• Fundamentos: arquivos .env e chaves de API: o que dá errado e como protegê-los
• De uma credencial do GitHub a um vazamento: o vazamento da CAMPFIRE (2026) (em inglês)
• Depois de um vazamento: 543.699 credenciais expostas no GitHub continuam válidas — por que é preciso revogar, não só apagar (em inglês)
• Quando o ataque rodou sem um humano: a invasão da Hugging Face e o pressuposto que os defensores precisam abandonar (em inglês)
• 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)

Fontes

• gitleaks (repositório oficial), README: comandos (git, dir, stdin), descontinuação de detect/protect na v8.19.0, códigos de saída, --redact, gitleaks:allow, .gitleaksignore, --baseline-path, extensão de configuração — github.com/gitleaks/gitleaks / definições oficiais do hook — .pre-commit-hooks.yaml / Releases
• gitleaks-action (GitHub Action oficial), README: exemplo de workflow e chave de licença — github.com/gitleaks/gitleaks-action
• Documentação do pre-commit (install, run --all-files, autoupdate, SKIP) — pre-commit.com
• Documentação do Git, "githooks" (o hook pre-commit e --no-verify) — git-scm.com
• GitHub Docs, "About push protection" — docs.github.com / "Removing sensitive data from a repository" — docs.github.com
• Toyota Motor Corporation, aviso sobre o possível vazamento de endereços de e-mail de clientes (7 de outubro de 2022, em japonês) — global.toyota