Gestión de secretos para equipos de desarrollo: del .env al vault

Cada aplicación que tu equipo desarrolla y opera depende de decenas de secretos: contraseñas de base de datos, claves de API de pasarelas de pago, tokens de servicios cloud, certificados TLS, credenciales de SMTP, claves de firma de JWT. Y sin embargo, en la mayoría de equipos de desarrollo la gestión de secretos sigue siendo el pariente pobre de la seguridad: un archivo .env que circula por Slack, una clave de AWS pegada en un script de despliegue de 2021 que nadie se atreve a tocar, o un token de Stripe con permisos totales compartido entre producción y staging.

El problema no es teórico. Los informes anuales de GitGuardian llevan años detectando millones de secretos expuestos en repositorios públicos de GitHub — y eso es solo lo visible: los repositorios privados que se vuelven públicos, los portátiles perdidos y los logs que imprimen credenciales no aparecen en ninguna estadística. Una parte enorme de las brechas que analizamos en auditorías no empieza con un exploit sofisticado, sino con una credencial válida que estaba donde no debía.

Esta guía es un recorrido práctico por la gestión de secretos para equipos de desarrollo: qué antipatrones eliminar hoy mismo, cómo es el ciclo de vida completo de un secreto, qué niveles de madurez existen (del .env al vault centralizado), cómo tratar los secretos en CI/CD y Kubernetes, cómo detectar fugas antes que los atacantes y qué exigen exactamente los controles técnicos de ISO 27001 y el ENS en esta materia. Al final tienes un plan de implantación de 90 días pensado para no frenar al equipo.

1. Qué es un secreto y por qué su gestión se ha vuelto crítica

Un secreto es cualquier pieza de información que otorga acceso o capacidad de firma y que, por tanto, debe permanecer confidencial: si se filtra, alguien puede actuar como si fuera tu sistema o tu equipo. La diferencia con otros datos sensibles es operativa: un secreto filtrado no solo hay que «comunicarlo», hay que revocarlo y sustituirlo en todos los sistemas que lo usan, y hacerlo rápido.

1.1 Tipos de secretos en un equipo de desarrollo

En un proyecto web típico conviven varias familias de secretos, cada una con su ciclo de vida y su radio de daño:

• Credenciales de infraestructura: contraseñas de bases de datos, usuarios SSH, claves de acceso a paneles y servidores.
• Claves de API de terceros: Stripe, Redsys, SendGrid, Google Maps, APIs de transportistas… El daño depende de los permisos: una clave de pasarela de pago con permisos de escritura es dinamita.
• Credenciales cloud: access keys de AWS, service accounts de GCP, service principals de Azure. Son el objetivo favorito de los atacantes porque abren la puerta a toda la infraestructura (y a la factura: minado de criptomonedas incluido).
• Secretos criptográficos propios: claves de firma de JWT y cookies de sesión, claves de cifrado de datos en reposo, certificados TLS privados.
• Tokens de maquinaria interna: tokens de CI/CD, webhooks firmados, credenciales de registries de contenedores, tokens de herramientas de automatización.

Este último grupo se olvida con frecuencia y es especialmente delicado en plataformas de automatización: lo analizamos en detalle en nuestra guía de seguridad en n8n: credenciales, permisos y buenas prácticas, donde un solo servidor de workflows puede concentrar las credenciales de media empresa.

1.2 El coste real de una fuga

Cuando un secreto se filtra, el coste tiene tres capas. La inmediata: el uso malicioso (exfiltración de la base de datos, cargos en la pasarela, instancias cloud levantadas para minar). La operativa: rotar la credencial comprometida y todas las que hayan podido verse expuestas en el mismo incidente, con el riesgo de romper servicios que dependían de ella. Y la regulatoria: si hay datos personales implicados, hablamos de notificación a la AEPD en 72 horas bajo RGPD, y de un incidente reportable si estás bajo el paraguas de NIS2 o del ENS. La fuga de una credencial es de las pocas categorías de incidente donde la prevención es radicalmente más barata que la respuesta.

