Secrets detection em repositórios: git-secrets, gitleaks

1. Introdução ao Vazamento de Secrets em Repositórios

O vazamento de secrets em repositórios Git é um dos problemas de segurança mais críticos e comuns no desenvolvimento de software. Quando desenvolvedores inserem acidentalmente credenciais, chaves de API, tokens de acesso ou senhas diretamente no código-fonte, eles expõem toda a infraestrutura da empresa a riscos graves.

O cenário típico é conhecido: um desenvolvedor precisa testar uma integração com um serviço externo e, por pressa, coloca a chave da API diretamente no código. O commit é feito, o código é enviado para o repositório remoto e, pronto — a chave está exposta para qualquer pessoa com acesso ao repositório. Pior ainda: mesmo que o arquivo seja removido em um commit posterior, a chave permanece no histórico do Git para sempre.

Os impactos de segurança são severos: exposição de APIs de terceiros, acesso não autorizado a bancos de dados, comprometimento de serviços de nuvem (AWS, Azure, GCP) e até mesmo invasão de infraestrutura corporativa. Estudos mostram que milhares de secrets são descobertos diariamente em repositórios públicos no GitHub.

2. Funcionamento Básico das Ferramentas de Secrets Detection

Ferramentas de detecção de secrets utilizam principalmente dois mecanismos: expressões regulares (regex) e heurísticas avançadas. As regex são usadas para identificar padrões conhecidos, como o formato de chaves AWS (AKIA...), tokens do GitHub (ghp_...), chaves SSH e senhas em formatos comuns.

Heurísticas mais avançadas analisam o contexto do código, a entropia dos dados (quão aleatória é uma string) e a probabilidade de um valor ser realmente um secret. Isso reduz falsos positivos e aumenta a precisão da detecção.

A principal diferenciação entre as ferramentas está no momento da detecção: ferramentas locais como git-secrets atuam como hooks pré-commit, impedindo que o secret seja commitado. Já scanners de repositório como gitleaks podem varrer todo o histórico do Git, identificando secrets que já foram commitados no passado.

3. git-secrets: Configuração e Uso Prático

O git-secrets é uma ferramenta da AWS que analisa commits e mensagens de commit em busca de padrões proibidos. Sua instalação é simples e sua integração com hooks do Git é direta.

Para instalar:

# No macOS
brew install git-secrets

# No Linux (Debian/Ubuntu)
sudo apt-get install git-secrets

Após a instalação, você precisa configurar o repositório:

# Navegue até o diretório do seu repositório
cd meu-projeto

# Instale os hooks no repositório atual
git secrets --install

# Adicione padrões conhecidos da AWS
git secrets --register-aws

# Adicione um padrão personalizado (exemplo: token do GitHub)
git secrets --add 'ghp_[a-zA-Z0-9]{36}'

# Adicione um padrão para senhas genéricas
git secrets --add 'password\s*=\s*["\']([^"\']+)["\']'

Para testar se a detecção está funcionando:

# Teste com um commit simulado
echo "AKIAIOSFODNN7EXAMPLE" | git secrets --scan
# Saída esperada: erro informando que um secret foi detectado

# Teste com um arquivo
git secrets --scan arquivo_com_secret.txt

Você também pode configurar padrões globais para aplicar em todos os repositórios:

git secrets --add --global 'sk-[a-zA-Z0-9]{48}'  # Chave da OpenAI
git secrets --add --global 'SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43}'  # SendGrid

4. gitleaks: Scanning Profundo e Automação

O gitleaks é uma ferramenta mais robusta que permite escanear não apenas commits atuais, mas todo o histórico do repositório. Ele é amplamente utilizado em pipelines de CI/CD.

Instalação:

# Via brew
brew install gitleaks

# Via script de instalação
curl -sSfL https://raw.githubusercontent.com/gitleaks/gitleaks/master/install.sh | sh

Comandos básicos de scan:

# Escanear o diretório atual (commits staged)
gitleaks detect --source . --verbose

# Escanear todo o histórico do Git
gitleaks detect --source . --log-opts="--all" --verbose

# Escanear apenas arquivos staged (antes do commit)
gitleaks protect --staged

Configuração personalizada com arquivo .gitleaks.toml:

# .gitleaks.toml
title = "Regras personalizadas do projeto"

[[rules]]
id = "github-token"
description = "Token de acesso pessoal do GitHub"
regex = '''ghp_[a-zA-Z0-9]{36}'''
tags = ["github", "token"]

