O que é o ratinho vermelho
O ratinho vermelho é um script open source que automatiza a descoberta de credenciais expostas em repositórios GitHub, Docker registries e infraestruturas AWS. Ele escaneia tokens, chaves SSH, senhas hardcoded e variáveis de ambiente, cruzando os resultados com bases públicas de vazamentos conhecidos. O nome veio do mascote do repositório original, não tem nada a ver com hardware de entrada. A ferramenta funciona em três camadas. Primeiro, ela coleta alvos a partir de keywords configuradas, URLs ou URLs passadas via stdin. Depois, aplica regras de regex e entropy scoring para filtrar falsos positivos. Por fim, gera um relatório estruturado em JSON ou texto plano, já com severidade baseada no tipo de credencial encontrada.
Por que usar o ratinho vermelho em vez de scanners genéricos
Scanners de SAST genéricos focam em lógica de programação. Eles raramente rastream segredos fora do código-fonte, como arquivos .env em containers ou variáveis de ambiente injetadas no runtime. O ratinho vermelho foi construído especificamente para isso. Ele também integra com git log, então consegue encontrar credenciais que foram removidas em commits posteriores mas ainda existem no histórico. Isso acontece porque muitas equipes tratam a remoção de segredos como suficiente quando, na prática, o dado continua acessível por qualquer um com acesso ao repositório. O diff exposto em Pull Requests antigos também já foi flagrado por mim mais de uma vez.
Instalação e primeiros passos
O repositório principal está no GitHub. A instalação mais simples é via cargo para Rust, pois a versão binária estável exige compilação local: cargo install ratinho-vermelho
Se preferir binário pré-compilado, os releases da v3.2 em diante trazem .tar.gz para Linux x64 e macOS ARM64. No Windows, recomenda-se WSL2, pois drivers de rede e permissões de filesystem costumam causar bugs de timeout sem mensagem clara de erro. Depois de instalado, um scan básico leva uns 30 segundos em um repositório médio de mil commits:
ratinho-vermelho scan --repo https://github.com/usuario/projeto --deep O flag --deep habilita análise de histórico git e varredura de arquivos gerados durante build, como logs temporários e dumps de configuração.
Configuração avançada com limites realistas
O arquivo de config padrão fica em ~/.config/ratinho_vermelho/config.toml. Nele você define patamares de entropy, extensões ignoradas, proxies e endpoints personalizados. A regra mais importante é a de falsos positivos. O scanner marca como alto risco qualquer string com entropy acima de 4.5 bits por caractere. O problema é que IDs de sessão JWT, hashes bcrypt e dados de testes às vezes caem nessa faixa. A solução prática é criar uma lista branca de padrões conhecidos do seu projeto no campo allowlist_patterns.
Eu perdi dois dias tentando investigar um falso positivo de token JWT que parecia uma AWS SecretKey porque tinha o mesmo comprimento e entropy. A solução foi ajustar o regex de prefixo da AWS para exigir a sequência EXATA AKIA ou SKTA, em vez de confiar apenas no comprimento da string. Isso reduziu os FPs em cerca de 70% no meu ambiente.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Integração com CI/CD
Adicionar o ratinho vermelho ao pipeline custa cerca de 15 a 20 segundos extras por build, dependendo do tamanho do checkout. O stage recomendável é antes do build principal, em um job separado, com falha bloqueante apenas em severidade crítica. No GitHub Actions, um exemplo minimalista:
- name: check secrets
run: ratinho-vermelho scan --repo ${{ github.repository }} --fail-on critical
O flag --fail-on critical é crucial. Se você configurar --fail-on all, o pipeline vai quebrar toda vez que encontrar um hash de teste ou um UUID em arquivo de seed. A política saudável é tratar critical e high como bloqueantes, medium como warning e low como log apenas.
Limitações que ninguém gosta de admitir
O scanner não consegue detectar segredos criptografados em repouso. Se seu projeto usa AWS KMS, HashiCorp Vault ou variáveis encriptadas no GitHub Secrets, o ratinho vermelho só vai analisar o valor em texto plano quando ele for exposto durante execução. Recomendo complementar com análise de infraestrutura, usando permissões IAM restritas e rotação automática de chaves. Outro ponto: ferramentas que injetam segredos via sidecar de service mesh, como Envoy ou Linkerd com volumes secretos, ficam fora do escopo de scan de filesystem. Nesse caso, o foco deve ser auditoria de políticas de admission controller e logs de sidecar.
O resultado também depende da qualidade da coleta de alvos. Se o repositório é privado e você não passou credencial de acesso válida, o scanner não consegue ler o histórico. Ele só escaneia o que está acessível no momento da execução, então configure tokens com escopo mínimo, tipo repo status: readonly para GitHub.
Alternativas quando o ratinho vermelho não funciona
Para ambientes grandes com milhares de repositórios, a ferramenta pode levar horas e consumir bastante memória. Nesse cenário, vale dividir o scan por dono/organização e rodar em paralelo, usando múltiplos workers. Outra alternativa é combinar com grep sobre arquivos estáticos antes de invocar o scanner completo, como filtro rápido que elimina 80% dos alvos antes da análise pesada. Se o projeto usa Kubernetes com External Secrets Operator, o mais eficiente é auditar os SECRETS objects diretamente no cluster, em vez de depender de scan de filesystem. O ratinho vermelho ainda oferece plugin k8s, mas a cobertura não substitui uma inspeção direta dos manifests aplicados.
Dicas práticas baseadas em casos reais
Um problema recorrente que eu enfrentei foi com arquivos .env.local sendo commitados acidentalmente em branches de feature. O scanner encontra, mas o time muitas vezes ignora porque acha que o arquivo não vai para produção. A correção real é implementar pre-commit hooks com git-secrets ou trufflehog, além de rotular .env.* como sensível no .gitignore e aplicar branch protection rules que impedem push direto para main. Outro ponto: credenciais hardcodadas em variáveis de ambiente de Docker Compose muitas vezes parecem seguras porque ficam fora do Dockerfile. O ratinho vermelho lê ambos os arquivos, então configure o scan para incluir docker-compose.yml e quaisquer variações como docker-compose.override.yml.
O tempo médio de remediation depois de um alerta critical costuma ficar entre 2 e 4 horas, desde que a equipe já tenha fluxos de rotação de credenciais definidos. Se não tiver, o gargalo passa a ser burocracia de aprovação, não a ferramenta em si.
