Saltar al contenido principal
Todas las credenciales sensibles de Woku (cadenas de conexión a base de datos, claves JWT, API keys de terceros, tokens de Stytch SSO, etc.) se almacenan en AWS SSM Parameter Store como SecureString y se inyectan al container en producción al momento de arrancar.

Modelo

  • Almacenamiento: AWS SSM Parameter Store, región us-east-1, bajo el prefijo /shared/prod/secrets/. Tipo SecureString (cifrado con KMS, llave alias/aws/ssm).
  • Inyección: Amazon ECS lee cada parámetro y lo entrega al container como variable de entorno (process.env) al iniciar la tarea. Cada secreto se declara en la lista Secrets de la definición de tarea del servicio (infrastructure/service.yml).
  • Permisos: el rol de ejecución de la tarea ECS tiene una policy acotada a ssm:GetParameters + kms:Decrypt solo sobre el prefijo /shared/prod/secrets/*. No puede leer otros parámetros de la cuenta.

Auditabilidad

  • Cada lectura de un parámetro queda en AWS CloudTrail.
  • Cada cambio (PutParameter, DeleteParameter) queda en CloudTrail también, con identidad IAM del autor.
  • KMS registra las operaciones Decrypt por separado en CloudTrail (data events si están habilitados).

¿Por qué no AWS Secrets Manager?

SSM Parameter Store SecureString ofrece el mismo cifrado KMS que Secrets Manager y la misma garantía de aislamiento. La diferencia principal es la rotación automática integrada (RDS / DocumentDB / Lambda), que actualmente no necesitamos. La elección de SSM nos ahorra el costo per-secret de Secrets Manager (~$0.40/mes c/u) manteniendo las garantías de cifrado y auditoría.

Lo que NO se hace

  • ❌ Nunca commiteamos secrets al repositorio. Hay un .dockerignore que excluye .env y .env.* de la imagen Docker; los archivos locales jamás llegan a producción.
  • ❌ Nunca pasamos secrets como argumentos en CI/CLI inline. Quedan en el shell history y en logs de CI. Se exportan al entorno antes de ejecutar el comando que los necesita.
  • ❌ Nunca se ponen secrets en variables: del manifest (esa sección está en texto plano dentro del CloudFormation stack).

Entornos

Estado actual: algunas instalaciones locales tienen valores de producción mezclados con sandbox dentro de su .env. El objetivo es que el .env local contenga solo valores de dev/sandbox (Mongo local, Stytch sandbox project, Paddle sandbox, etc.) y que cualquier conexión a recursos productivos pase exclusivamente por SSM al levantar el container en AWS.
Si necesitas un secret nuevo en producción, sigue el procedimiento.

Agregar un secret nuevo

  1. Subir el valor a SSM. Exporta el valor en tu shell y usa el helper que vive en el repo:
    El script sube cada variable que esté exportada a /shared/prod/secrets/<NOMBRE> como SecureString. Skipea silenciosamente las que no estén seteadas.
  2. Referenciarlo desde la definición de tarea en infrastructure/service.yml (lista Secrets del contenedor):
  3. Deploy. El siguiente deploy (push a main) levanta el container con la variable disponible en process.env.MI_SECRET_NUEVO.

Rotar un secret

Para credenciales sin rotación automática (todo lo que tenemos hoy):
  1. Genera el nuevo valor en el proveedor (ej: nuevo STYTCH_SECRET en el dashboard de Stytch).
  2. aws ssm put-parameter --overwrite --type SecureString ... (el helper script ya lo hace).
  3. Forzar un despliegue nuevo del servicio para que las tareas tomen el valor nuevo: aws ecs update-service --cluster <cluster> --service <servicio> --force-new-deployment.
  4. Revoca el valor anterior en el proveedor.
El container no detecta cambios en SSM en vivo. Los valores se leen una sola vez al arrancar. Por eso siempre hay que redeployar después de rotar.

Reportar un leak

Si descubres un secret expuesto (en un repo público, en logs, en un PR, en un screenshot), envía el detalle a team@woku.app. El proceso de respuesta:
  1. Rotación inmediata del valor comprometido.
  2. Investigación de uso del valor anterior en CloudTrail.
  3. Notificación al cliente si la rotación afecta sus integraciones.
El SLA por defecto es 4 horas hábiles, o lo que pacte tu contrato Corporate si exige un tiempo menor.
Última modificación el 26 de octubre de 2026