Detectando Exposição de Credenciais AWS com TruffleHog

Quando Usar

• Ao integrar a detecção de segredos em pipelines de CI/CD para evitar que credenciais commitadas cheguem à produção
• Ao realizar uma auditoria de segurança de repositórios existentes em busca de credenciais AWS commitadas historicamente
• Ao responder a um alerta do AWS GuardDuty sobre o uso de credenciais de um IP ou região inesperados
• Ao integrar repositórios de empresas adquiridas ou fornecedores terceirizados
• Ao validar que os processos de rotação de credenciais removeram todas as referências a chaves de acesso antigas

Não use para monitoramento de credenciais em tempo real (use AWS GuardDuty ou Amazon Macie), para gerenciar segredos (use AWS Secrets Manager ou HashiCorp Vault), ou para detectar dados sensíveis que não sejam credenciais, como PII (use Amazon Macie ou ferramentas DLP).

Pré-requisitos

• TruffleHog v3 instalado (brew install trufflehog ou pip install trufflehog)
• git-secrets instalado para integração com hook de pré-commit (brew install git-secrets)
• Acesso a repositórios de código-fonte (GitHub, GitLab, Bitbucket ou repositórios git locais)
• AWS CLI configurado com permissões para verificar o status das chaves (iam:ListAccessKeys, iam:GetAccessKeyLastUsed)
• Token de API do GitHub ou GitLab para escanear repositórios em toda a organização

Fluxo de Trabalho

Passo 1: Instalar e Configurar o TruffleHog

Instale o TruffleHog v3 e verifique se ele consegue detectar os padrões de credenciais AWS.

# Install TruffleHog v3
pip install trufflehog

# Or install from binary release
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin

# Verify installation
trufflehog --version

# Test with a known test repository
trufflehog git https://github.com/trufflesecurity/test_keys --only-verified

Passo 2: Escanear Repositórios Git em Busca de Credenciais Expostas

Escanear todo o histórico do git, incluindo todos os branches e commits, em busca de chaves de acesso AWS, chaves secretas e tokens de sessão.

# Scan a local git repository (full history)
trufflehog git file:///path/to/repo --only-verified --json > trufflehog-results.json

# Scan a GitHub organization's repositories
trufflehog github --org=your-organization --token=$GITHUB_TOKEN --only-verified

# Scan a specific GitHub repository with all branches
trufflehog git https://github.com/org/repo.git --only-verified --branch=main

# Scan a GitLab group
trufflehog gitlab --group=your-group --token=$GITLAB_TOKEN --only-verified

# Scan filesystem paths for credentials in config files
trufflehog filesystem /path/to/project --only-verified

Passo 3: Analisar e Validar Credenciais Detectadas

Analisar os resultados do TruffleHog para identificar credenciais verificadas (ainda ativas) versus chaves rotacionadas ou de teste.

# Parse TruffleHog JSON output for AWS findings
cat trufflehog-results.json | python3 -c "
import json, sys
for line in sys.stdin:
    finding = json.loads(line)
    if 'AWS' in finding.get('DetectorName', ''):
        print(f\"Detector: {finding['DetectorName']}\")
        print(f\"Verified: {finding.get('Verified', False)}\")
        print(f\"Source: {finding.get('SourceMetadata', {})}\")
        print(f\"Commit: {finding.get('SourceMetadata', {}).get('Data', {}).get('Git', {}).get('commit', 'N/A')}\")
        print(f\"File: {finding.get('SourceMetadata', {}).get('Data', {}).get('Git', {}).get('file', 'N/A')}\")
        print('---')
"

# Check if a detected access key is still active
aws iam get-access-key-last-used --access-key-id AKIAIOSFODNN7EXAMPLE

# List all access keys for a user to find active keys
aws iam list-access-keys --user-name target-user \
  --query 'AccessKeyMetadata[*].[AccessKeyId,Status,CreateDate]' --output table

Passo 4: Configurar Hooks de Pré-commit com git-secrets

Evitar que credenciais sejam commitadas em primeiro lugar, usando git-secrets como um hook de pré-commit.

# Install git-secrets
git secrets --install  # In each repository

# Register AWS credential patterns
git secrets --register-aws

# Add custom patterns for internal credential formats
git secrets --add 'AKIA[0-9A-Z]{16}'
git secrets --add 'aws_secret_access_key\s*=\s*.{40}'
git secrets --add 'aws_session_token\s*=\s*.+'

# Scan entire repository history
git secrets --scan-history

# Add to global git template for all new repos
git secrets --install ~/.git-templates/git-secrets
git config --global init.templateDir ~/.git-templates/git-secrets

Passo 5: Integrar o TruffleHog ao Pipeline de CI/CD

…