2. Los antipatrones que seguimos viendo en auditorías

Antes de hablar de herramientas, conviene nombrar los tres pecados capitales. Los encontramos una y otra vez en auditorías de seguridad de empresas de todos los tamaños, incluidas algunas con equipos técnicos excelentes.

2.1 Secretos hardcodeados en el repositorio

La clave de API escrita directamente en el código, «solo para probar», que acaba commiteada. El problema no es solo el presente: Git recuerda todo. Aunque borres el secreto en el siguiente commit, sigue en el historial, en los forks, en los clones locales de todo el que haya tocado el repo y en las cachés de las herramientas de análisis. Un secreto que ha entrado en Git debe considerarse comprometido y rotarse: limpiar el historial con git filter-repo es cosmética, no remediación.

2.2 El .env compartido por Slack

El archivo .env fue un avance en su día: sacó los secretos del código. Pero en muchos equipos se ha convertido en el nuevo problema: se comparte por Slack o email cuando entra alguien nuevo («pásame el .env de producción»), vive sin cifrar en decenas de portátiles, nadie sabe qué versión es la buena y, cuando alguien deja la empresa, se va con una copia de todas las credenciales de producción en su disco. El canal de mensajería se convierte en un archivo histórico de secretos consultable por cualquiera que comprometa una cuenta de Slack.

2.3 Secretos eternos: sin rotación, sin caducidad, sin dueño

La access key de AWS creada en 2019 por un desarrollador que ya no está en la empresa y que sigue activa porque «algo la usa y no sabemos qué». Los secretos sin fecha de caducidad ni responsable asignado son deuda de seguridad pura: cuanto más viejo es un secreto, más sitios lo conocen y más caro es rotarlo. Si no puedes rotar una credencial sin miedo, no controlas tu sistema; el atacante que la consiga, sí.

3. El ciclo de vida de un secreto

Gestionar secretos bien no es «usar una herramienta», es cubrir un ciclo de vida completo. Todo secreto pasa (o debería pasar) por seis fases:

1. Generación: el secreto se crea con entropía suficiente y de forma automatizada — nunca «inventado» por una persona ni reutilizado de otro entorno. Idealmente lo genera la propia plataforma de secretos.
2. Almacenamiento: cifrado en reposo, con control de acceso por identidad y registro de auditoría. Aquí es donde el .env plano y el canal de Slack suspenden.
3. Distribución: el secreto llega a la aplicación en tiempo de arranque o de despliegue (inyección como variable de entorno, fichero temporal o llamada a la API del vault), sin pasar por manos humanas.
4. Uso: con el principio de mínimo privilegio: cada servicio ve solo los secretos que necesita, con permisos de solo lectura cuando basta, y sin que acaben en logs, trazas o mensajes de error.
5. Rotación: el secreto se sustituye periódicamente (o tras cada baja en el equipo) de forma automatizada. Si la rotación es manual y dolorosa, no se hará.
6. Revocación: ante una sospecha de fuga, el secreto se invalida de inmediato y el sistema sigue funcionando con el nuevo. El tiempo de revocación es la métrica que separa un susto de una brecha.

La mayoría de equipos cubre razonablemente las fases 3 y 4 y falla en las otras cuatro. La pregunta honesta que hay que hacerse: si ahora mismo se filtrara la contraseña de tu base de datos de producción, ¿cuánto tardarías en rotarla con confianza? Si la respuesta se mide en días, tienes trabajo por delante.

4. Niveles de madurez: del .env al vault

No todas las empresas necesitan lo mismo. Un SaaS con veinte microservicios no tiene los mismos requisitos que una agencia que mantiene diez WordPress. Lo útil es pensar en niveles de madurez e ir subiendo escalones según el riesgo real.

4.1 Nivel 0 y 1: del código al .env con gitignore

