Detección de secretos expuestos con Gitleaks

Exposición de secretos en código

La exposición de secretos en código ocurre cuando información sensible queda escrita dentro de un repositorio. Un secreto puede ser un token de acceso, una API key, una contraseña, una clave privada, una credencial de base de datos o cualquier valor que permita autenticarse contra un servicio o acceder a un recurso protegido.

Este problema puede aparecer en archivos fuente, archivos de configuración, scripts, variables de entorno copiadas por error, ejemplos de uso, notebooks o historial de commits. El riesgo no depende solo de que el secreto esté en la versión actual del proyecto. Si el valor fue confirmado en un commit anterior, puede seguir existiendo en el historial del repositorio.

La evidencia empírica muestra que este problema no es excepcional. Meli, McNiece y Reaves (2019) analizaron repositorios públicos de GitHub a gran escala y encontraron más de 200.000 secretos únicos, con filtraciones nuevas todos los días. Su trabajo muestra que los secretos expuestos aparecen en código, archivos criptográficos, archivos de datos y archivos de configuración, lo que confirma que la exposición puede ocurrir en distintas partes del repositorio.

Desde la perspectiva de seguridad, la exposición de secretos afecta directamente la confidencialidad. Una persona no autorizada que obtiene un secreto válido puede leer datos privados, consultar APIs internas, descargar artefactos, acceder a servicios externos o moverse hacia otros sistemas. Si el secreto además tiene permisos de escritura o administración, el impacto puede extenderse a integridad y disponibilidad.

Por qué es un problema de seguridad

Un secreto expuesto puede permitir acceso no autorizado sin explotar una vulnerabilidad tradicional del software. El atacante no necesita romper un algoritmo criptográfico ni evadir un mecanismo complejo si ya posee una credencial válida. Por eso, una API key o una clave privada confirmada por error en un repositorio puede transformarse en una vía directa de compromiso.

Meli et al. (2019) estimaron que la mayoría de los secretos descubiertos en su estudio eran sensibles. También observaron que muchos secretos no desaparecen rápidamente después de ser publicados. Incluso cuando una persona elimina el valor de la versión visible del archivo, Git puede conservarlo en commits anteriores. Esto hace que la mitigación correcta no sea solo borrar la línea afectada, sino también revocar o rotar el secreto.

La detección de secretos complementa otros controles de seguridad de aplicaciones. En el marco de OWASP Top 10, este tipo de revisión ayuda a reducir riesgos asociados a malas configuraciones, exposición de información sensible y fallas en la gestión de credenciales.

Qué permite hacer Gitleaks

Gitleaks es una herramienta de análisis orientada a detectar secretos expuestos en repositorios Git, directorios de trabajo y otros conjuntos de archivos. Su propósito es identificar patrones compatibles con credenciales antes de que sean usados indebidamente o antes de que lleguen a ramas compartidas, servidores remotos o procesos de distribución.

Gitleaks analiza el contenido de los archivos y el historial Git usando reglas de detección. Estas reglas buscan cadenas que se parecen a secretos reales, como tokens de proveedores cloud, claves de APIs, credenciales embebidas, llaves privadas y valores de autenticación asociados a servicios conocidos. Esta estrategia es consistente con la observación de Meli et al. (2019): muchos secretos tienen estructuras distintivas, por ejemplo prefijos, longitudes o encabezados reconocibles, que permiten construir detectores basados en patrones.

Gitleaks puede usarse de forma local durante el desarrollo, como parte de una revisión manual o dentro de un pipeline de integración continua. En todos los casos, el objetivo es identificar secretos presentes en el repositorio para corregirlos antes de que se propaguen o para documentar una exposición que ya ocurrió.

Problemas que detecta

Gitleaks detecta valores que tienen apariencia de secretos. Entre los casos frecuentes están tokens de acceso personal, API keys de servicios externos, credenciales de plataformas cloud, contraseñas escritas en texto plano, claves privadas SSH, secretos de webhooks, tokens de CI/CD y cadenas de conexión que incluyen usuario y contraseña.

El estudio de Meli et al. (2019) muestra ejemplos concretos de este tipo de exposición: claves de Google, AWS, Twitter, Facebook, MailGun, MailChimp, Stripe, Twilio y claves privadas RSA, EC y PGP. Estos ejemplos son relevantes porque representan credenciales que pueden afectar privacidad, integridad de datos, abuso de servicios, costos económicos o acceso a infraestructura.

Un hallazgo de Gitleaks no significa siempre que el secreto siga activo, pero sí indica que existe una cadena sensible o potencialmente sensible dentro del material analizado. Por eso el resultado debe revisarse y, cuando corresponda, el secreto debe revocarse, rotarse y eliminarse del repositorio y de su historial. Meli et al. (2019) advierten que algunos secretos pueden ser inválidos, de prueba o ya revocados, pero aun así la presencia de un patrón sensible debe tratarse como un evento de seguridad hasta ser verificado.

Output de Gitleaks

Gitleaks genera resultados estructurados que describen cada hallazgo. En formato JSON, cada resultado incluye campos como la regla que produjo la detección, una descripción del problema, el archivo afectado, la línea donde aparece el valor, el commit asociado cuando aplica, el autor, la fecha, la huella del hallazgo y fragmentos del contenido detectado.

Esta estructura permite revisar los hallazgos de manera manual o integrarlos en herramientas de automatización. El archivo de salida puede almacenarse como evidencia del análisis, procesarse en un pipeline o usarse para priorizar la corrección de secretos expuestos.

La existencia de un output estructurado es importante porque la detección de secretos requiere trazabilidad. Para corregir el problema se necesita saber qué regla se activó, dónde aparece el valor, en qué archivo está y si pertenece al estado actual del repositorio o al historial. Esa información permite distinguir entre un secreto nuevo, un secreto heredado y un falso positivo.

Uso básico

Un uso básico de Gitleaks sobre el directorio actual es el siguiente:

gitleaks detect -s . -f json -r results.json

El parámetro detect ejecuta el análisis de secretos. La opción -s . indica que la fuente a revisar es el directorio actual. La opción -f json define que el formato de salida será JSON. La opción -r results.json guarda los resultados en el archivo results.json.

Si Gitleaks encuentra secretos o valores compatibles con reglas de detección, el archivo results.json contendrá una lista de hallazgos con la ubicación y los metadatos necesarios para revisarlos. Si no se encuentran hallazgos, el resultado indica que no se detectaron secretos bajo las reglas aplicadas.

Interpretación de resultados

El resultado de Gitleaks debe interpretarse como una señal de posible exposición. El primer paso es identificar el archivo, la línea y la regla asociada. Luego se debe determinar si el valor corresponde a una credencial real, una credencial de prueba, un ejemplo documentado o un falso positivo.

Cuando el valor corresponde a un secreto real, la acción segura es revocarlo o rotarlo. Borrar el archivo o modificar el commit más reciente no basta si el secreto ya fue publicado. Meli et al. (2019) muestran que los secretos pueden persistir en GitHub y que la detección cercana al momento del commit es importante porque un atacante puede monitorear repositorios públicos casi en tiempo real.

Referencias

Gitleaks. (s. f.). Gitleaks. GitHub. https://github.com/gitleaks/gitleaks

Meli, M., McNiece, M. R., & Reaves, B. (2019). How bad can it Git? Characterizing secret leakage in public GitHub repositories. Network and Distributed System Security Symposium.

OWASP Foundation. (s. f.). OWASP Top Ten. https://owasp.org/www-project-top-ten/