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
-
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.
-
Referenciarlo desde la definición de tarea en
infrastructure/service.yml (lista Secrets del contenedor):
-
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):
- Genera el nuevo valor en el proveedor (ej: nuevo
STYTCH_SECRET
en el dashboard de Stytch).
aws ssm put-parameter --overwrite --type SecureString ... (el
helper script ya lo hace).
- 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.
- 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:
- Rotación inmediata del valor comprometido.
- Investigación de uso del valor anterior en CloudTrail.
- 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