Desarrollo seguro: Parte 2 — Secretos en el código

Un secreto — cualquier dato que da acceso a un recurso: la contraseña de la base de datos, la clave API de un sistema de pagos o de la nube, el token de un bot, la clave SSH privada. Si ese secreto llegó a Git, eliminarlo en el siguiente commit no arregla nada: Git guarda todo el historial, y la versión antigua del archivo está disponible para cualquiera que tenga una copia del repositorio. Escáneres automáticos revisan constantemente los repositorios públicos, por lo que una clave que apareció en un commit público debe considerarse comprometida de inmediato.

Si el secreto ya se ha filtrado

El orden de las acciones es más importante que las herramientas:

1. Revocar o cambiar el secreto con el proveedor: crear una clave nueva, desactivar la anterior, cambiar la contraseña de la base de datos. Este es el único paso que realmente cierra el acceso.
2. Revisar los registros de acceso del servicio al que pertenecía la clave: comprobar si alguien ajeno la utilizó.
3. Cambiar los accesos relacionados. Si se filtró una contraseña que se usaba en varios sitios, cambiarla en todos.
4. Solo después de eso limpiar el historial del repositorio. El proyecto Git recomienda para ello git filter-repo en lugar del obsoleto git filter-branch:

# eliminar el archivo de todo el historial
git filter-repo --path config/secrets.yml --invert-paths

# reemplazar líneas según el archivo replacements.txt en todos los commits
git filter-repo --replace-text replacements.txt

Tras reescribir el historial es necesario forzar el envío al repositorio remoto, y todos los participantes deben clonar el proyecto de nuevo. Las copias que ya existen — forks, clones locales, cachés de CI — no se ven afectadas por la limpieza. Por eso esto no sustituye al primer paso, solo elimina las huellas.

Dónde guardar los secretos

• En desarrollo — en el archivo .env, que está listado en .gitignore. En el repositorio se pone .env.example con los nombres de las variables y valores vacíos, para que los colegas sepan qué rellenar.
• En CI/CD — en las variables protegidas del proyecto: masked y protected en GitLab, secrets en GitHub Actions.
• En los servidores — en el entorno del servicio o en un almacén de secretos separado, pero no en el código ni en la imagen Docker.

Si .env ya llegó al repositorio, añadirlo a .gitignore no es suficiente: hay que quitar el archivo del índice con git rm --cached .env — y, por supuesto, cambiar todo lo que contenía.

Gitleaks

Gitleaks busca en repositorios y directorios contraseñas, claves y tokens usando un conjunto de expresiones regulares para cientos de formatos. Licencia MIT, versión vigente en septiembre de 2026 — 8.30.1. El autor declaró la herramienta finalizada: no se añaden nuevas funciones, solo se publican correcciones de seguridad, y el desarrollo continúa en el nuevo proyecto Betterleaks.

Modos de funcionamiento principales:

gitleaks git -v     # проверить всю историю текущего репозитория
gitleaks dir .      # проверить файлы в каталоге без учёта истории

Los comandos detect y protect de versiones antiguas están obsoletos, aunque aún funcionan.

Comprobación antes de cada commit: pre-commit

El framework pre-commit ejecuta comprobaciones automáticamente en cada git commit. Instalación y conexión de Gitleaks:

pip install pre-commit

Archivo .pre-commit-config.yaml en la raíz del proyecto:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks

pre-commit install          # conectar el hook al repositorio
pre-commit run --all-files  # comprobar todos los archivos inmediatamente después de conectarlo
pre-commit autoupdate       # actualizar las versiones de los hooks

Si Gitleaks encuentra un secreto, el commit no se realizará. Se puede omitir la comprobación con la variable SKIP=gitleaks, por lo que el hook local es una comodidad para el desarrollador, no una garantía.

TruffleHog

TruffleHog resuelve la misma tarea, pero puede verificar lo detectado: para muchos tipos de claves consulta la API del proveedor y reporta si la clave sigue activa. Licencia AGPL-3.0, versión vigente — 3.97.5.

trufflehog git https://git.example.ru/team/project.git --results=verified

El flag --results=verified deja en el informe solo las claves confirmadas como activas. Estos hallazgos requieren el cambio inmediato del secreto.

Comprobación en el servidor

Dado que la comprobación local puede desactivarse, se repite en el pipeline — como la primera tarea, antes de la compilación y las pruebas. Para GitHub Actions Gitleaks tiene una acción lista gitleaks-action; en GitLab CI y Gitea Actions basta con una tarea que ejecute gitleaks git en el directorio del proyecto. Dicha tarea debe detener el pipeline ante cualquier hallazgo.

GitHub también tiene su propia protección — push protection. Para cuentas personales está activada por defecto y no permite enviar un secreto a un repositorio público. La protección a nivel de repositorio, que funciona también para proyectos privados, requiere la función de pago GitHub Secret Protection y la habilita un administrador.

Errores típicos

• Eliminar el archivo con un nuevo commit y considerar el problema resuelto. El secreto permanece en el historial.
• Limpiar el historial en lugar de cambiar la clave. Ya existen copias del repositorio.
• Imprimir secretos en los registros del CI. El comando echo $TOKEN para depuración imprime la clave en el log de la build; las variables protegidas se enmascaran, pero no conviene confiar solo en eso.
• Pasar secretos a la imagen Docker mediante ARG o ENV. Se quedan en las capas de la imagen; la forma correcta es usar secretos de BuildKit.
• La misma clave para desarrollo y producción. La filtración del entorno de pruebas abre acceso al entorno de producción.