Implementando Verificação de Segredos com Gitleaks

Quando Usar

• Quando desenvolvedores podem acidentalmente enviar chaves de API, senhas, tokens ou chaves privadas para repositórios
• Ao estabelecer barreiras de pré-commit que impedem que segredos entrem no histórico do git
• Ao verificar o histórico de repositórios existentes em busca de segredos previamente enviados que precisam ser rotacionados
• Quando requisitos de conformidade exigem a detecção de segredos em todos os repositórios de código-fonte
• Ao migrar de auditorias manuais de segredos para verificação contínua automatizada

Não use para detectar segredos em aplicações em execução ou memória (use detecção de segredos em tempo de execução), para gerenciar segredos após a detecção (use Vault ou AWS Secrets Manager), ou para verificar imagens de contêineres (use Trivy ou Grype).

Pré-requisitos

• Gitleaks v8.18+ instalado via binário, Go install ou Docker
• Framework Pre-commit instalado para integração de hook local
• Repositório Git com histórico para verificar
• Acesso à plataforma CI/CD (GitHub Actions, GitLab CI ou equivalente)

Fluxo de Trabalho

Etapa 1: Instalar e Executar Verificação Inicial do Repositório

Realize uma verificação de linha de base do repositório para identificar todos os segredos existentes no histórico do git.

# Install Gitleaks
brew install gitleaks  # macOS
# or download binary from https://github.com/gitleaks/gitleaks/releases

# Scan entire git history for secrets
gitleaks detect --source . --report-format json --report-path gitleaks-report.json -v

# Scan only staged changes (for pre-commit)
gitleaks protect --staged --report-format json --report-path gitleaks-staged.json

# Scan specific commit range
gitleaks detect --source . --log-opts="HEAD~10..HEAD" --report-format json

# Scan without git history (filesystem only)
gitleaks detect --source . --no-git --report-format json

Etapa 2: Configurar Hook de Pré-commit

Configure o Gitleaks como um hook de pré-commit para impedir que segredos sejam enviados.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks
        name: gitleaks
        description: Detect hardcoded secrets using Gitleaks
        entry: gitleaks protect --staged --verbose --redact
        language: golang
        pass_filenames: false

# Install pre-commit framework
pip install pre-commit

# Install hooks defined in .pre-commit-config.yaml
pre-commit install

# Run against all files (not just staged)
pre-commit run gitleaks --all-files

# Test the hook with a deliberate secret
echo 'AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"' >> test.txt
git add test.txt
git commit -m "test"  # Should be blocked by gitleaks

Etapa 3: Integrar ao GitHub Actions

# .github/workflows/secret-scanning.yml
name: Secret Scanning

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

jobs:
  gitleaks:
    name: Gitleaks Secret Scan
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for comprehensive scanning

      - name: Run Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}  # Required for gitleaks-action v2

      # Alternative: Run Gitleaks directly
      - name: Install Gitleaks
        run: |
          wget -q https://github.com/gitleaks/gitleaks/releases/download/v8.21.2/gitleaks_8.21.2_linux_x64.tar.gz
          tar -xzf gitleaks_8.21.2_linux_x64.tar.gz
          chmod +x gitleaks

      - name: Scan for secrets
        run: |
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            ./gitleaks detect \
              --source . \
              --log-opts="${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}" \
              --report-format sarif \
              --report-path gitleaks.sarif \
              --exit-code 1
          else
            ./gitleaks detect \
              --source . \
              --report-format sarif \
              --report-path gitleaks.sarif \
              --exit-code 1 \
              --baseline-path .gitleaks-baseline.json
          fi

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: gitleaks.sarif
          category: gitleaks

Etapa 4: Criar Regras de Detecção Personalizadas

Crie regras específicas da organização para padrões de segredos internos.

…