El nivel 0 (secretos en el código) es inaceptable en cualquier contexto profesional. El nivel 1 — variables en .env excluido del repositorio con .gitignore, más un .env.example sin valores reales — es el mínimo higiénico. Sigue teniendo los problemas de distribución y rotación descritos arriba, pero al menos separa código y configuración. Si estás aquí, los dos pasos inmediatos son: activar escaneo de secretos en el repositorio (sección 6) y dejar de compartir el archivo por canales de mensajería — herramientas como los envíos autodestructivos de un gestor de contraseñas de equipo (1Password, Bitwarden) resuelven el traspaso puntual.

4.2 Nivel 2: variables de entorno gestionadas y secretos de CI

El siguiente escalón es que los secretos de cada entorno vivan en la plataforma que ejecuta la aplicación: variables cifradas del proveedor de hosting o PaaS, secretos de GitHub Actions o GitLab CI, secretos de Docker/Kubernetes. Los humanos dejan de tener copias locales de producción: el desarrollador trabaja con credenciales de desarrollo y solo la plataforma conoce las de producción. Para equipos pequeños con pocos servicios, este nivel bien ejecutado ya elimina el 80% del riesgo.

4.3 Nivel 3: secrets manager gestionado

Cuando hay varios servicios, varios entornos y varios equipos, conviene centralizar: AWS Secrets Manager, GCP Secret Manager, Azure Key Vault o el más reciente ecosistema de Infisical y Doppler. Aportan lo que el nivel 2 no tiene: un único lugar donde ver qué secretos existen, quién accede a cada uno (auditoría), versionado, rotación automatizada para ciertos tipos (RDS, por ejemplo) y control de acceso fino por rol. El coste es bajo (céntimos por secreto y mes en los gestionados) y la integración con las aplicaciones es directa via SDK o inyección en despliegue.

4.4 Nivel 4: vault centralizado con secretos dinámicos

El escalón superior es un vault centralizado tipo HashiCorp Vault o su fork open source OpenBao: además de almacenar secretos estáticos, puede generar secretos dinámicos — credenciales de base de datos creadas al vuelo para cada servicio o sesión, con TTL de minutos u horas, que caducan solas. El concepto cambia el juego: un secreto que expira en 15 minutos apenas tiene valor para un atacante. A cambio, un vault autogestionado es infraestructura crítica que hay que operar, respaldar y mantener en alta disponibilidad: tiene sentido en organizaciones con equipo de plataforma, no como primer paso de una pyme. La trampa habitual es montarlo, apuntarse el tanto y dejarlo a medias: un vault mal operado es un punto único de fallo.

5. Secretos en CI/CD, contenedores y Kubernetes

La cadena de despliegue es hoy el punto más caliente de la gestión de secretos: el CI/CD necesita credenciales para desplegar, y por eso concentra permisos elevados sobre todo lo demás.

5.1 Buenas prácticas en GitHub Actions y GitLab CI

Las reglas básicas: usar los secrets nativos de la plataforma (nunca variables en claro en el YAML), limitar cada secreto al entorno que lo necesita (environments con aprobación para producción), no imprimir secretos en logs (las plataformas los enmascaran, pero solo si los has declarado como secretos) y desconfiar de las actions de terceros: fijarlas por hash de commit, no por tag, porque una action comprometida puede exfiltrar todos los secretos del job. Los ataques a la cadena de suministro via dependencias y pipelines son ya un vector de primer orden, como el desarrollo seguro según ISO 27001 y el ENS recoge explícitamente.

5.2 OIDC: la muerte anunciada de las claves estáticas de despliegue

El avance más importante de los últimos años: la federación OIDC entre el CI y el cloud. En lugar de guardar una access key de AWS eterna en los secretos de GitHub, el workflow obtiene en cada ejecución un token temporal intercambiando su identidad OIDC por un rol de AWS/GCP/Azure con permisos acotados. Resultado: no hay clave estática que robar, y el permiso vive minutos. Si solo puedes hacer una mejora en tu pipeline este trimestre, que sea esta.

