Dónde guardar las claves de tu aplicación: gestores de secretos y escáneres
Las API keys en un archivo .env viajan por el historial de Git, el JavaScript del navegador y cualquier programa local. Gestores de secretos, escáneres automáticos y rotación: la guía práctica.
Un hábito extendido merece una revisión a fondo: guardar las claves de una aplicación en un archivo .env. El archivo reúne todas las llaves en texto plano, y la experiencia acumulada de la industria muestra que esas llaves terminan apareciendo en más lugares de los planeados. La buena noticia: el ecosistema ya tiene una respuesta madura, con gestores de secretos, escáneres automáticos y rutinas de rotación que cualquier equipo adopta en una semana. Esta guía recorre el panorama completo: por dónde viajan las claves, quién las busca, cómo se monta la defensa pieza por pieza y qué rutina la mantiene vigente.
Tres caminos por los que viajan las claves
El primero es el historial de Git. Un commit con el .env dentro queda registrado de forma permanente: borrar el archivo en el commit siguiente deja intacta la versión anterior, y cualquier persona con acceso al repositorio puede recuperarla. Los repositorios públicos multiplican el alcance, y hasta un repositorio privado compartido con colaboradores amplía el círculo de copias.
El segundo camino es el front-end. Las variables de entorno que usa el navegador terminan compiladas dentro del JavaScript que se descarga en cada visita. Cualquier visitante puede abrir las herramientas de desarrollo y leerlas. La regla práctica: toda variable que llega al navegador es pública por diseño, y merece tratarse como tal desde el primer día.
El tercero es la propia computadora. Cualquier programa que se ejecuta con los permisos de la persona usuaria puede leer ese archivo: dependencias, scripts de build, extensiones del editor. Un archivo .env concentra todo el tesoro en una sola dirección conocida, y cada herramienta instalada amplía la lista de lectores potenciales.
Quién aprovecha esas filtraciones
La búsqueda es automática. Programas especializados recorren commits públicos y prueban las claves que encuentran a los pocos minutos de publicadas. La unidad de investigación Unit 42 de Palo Alto Networks documentó el fenómeno con un experimento controlado: publicaron claves de AWS en GitHub y registraron intentos de uso en cuestión de minutos, dentro de una campaña que llamaron Elektra-Leak. El hallazgo central: la velocidad de aprovechamiento se mide en minutos, y la defensa se mide en hábitos.
El escaneo tampoco se limita a GitHub. Existen campañas que recorren miles de servidores buscando archivos .env accesibles desde la web, y paquetes maliciosos publicados en registros de dependencias que, al instalarse, buscan secretos en la computadora de la persona desarrolladora. La cadena de suministro convierte cada instalación en una decisión de confianza, y una buena higiene de dependencias complementa al gestor de secretos.
El uso típico de una clave capturada es inmediato y medible: minería de criptomonedas contra la cuenta, acceso a datos almacenados, cargos que escalan en horas. Unit 42 registró operaciones completas montadas sobre claves expuestas, con automatización para encontrarlas, probarlas y explotarlas. La lección práctica es de calendario: cada minuto que una clave pasa publicada cuenta, y la rotación veloz reduce la ventana a su mínima expresión.
La respuesta madura: un gestor de secretos
Un gestor de secretos concentra las claves en un servicio diseñado para custodiarlas. OpenBao, la bifurcación comunitaria de Vault, Infisical y Doppler son tres opciones activas y bien mantenidas. El patrón es el mismo en las tres: las claves viven cifradas en un solo lugar, cada persona y cada servicio recibe acceso a lo estrictamente necesario, y la aplicación obtiene los valores al arrancar, inyectados en memoria en el momento de ejecutarse.
El cambio de modelo ordena la operación completa. Circula una versión única y controlada, con bitácora de accesos: quién leyó qué, cuándo y desde dónde. Cuando una persona cambia de equipo, revocar su acceso es una acción de un paso, en lugar de perseguir copias por laptops y canales de chat. Y rotar una clave se convierte en una operación centralizada que se propaga a todos los servicios que la usan.
Paso a paso: montar el gestor
OpenBao
OpenBao es la bifurcación comunitaria de Vault, con licencia abierta y desarrollo en público. La forma rápida de probarlo es el modo de desarrollo sobre la propia máquina: se instala el binario desde openbao.org, se arranca el servidor de pruebas y se guarda el primer secreto.
bao server -dev -dev-root-token-id=root
export BAO_ADDR=http://127.0.0.1:8200
bao kv put secret/mi-app STRIPE_KEY=sk_live_ejemplo OPENAI_KEY=sk-proj-ejemplo
bao kv get secret/mi-appEl cuarto comando devuelve los valores al instante. En producción el servidor corre con almacenamiento cifrado y sellado, y cada servicio recibe un token de alcance mínimo mediante políticas: la app de ventas lee únicamente la ruta secret/ventas, y la bitácora registra cada lectura. La aplicación recoge sus valores al arrancar mediante el CLI, el agente inyector o las librerías cliente, y el contenedor oficial facilita el despliegue en cualquier infraestructura propia.
Infisical
Infisical combina nube administrada y opción autohospedada, todo open source. El flujo empieza creando un proyecto en la interfaz web, y el CLI enlaza la carpeta local con ese proyecto en pocos comandos.
brew install infisical/get-cli/infisical
infisical login
infisical init
infisical run -- npm run devEl último comando arranca la app con las variables inyectadas en memoria: los valores viajan cifrados desde el servicio y se entregan al proceso en el momento de ejecutarse. Cada entorno (desarrollo, staging, producción) guarda su propio juego de valores dentro del mismo proyecto, y la interfaz muestra el historial de cambios valor por valor, con la opción de volver a cualquier versión anterior.
Doppler
Doppler apuesta por la experiencia de uso. Tras crear la cuenta, cada proyecto tiene configuraciones por entorno, y el CLI sigue el mismo patrón: autenticarse, enlazar la carpeta y arrancar la app con inyección.
brew install dopplerhq/cli/doppler
doppler login
doppler setup
doppler run -- npm run devLa sincronización con proveedores de nube y plataformas de despliegue viene lista: al actualizar un valor en Doppler, los entornos conectados reciben el cambio y los despliegues posteriores lo traen consigo. Para equipos que valoran una curva de adopción corta, el conjunto resulta muy directo.
Cómo elegir entre las opciones
OpenBao se instala en infraestructura propia: control total de los datos y la operación, ideal para equipos con capacidad de administrar servicios. Infisical es open source y ofrece ambas modalidades, autohospedado o nube administrada, con una interfaz moderna. Doppler apuesta por la experiencia de uso: sincronización entre entornos, integraciones listas y una curva de adopción muy corta. Los tres manejan inyección en tiempo de ejecución, control de acceso por persona y bitácora.
Los criterios de decisión son tres: dónde prefieren residir los datos, cuánta operación quiere cargar el equipo y qué integraciones necesita el flujo de trabajo actual. Un proyecto pequeño avanza rápido con la nube administrada; una operación con requisitos de residencia de datos se inclina por el autohospedado. Un piloto con un proyecto y un entorno responde la pregunta de ajuste en una semana, antes de cualquier despliegue amplio.
Paso a paso: el escáner que vigila cada push
La segunda pieza de la defensa es automática: un escáner de secretos revisa cada commit antes de que llegue al repositorio. Gitleaks y TruffleHog son las dos herramientas de referencia, ambas abiertas y gratuitas, y reconocen cientos de patrones: claves de AWS, tokens de GitHub, claves de OpenAI, cadenas de conexión a bases de datos.
Gitleaks
Gitleaks audita el repositorio completo y vigila cada cambio nuevo. La primera ejecución recorre el historial entero en segundos, y el hook de pre-commit filtra cada commit desde la propia laptop.
brew install gitleaks
gitleaks git -v .
brew install pre-commit
pre-commit installEl archivo .pre-commit-config.yaml queda así, con la etiqueta ajustada a la versión vigente del proyecto (pre-commit autoupdate la actualiza):
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.24.3
hooks:
- id: gitleaksEl mismo filtro corre en el pipeline como paso automático en cada push, con la acción oficial gitleaks-action para GitHub o el binario en cualquier otro proveedor de integración continua. Una clave que intenta entrar al historial queda detenida en la laptop o en el pipeline, con el archivo y la línea señalados para su corrección inmediata.
name: gitleaks
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: gitleaks/gitleaks-action@v2TruffleHog
TruffleHog complementa con verificación activa: prueba cada hallazgo contra el proveedor correspondiente y reporta únicamente las credenciales que siguen vigentes. Ese filtro concentra la atención en lo que requiere acción inmediata.
brew install trufflesecurity/trufflehog/trufflehog
trufflehog git file://$(pwd) --only-verifiedUna ejecución mensual sobre el historial completo mantiene la certeza de que el pasado sigue limpio, y el modo verificado marca con claridad cualquier clave activa que aparezca. Entre el hook de pre-commit, el paso del pipeline y la auditoría mensual, el repositorio queda vigilado en sus tres momentos: antes del commit, en cada push y a lo largo de la historia.
La rotación como rutina
La rotación periódica acota la vida útil de cada clave: aunque una copia llegara a circular, su ventana de utilidad queda medida en días. La cadencia habitual es trimestral para claves de servicios externos y mensual para las de mayor alcance, con rotación inmediata ante cualquier exposición detectada.
La técnica de doble clave permite rotar con el servicio siempre disponible: el proveedor emite la clave nueva, los servicios la adoptan mientras la anterior sigue aceptada, y la revocación de la vieja llega al final, una vez confirmado el cambio. Los gestores centralizan la operación: el valor nuevo se publica en la ruta correspondiente y cada servicio lo recoge en su siguiente arranque o recarga.
El archivo .env conserva un lugar
La recomendación apunta al contenido, y el formato sigue siendo útil para el desarrollo local. La convención sana: un archivo .env.example dentro del repositorio con los nombres de las variables y valores de muestra, y el .env real fuera del control de versiones, listado en .gitignore desde el primer commit. Los valores reales llegan al entorno local desde el gestor, con un comando que los inyecta al arrancar la app.
# .env.example
STRIPE_KEY=pega_el_valor_aqui
OPENAI_KEY=pega_el_valor_aquiEl archivo de muestra documenta cada variable que la app espera, así que preparar un entorno nuevo significa copiar la plantilla y pedir los valores reales al gestor.
Si una clave ya apareció en público
La respuesta correcta es la rotación inmediata: revocar la clave expuesta y generar una nueva. Borrar el commit deja el historial intacto, y los bots ya copiaron el valor en los primeros minutos, así que la limpieza del repositorio ocupa el segundo lugar, una vez asegurada la puerta. Los proveedores de nube y de APIs ofrecen la revocación desde el panel en segundos, y varios incluso revocan de forma automática las claves que detectan publicadas.
Después de la rotación conviene una revisión breve. Los registros de uso del proveedor muestran si la clave tuvo actividad ajena, y el escáner confirma que el resto del repositorio quedó libre de valores sensibles. El incidente se convierte en una práctica de rutina: medir, rotar, verificar, documentar.
Una guía de respuesta escrita acorta esa primera reacción. Cabe en una página: quién revoca en cada proveedor, dónde viven los registros de uso, quién avisa al equipo y cómo se documenta el incidente. Los equipos que ensayan la guía una vez por trimestre atienden una exposición en minutos, con la misma calma de un despliegue cualquiera.
El cambio también mejora el trabajo diario. Incorporar a una persona desarrolladora significa otorgarle acceso acotado en el gestor, y su salida significa revocarlo, con cada lectura registrada entre ambos momentos. Los entornos nuevos arrancan con los valores correctos desde el primer día, y la versión vigente de cada clave vive en un solo lugar, consultable y auditada.
Lista de verificación
- .env listado en .gitignore desde el primer commit, y .env.example con nombres y valores de muestra
- Gestor de secretos elegido, con proyecto y entornos creados
- CLI del gestor instalado en cada laptop, con inyección al arrancar la app
- Escáner instalado como hook de pre-commit y como paso del pipeline
- Historial completo auditado con Gitleaks y TruffleHog en modo verificado
- Claves que circularon por archivos o chats rotadas y reemplazadas
- Acceso por persona y por servicio con alcance mínimo
- Guía de respuesta ante exposición escrita en una página y ensayada
- Rotación trimestral agendada en el calendario del equipo
Una rutina de una semana
El plan completo cabe en cinco días. Día uno: agregar .env al .gitignore y mover las claves actuales a un gestor. Día dos: instalar el escáner como hook local y como paso del pipeline. Día tres: rotar todas las claves que alguna vez circularon por un archivo o un chat. Día cuatro: definir quién accede a qué, con el mínimo privilegio por persona y por servicio. Día cinco: documentar la rutina de rotación trimestral y la respuesta ante exposición. El resultado: las claves dejan de depender del cuidado individual y pasan a depender del sistema.
La versión de una línea para compartir con el equipo: las claves viven en un gestor, el escáner vigila cada push y toda exposición termina en rotación inmediata.
Fuentes
¿Te fue útil este artículo?