[[rules]]
id = "aws-access-key"
description = "Chave de acesso AWS"
regex = '''(AKIA|ASIA)[A-Z0-9]{16}'''
tags = ["aws", "token"]

[[rules]]
id = "slack-webhook"
description = "Webhook do Slack"
regex = '''https://hooks\.slack\.com/services/T[a-zA-Z0-9_]{8,12}/B[a-zA-Z0-9_]{8,12}/[a-zA-Z0-9_]{24}'''
tags = ["slack", "webhook"]

[allowlist]
description = "Arquivos e diretórios permitidos"
paths = [
    '''.*\.test\.py''',
    '''tests/.*''',
    '''node_modules/.*'''
]

Para escanear com essa configuração:

gitleaks detect --source . --config .gitleaks.toml --report-path report.json

5. Integração com CI/CD e Pipelines

A verdadeira força dessas ferramentas está na automação. Integrar a detecção de secrets em pipelines de CI/CD garante que nenhum código com credenciais expostas chegue à produção.

Exemplo de integração com GitHub Actions:

# .github/workflows/secrets-scan.yml
name: Secrets Scan

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Run gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Exemplo de integração com GitLab CI:

# .gitlab-ci.yml
stages:
  - security

secrets-scan:
  stage: security
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks detect --source . --verbose
  only:
    - main
    - develop

Para git-secrets em hooks pré-commit:

# .git/hooks/pre-commit (após git secrets --install)
#!/bin/bash
git secrets --pre_commit_hook
if [ $? -ne 0 ]; then
    echo "ERRO: Secrets detectados! Commit bloqueado."
    exit 1
fi

6. Estratégias de Remediação e Rotação de Secrets

Se um secret foi commitado, a primeira ação deve ser a rotação imediata da credencial. Nunca confie que a remoção do arquivo do repositório é suficiente — o secret já está no histórico.

Para remover secrets do histórico, use o BFG Repo-Cleaner:

# Remover um arquivo específico do histórico
java -jar bfg.jar --delete-files arquivo_com_secret.txt meu-repositorio.git

# Substituir um texto específico no histórico
java -jar bfg.jar --replace-text secrets.txt meu-repositorio.git

Após a limpeza, force o push para o repositório remoto:

cd meu-repositorio
git reflog expire --expire=now --all && git gc --prune=now --aggressive
git push --force

Boas práticas para gerenciamento de secrets:

  • Use vaults como HashiCorp Vault ou AWS Secrets Manager para armazenar credenciais
  • Nunca hardcode secrets em arquivos de configuração
  • Utilize variáveis de ambiente para injetar secrets em tempo de execução
  • Implemente rotação automática de credenciais

7. Limitações e Melhores Práticas

Falsos positivos são comuns em ferramentas baseadas em regex. Strings que se parecem com chaves AWS ou tokens podem ser detectadas incorretamente. Para mitigar isso:

  • Utilize allowlists para ignorar arquivos de teste e diretórios seguros
  • Ajuste as regras regex para serem mais específicas
  • Revise manualmente os resultados antes de bloquear um commit

Limitações importantes:

  • Secrets ofuscados (codificados em base64, criptografados) não são detectados
  • Ferramentas regex não identificam secrets gerados dinamicamente
  • Dependência de padrões conhecidos — tokens personalizados podem passar despercebidos

A cultura de segurança é tão importante quanto as ferramentas. Treine desenvolvedores para:

  • Nunca commitarem secrets, mesmo em branches privadas
  • Usarem pre-commit hooks localmente
  • Reportarem imediatamente qualquer vazamento acidental

8. Conclusão e Próximos Passos na Série

A detecção proativa de secrets é uma das medidas de segurança mais eficazes que uma equipe de desenvolvimento pode implementar. Ferramentas como git-secrets e gitleaks oferecem camadas complementares de proteção: a primeira atua como barreira imediata no momento do commit, enquanto a segunda funciona como scanner profundo de todo o repositório.

A adoção combinada dessas ferramentas com hooks locais e pipelines de CI/CD cria um sistema robusto de prevenção contra vazamento de credenciais. Quando integradas a práticas de gerenciamento de secrets com vaults e rotação automática, formam uma defesa sólida contra um dos vetores de ataque mais explorados atualmente.

Nos próximos artigos desta série, exploraremos temas como code signing, RASP (Runtime Application Self-Protection) e segurança em infraestrutura como código (IaC). A combinação dessas práticas com a detecção de secrets forma a base de uma estratégia completa de segurança para desenvolvedores.

Referências