5.3 Contenedores y Kubernetes

En contenedores, tres errores clásicos: hornear secretos en la imagen (quedan en las capas y en el registry para siempre), pasarlos como argumentos de build y confiar en que los Secrets de Kubernetes son seguros por defecto — van en base64, que es codificación, no cifrado. El estándar razonable: cifrado en reposo de etcd activado, RBAC estricto sobre quién lee Secrets, y para subir el listón, External Secrets Operator sincronizando desde el secrets manager del nivel 3, o el patrón de sealed secrets para poder versionar secretos cifrados en Git (GitOps). Y en el borde de la aplicación, recuerda que el secreto también hay que protegerlo en uso: buena parte de los incidentes de seguridad en APIs REST empiezan con un token con permisos excesivos o sin caducidad.

6. Detección de fugas: escaneo y respuesta

Asumir que las fugas ocurrirán es parte de la madurez. La cuestión es detectarlas tú antes que los bots — que escanean cada commit público de GitHub en segundos.

6.1 Escaneo de secretos en el repositorio y el pipeline

Herramientas open source como gitleaks o trufflehog detectan patrones de secretos (y en el caso de trufflehog, verifican si la credencial sigue activa) tanto en el working tree como en todo el historial. La configuración recomendable es en tres capas: hook de pre-commit en las máquinas de los desarrolladores (parar el secreto antes de que entre), job en el CI que falla la build si detecta secretos, y escaneo periódico del historial completo. GitHub ofrece además secret scanning con push protection — gratuito en repos públicos y disponible en los planes de pago para privados — que bloquea el push si detecta un secreto conocido. Un ejemplo mínimo de gitleaks en GitHub Actions:

name: gitleaks
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # historial completo
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

6.2 Qué hacer cuando un secreto se filtra

El orden importa: primero rotar, después investigar. (1) Genera la nueva credencial y despliégala; (2) revoca la antigua; (3) revisa los logs de uso de la credencial comprometida durante toda la ventana de exposición — no desde que te enteraste, sino desde que se filtró; (4) evalúa si hubo acceso a datos personales y si aplica notificación RGPD; (5) haz el post-mortem sin culpables: el objetivo es arreglar el proceso que permitió la fuga, no señalar al que commiteó el .env. Ten este runbook escrito antes de necesitarlo; a las 2 de la mañana de un incidente no es momento de improvisar. Y no olvides los vectores indirectos: muchas credenciales se filtran a través de vulnerabilidades clásicas — SSRF contra metadatos de instancia, inyecciones, configuraciones expuestas — que el OWASP Top 10 lleva años catalogando.

7. Qué exigen ISO 27001 y el ENS

Si tu empresa está certificada o en camino de estarlo, la gestión de secretos no es opcional: es objeto directo de controles. En ISO 27001:2022, el control 5.17 (información de autenticación) exige gestionar la asignación y el ciclo de vida de credenciales; el 8.24 (uso de criptografía) cubre la gestión de claves criptográficas; y la pareja 8.28 (codificación segura) y 8.31 (separación de entornos) apuntala que producción y desarrollo no compartan credenciales y que el código no contenga secretos. Un auditor que encuentre claves hardcodeadas o un .env de producción circulando por Slack tiene una no conformidad servida. En el ENS (RD 311/2022), las medidas op.acc de control de acceso —en particular los requisitos sobre credenciales y su renovación— y mp.info de protección de la información empujan en la misma dirección, con exigencia creciente según el nivel (básico, medio, alto). La buena noticia: todo lo descrito en esta guía — inventario, cifrado en reposo, mínimo privilegio, rotación, auditoría de acceso — es exactamente la evidencia que estas normas piden. Si quieres el mapa completo de controles, tienes el detalle en nuestro análisis de los controles técnicos de ISO 27001.

