Guías de seguridad
Detén los secretos antes de hacerles commit con gitleaks: atrapa fugas de claves de API antes del push
Haz commit de una clave de API por accidente y se queda en el historial de Git, filtrada para siempre. Cómo gitleaks detiene los secretos en dos puertas — un hook de pre-commit y CI — más el paso de revocación que la detección por sí sola no completa.
Para: cualquiera que use Git en desarrollo en solitario o en equipo pequeño, preocupado por «¿y si hago commit de una clave de API por accidente?» Aquí no hay mecánica de atacante — solo la maquinaria para impedir que los secretos se filtren fuera de tu propio repositorio.
La visión de este sitio: .gitignore por sí solo no puede proteger los secretos
«Mi .env está en .gitignore, así que estoy bien» es una frase común — y tiene agujeros. .gitignore solo impide que se sigan archivos nuevos; no puede atrapar secretos que ya tienen commit, los forzados con prisa con git add -f, ni nombres inesperados como .env.local.bak. Bloquea solo parte de la entrada. Necesitas algo que de verdad mire el contenido de los commits y marque las «cadenas con aspecto de secreto» — un detector. Para eso sirve gitleaks.
Por qué detenerlo «antes del commit»
Los secretos son peligrosos porque Git conserva el historial para siempre. Bórralo del archivo más reciente y permanece en commits pasados. Y en el momento en que se hace push, ese historial se copia a otras máquinas, servidores y registros de CI.
Así que la defensa de secretos trata en realidad de la prevención antes de la fuga, no de la recuperación después. Es la misma idea que el inventario «no dejar secretos en un directorio público» (→ el inventario de la raíz web), llevada al mundo del código.
Dónde van las puertas
En el camino que recorre un secreto desde el código hasta el mundo, puedes colocar dos puertas: en el momento del commit local, y justo antes de que se comparta (CI).
secreto en el código
clave de API, clave, token
puerta 1: pre-commit
detectar y abortar localmente al hacer commit
puerta 2: CI / cron
detectar tras el push, antes del merge/despliegue
público / compartido
pasado aquí, trátalo como filtrado
Cómo conectar gitleaks
Escanea primero el historial existente
gitleaks detect. Sacar a la luz los secretos dormidos en commits pasados es el primer trabajo. Cualquier cosa que se encuentre aquí se asume que necesita revocación, como abajo.Construye la puerta 1 con un hook de pre-commit
gitleaks protect --staged en cada commit para abortar en el acto cualquier commit que contenga un secreto. Añádelo a un framework de pre-commit (.pre-commit-config.yaml) para que la misma comprobación aplique para todos, localmente.Construye la puerta 2 en CI / cron
gitleaks detect como trabajo de CI — o, para montajes autoalojados, como escaneo periódico — para atrapar lo que se cuela (la misma mentalidad de monitoreo por máquina que las auditorías de dependencias).Ajusta los falsos positivos en .gitleaks.toml
.gitleaks.toml. La práctica correcta es no «silenciarlo» sino «registrar por qué es seguro» — una exclusión sin justificación es la semilla del próximo incidente.En la detección, «revocar» va primero; reescribir el historial va después
Cuando encuentres un secreto que tuvo commit y push, la máxima prioridad es revocar y reemitir (rotar) esa clave o token. Borrarlo del historial con git filter-repo importa, pero es solo limpieza para «detener que se propague más». Asume que un secreto que llegó a un repo público, un fork, un registro de CI o el clon de otra persona es irrecuperable — invalídalo primero, luego limpia el historial. Invierte el orden y se usa mientras aún estás borrando.
Confiar en .gitignore
- solo evita el nuevo seguimiento
- los secretos que ya tienen commit pasan de largo
- impotente frente a
git add -fo nombres de archivo raros - no puede verificar «no quería añadir eso»
gitleaks (detección + práctica de revocación)
- de verdad inspecciona el árbol de trabajo y el contenido del historial
- lo detiene en dos puertas: pre-commit y CI
- en la detección, un procedimiento que llega hasta la revocación
- falsos positivos excluidos con una justificación registrada
Lo que hace este sitio
Este sitio se construye sobre una base de mantener los secretos totalmente fuera de Git — las cadenas de conexión y las claves de API viven solo en configuración protegida en el servidor (un archivo env con permisos restringidos), nunca en texto plano en el repo ni en notas de traspaso (→ mantener los secretos fuera de git / Git autoalojado vs GitHub). Sobre eso, superponemos detectores partiendo de que los humanos siempre resbalan. El diseño garantiza «no lo metas», y un escaneo como gitleaks atrapa «se metió igualmente» — esas dos capas son la defensa de este sitio contra las fugas de secretos. El principio de manejar secretos en sí es continuo con los archivos .env y secretos y guardar contraseñas de forma segura.
Leer a continuación
- Inventario: ¿estás dejando secretos en un directorio público?
- Autoalojamiento: mantener los secretos fuera de git / Git autoalojado vs GitHub
- Glosario: qué es «.env» — qué pasa cuando se filtra un archivo env
- Herramienta: escáner de fugas de secretos (pega y comprueba)
FAQ
Q¿Qué es gitleaks?
Una herramienta gratuita que escanea el árbol de trabajo y el historial de commits de un repositorio Git para detectar si se han hecho commit de secretos — claves de API, claves privadas, tokens. Encuentra «cadenas con aspecto de secreto» con reglas regex y entropía de cadenas (aleatoriedad), y puede ejecutarse como hook de pre-commit o en CI para comprobaciones automáticas.
Q¿No protege los secretos ponerlos en .gitignore?
No basta. .gitignore solo detiene el «nuevo seguimiento» — no puede detectar secretos que ya tienen commit, ni los forzados con git add -f. Bloquea solo parte del accidente, así que combínalo con un detector como gitleaks tanto en pre-commit como en CI.
Q¿Qué hago si accidentalmente hice commit y push de un secreto?
Trata ese secreto como filtrado. La máxima prioridad no es reescribir el historial sino revocar y rotar (reemitir) la clave o el token expuesto. Asume que un secreto que llegó a un repo público o a un registro no puede recuperarse — invalídalo primero, luego limpia el historial y añade prevención (gitleaks).