Escaneo de Secretos en tu Repositorio con TruffleHog
¿Confirmaste accidentalmente una clave API en tu repositorio? No estás solo. Miles de credenciales se filtran a través de git cada día, a menudo permaneciendo en el historial de commits mucho después de que los desarrolladores creen haberlas eliminado. El escaneo de secretos con TruffleHog ofrece una forma directa de detectar claves API expuestas en repositorios antes de que se conviertan en incidentes de seguridad.
Este artículo cubre cómo funciona TruffleHog, cómo escanear repositorios git en busca de secretos de forma local y en CI, y cómo interpretar los resultados para que puedas priorizar la remediación de manera efectiva.
Puntos Clave
- TruffleHog escanea historiales completos de git, no solo archivos actuales, revelando secretos enterrados en commits antiguos
- Los hallazgos verificados indican credenciales activas y explotables que requieren rotación inmediata
- Integrar TruffleHog en pipelines de CI previene filtraciones de credenciales antes de que lleguen a producción
- Cuando se encuentran secretos, primero rota las credenciales, luego elimínalas del historial usando herramientas como BFG Repo-Cleaner o git-filter-repo
Por Qué los Secretos Terminan en Git
Los desarrolladores trabajan rápido. Una contraseña de base de datos se codifica directamente durante la depuración. Una clave de AWS termina en un archivo de configuración. Estos errores ocurren constantemente, y el historial inmutable de git significa que incluso los secretos “eliminados” persisten en commits anteriores.
El riesgo es real: bots automatizados escanean repositorios públicos continuamente, y las credenciales expuestas pueden ser explotadas en minutos después de ser publicadas. Incluso los repositorios privados no están a salvo: una sola cuenta de desarrollador comprometida o un control de acceso mal configurado puede exponerlo todo.
Cómo TruffleHog Detecta Secretos
TruffleHog no es una simple herramienta de grep. Utiliza escaneo basado en detectores con cientos de patrones integrados para tipos específicos de credenciales: claves de AWS, tokens de GitHub, claves API de Stripe, cadenas de conexión a bases de datos, y más.
El enfoque de detección combina:
- Coincidencia de patrones: Detectores regex ajustados para formatos conocidos de secretos
- Análisis contextual: Examina el código circundante para reducir el ruido
- Verificación opcional: Prueba las credenciales contra APIs reales para confirmar que están activas
Este enfoque en capas significa menos falsos positivos que los escáneres basados únicamente en entropía. Cuando TruffleHog marca algo, generalmente vale la pena investigarlo.
Escaneo de un Repositorio Local
Para escanear repositorios git en busca de secretos localmente, apunta TruffleHog a tu repositorio:
trufflehog git file://.Esto escanea todo el historial de git, no solo el árbol de trabajo actual. Los secretos enterrados en commits antiguos se revelan junto con los recientes.
Para obtener retroalimentación más rápida durante el desarrollo, puedes limitar el alcance del escaneo a commits recientes o ramas específicas. Esto hace práctico ejecutarlo antes de publicar cambios.
Entendiendo Resultados Verificados vs. No Verificados
TruffleHog distingue entre dos tipos de hallazgos:
- Verificados: La credencial fue probada contra su API y confirmada como activa
- No verificados: El patrón coincide con un formato conocido de secreto, pero la verificación no fue posible o no se intentó
Los hallazgos verificados demandan acción inmediata: estas son credenciales activas que podrían ser explotadas ahora mismo. Los hallazgos no verificados aún merecen revisión, pero puedes priorizarlos más bajo al clasificar un conjunto grande de resultados.
Para filtrar la salida solo a resultados verificados:
trufflehog git file://. --only-verified
Discover how at OpenReplay.com.
Integración de TruffleHog GitHub Action en CI
Ejecutar escaneos manualmente detecta problemas, pero la automatización los previene. La TruffleHog GitHub Action se integra directamente en tu pipeline de CI para escanear cada pull request y push.
Una configuración básica de workflow escanea los cambios entrantes y falla la compilación si se detectan secretos. Esto crea una barrera que detiene las filtraciones de credenciales antes de que lleguen a tu rama principal, o peor aún, a producción.
La action admite escanear solo el diff (más rápido para verificaciones de PR) o el historial completo del repositorio (útil para auditorías periódicas). La mayoría de los equipos ejecutan escaneos ligeros de diff en cada PR y programan escaneos completos del historial semanalmente.
Más Allá de Git: Otros Objetivos de Escaneo
Aunque este artículo se enfoca en flujos de trabajo de git, TruffleHog admite objetivos adicionales: sistemas de archivos, buckets de S3 e imágenes Docker. Para la mayoría de los desarrolladores, los escáneres de git y sistema de archivos cubren los casos de uso típicos. Las capacidades más amplias se vuelven relevantes a medida que tu infraestructura crece.
Qué Hacer Cuando se Encuentran Secretos
Encontrar un secreto es solo el primer paso. La respuesta importa más:
- Rota la credencial inmediatamente: asume que está comprometida
- Elimínala del historial de git usando herramientas como BFG Repo-Cleaner o git-filter-repo
- Audita los registros de acceso del servicio afectado para verificar uso no autorizado
- Actualiza tu flujo de trabajo para prevenir filtraciones de credenciales en el control de código fuente en el futuro
Simplemente eliminar el archivo y confirmar nuevamente no ayuda. El secreto permanece en el historial hasta que lo reescribas.
Conclusión
TruffleHog funciona mejor como control preventivo, no solo como herramienta de auditoría. Ejecútalo temprano en CI, idealmente en cada pull request. Cuanto antes detectes una credencial filtrada, menor será el radio de impacto.
Combina el escaneo automatizado con buenas prácticas: usa variables de entorno para secretos, agrega patrones sensibles a .gitignore, y considera hooks de pre-commit para aplicación local.
El escaneo de secretos no eliminará todos los riesgos, pero reduce dramáticamente la ventana entre un error y su descubrimiento. Eso a menudo es la diferencia entre un casi-incidente y un incidente real.
Preguntas Frecuentes
TruffleHog escanea todo el historial de git por defecto, no solo el árbol de trabajo actual. Esto significa que los secretos enterrados en commits antiguos se revelan incluso si fueron eliminados en commits posteriores. El historial inmutable de git preserva todo, por lo que el escaneo exhaustivo es esencial para encontrar todas las credenciales expuestas.
Los hallazgos verificados significan que TruffleHog probó la credencial contra su API real y confirmó que aún está activa. Los hallazgos no verificados coinciden con patrones conocidos de secretos pero no fueron validados. Prioriza los hallazgos verificados para acción inmediata ya que representan credenciales activas y explotables.
Eliminar el archivo y confirmar no eliminará el secreto del historial. Usa herramientas como BFG Repo-Cleaner o git-filter-repo para reescribir el historial de git y purgar la credencial de todos los commits. Después de reescribir, haz force-push al remoto y pide a todos los colaboradores que vuelvan a clonar el repositorio.
Sí, TruffleHog puede ejecutarse como hook de pre-commit para aplicación local. Esto detecta secretos antes de que lleguen a tu repositorio remoto. Combina hooks de pre-commit con integración de CI para defensa en profundidad, asegurando que los secretos se bloqueen tanto localmente como en tu pipeline.
Understand every bug
Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.
