Micare
Seguridad

Escaneo de secretos antes de cada commit

Hook que revisa los archivos modificados antes de cada commit de git y bloquea la subida si detecta credenciales o llaves de API (tokens de acceso), para que nunca se te escape un secreto al repositorio.

HookPremiumSeguridad

🌱 Empieza aquí · Escaneo de secretos antes de cada commit

Para ti (el humano)

Dile a tu asistente:

"Siembra esta semilla 🌱"

Y ya. Tu asistente hace todo lo técnico. Tú solo confirmas cuando te pregunte.

¿Otras formas de decírselo? "instala este hook", "pon a funcionar el escaneo de secretos", "activa el guardián de credenciales". Te entiende igual.

Esta semilla instala un hook (gancho de automatización): un guardián silencioso que revisa tus archivos justo antes de cada commit de git y detiene la operación si detecta una contraseña, una llave de API (token de acceso) o cualquier credencial a punto de subirse por error a tu repositorio.

Para el asistente que siembra

Eres el asistente. Instala este hook siguiendo estos pasos. No le pidas al humano nada técnico; tú resuelves y solo confirmas lo delicado.

1. Copia el script del kernel

Copia kernel/git-secret-scan.sh a la carpeta de hooks de la plataforma del usuario:

  • Claude Code / Cowork: cópialo a <TU-RUTA> (recomendado: ~/.claude/hooks/git-secret-scan.sh).
    • En macOS/Linux ~/.claude/hooks/ ya existe o se crea con mkdir -p ~/.claude/hooks.
    • En Windows la ruta equivalente es %USERPROFILE%\.claude\hooks\.
mkdir -p ~/.claude/hooks
cp kernel/git-secret-scan.sh ~/.claude/hooks/git-secret-scan.sh

2. Dale permiso de ejecución (macOS / Linux)

chmod +x ~/.claude/hooks/git-secret-scan.sh

En Windows este paso no aplica (se invoca con bash, que viene con Git para Windows).

3. Conéctalo como hook PreToolUse en settings.json

Abre el settings.json del usuario (~/.claude/settings.json) y agrega este bloque dentro de hooks. Si ya existe una sección PreToolUse, añade el objeto al arreglo existente, no lo dupliques.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/git-secret-scan.sh"
          }
        ]
      }
    ]
  }
}

matcher: "Bash" hace que el hook se dispare antes de cada comando de terminal. El propio script se filtra solo: únicamente actúa cuando el comando es un git commit; para todo lo demás sale al instante sin molestar.

4. Verificación post-siembra (obligatoria)

Comprueba con un repositorio de prueba desechable que el guardián bloquea de verdad. Copia y corre esto tal cual:

SB="$(mktemp -d)"; cd "$SB"; git init -q
printf 'GOOGLE_API_KEY=AIzaSyA0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6\n' > config.txt
bash ~/.claude/hooks/git-secret-scan.sh; echo "codigo=$?"

Salida esperada:

BLOQUEADO: se detectaron posibles secretos en: config.txt
Detalle guardado en .secret-detected — mueve el secreto antes de hacer commit.
codigo=2

Si viste codigo=2 y el mensaje BLOQUEADO, el guardián funciona. (La llave del ejemplo es falsa, solo tiene el formato correcto para la prueba.) El directorio $SB es temporal y el sistema lo limpia solo.

Notas de configuración

  • <TU-RUTA> = carpeta de hooks donde copiaste el script (~/.claude/hooks/ por defecto).
  • .git-secret-scan-allowlist (opcional) = archivo en la raíz de un repo, con una ruta por línea, para saltar archivos que dan falso positivo (por ejemplo, documentación que menciona una llave de ejemplo).
  • .secret-detected = reporte que el hook deja en la raíz del repo cuando encuentra algo. Conviene agregarlo a .gitignore para que no se suba.
  • El script no depende de rutas fijas: opera sobre el repositorio git donde se ejecuta (git rev-parse --show-toplevel).

¿Cómo sé que funcionó?

A partir de ahora, cada vez que tu asistente vaya a hacer commit, este guardián revisa primero. Si todo está limpio, ni te enteras: el commit pasa normal. Si detecta una credencial a punto de subirse, detiene el commit y te avisa qué archivo revisar. Tú decides: sacas el secreto a un lugar seguro, o (si fue una falsa alarma) tu asistente lo agrega a la lista de excepciones. Tu repositorio queda protegido sin que tengas que acordarte de revisar nada.