8. Plan de implantación en 90 días (sin frenar al equipo)

La gestión de secretos fracasa cuando se plantea como un big bang. Este plan por fases funciona en equipos reales:

Días 1-30: visibilidad y sangrado cortado

• Escaneo completo del historial de todos los repositorios con gitleaks/trufflehog. Rotación inmediata de todo lo que aparezca activo.
• Push protection y hook de pre-commit activados en todos los repos.
• Inventario de secretos: qué existe, dónde vive, quién lo conoce, cuándo se rotó por última vez y quién es su dueño. Una hoja de cálculo basta para empezar.
• Prohibición efectiva del traspaso de secretos por chat/email: gestor de contraseñas de equipo para los traspasos puntuales.

Días 31-60: centralización

• Elección de plataforma según tu nivel objetivo (sección 4): para la mayoría de pymes tecnológicas, un secrets manager gestionado es el punto óptimo coste/beneficio.
• Migración de los secretos de producción de los 2-3 servicios más críticos, con inyección en despliegue y eliminación de las copias locales.
• OIDC en el pipeline de despliegue: fuera claves estáticas del CI.

Días 61-90: rotación y rutina

• Rotación automatizada donde la plataforma lo soporte; calendario trimestral para el resto.
• Runbook de revocación escrito y ensayado (un game day de una hora rotando una credencial de staging enseña más que diez documentos).
• Revisión de accesos: baja de empleados = rotación de lo que conocían; es el momento de descubrir si tu inventario era real.
• Métricas al panel del equipo: número de secretos fuera de la plataforma, edad media, tiempo de rotación.

Conclusión

La gestión de secretos es uno de esos temas donde la distancia entre «lo que todo el mundo sabe que hay que hacer» y «lo que se hace» es enorme — hasta que una credencial filtrada la cierra de golpe. La buena noticia es que el camino está muy trillado: cortar las fugas con escaneo automático, centralizar en una plataforma con auditoría y control de acceso, sustituir claves estáticas por credenciales efímeras via OIDC y automatizar la rotación. Nada de esto requiere un equipo de seguridad dedicado; requiere decidir que los secretos son infraestructura, no folclore del equipo. Empieza por el escaneo del historial esta misma semana: es gratis, tarda una tarde y es la vía más rápida de descubrir cuál es tu punto de partida real.

Preguntas frecuentes sobre gestión de secretos

¿Es seguro guardar secretos en las variables de GitHub Actions?

Para la mayoría de equipos, sí: van cifradas, se enmascaran en logs y se pueden acotar por entorno. Los riesgos reales son las actions de terceros comprometidas (fíjalas por hash) y los permisos excesivos del token. Para producción con requisitos altos, combínalas con OIDC y un secrets manager externo.

¿Cada cuánto hay que rotar los secretos?

Depende del tipo: inmediatamente tras cualquier sospecha de fuga o baja de una persona que los conociera; de forma automatizada y frecuente (días u horas) si la plataforma lo permite; y como mínimo revisión trimestral para el resto. Más importante que la frecuencia es la capacidad: si rotar te da miedo, ese es el problema a arreglar.

¿Necesito HashiCorp Vault siendo una pyme?

Probablemente no como primer paso. Un vault autogestionado es infraestructura crítica que hay que operar. El recorrido sensato para una pyme es: higiene de .env + escaneo → secretos de plataforma/CI → secrets manager gestionado (AWS/GCP/Azure, Infisical). El vault con secretos dinámicos aporta valor cuando hay equipo de plataforma y decenas de servicios.

He encontrado una clave en un commit antiguo. ¿Basta con borrarla del historial?

No. Un secreto que ha estado en Git debe considerarse comprometido: pudo ser clonado por cualquiera con acceso en cualquier momento. El orden correcto es rotar la credencial primero y, después, si quieres, limpiar el historial por higiene. Nunca al revés.