All of Woku’s sensitive credentials (database connection
strings, JWT keys, third-party API keys, Stytch SSO tokens,
etc.) are stored in AWS SSM Parameter Store as SecureString
and injected into the container in production at startup.
Model
- Storage: AWS SSM Parameter Store, region
us-east-1,
under the prefix /shared/prod/secrets/. Type SecureString (encrypted
with KMS, key alias/aws/ssm).
- Injection: Amazon ECS reads each parameter and delivers it to the
container as an environment variable (
process.env) when the task
starts. Each secret is declared in the Secrets list of the service
task definition (infrastructure/service.yml).
- Permissions: the ECS task execution role has a policy
scoped to
ssm:GetParameters + kms:Decrypt only over the prefix
/shared/prod/secrets/*. It cannot read other parameters in the
account.
Auditability
- Every read of a parameter is recorded in AWS CloudTrail.
- Every change (
PutParameter, DeleteParameter) is recorded in CloudTrail
as well, with the IAM identity of the author.
- KMS logs
Decrypt operations separately in CloudTrail
(data events if they are enabled).
Why not AWS Secrets Manager?
SSM Parameter Store SecureString offers the same KMS encryption as
Secrets Manager and the same isolation guarantee. The main
difference is the built-in automatic rotation (RDS / DocumentDB /
Lambda), which we currently do not need. Choosing SSM saves us
the per-secret cost of Secrets Manager (~$0.40/month each)
while keeping the encryption and audit guarantees.
What we do NOT do
- ❌ We never commit secrets to the repository. There is a
.dockerignore that excludes .env and .env.* from the Docker image;
local files never reach production.
- ❌ We never pass secrets as inline arguments in CI/CLI.
They end up in the shell history and in CI logs. They are exported to the
environment before running the command that needs them.
- ❌ We never put secrets in the manifest
variables: (that
section is in plain text inside the CloudFormation stack).
Environments
Current state: some local installations have production values
mixed with sandbox inside their .env. The goal is
for the local .env to contain only dev/sandbox values (local
Mongo, Stytch sandbox project, Paddle sandbox, etc.) and for any
connection to production resources to go exclusively through SSM when
the container comes up in AWS.
If you need a new secret in production, follow
the procedure.
Adding a new secret
-
Upload the value to SSM. Export the value in your shell and use the
helper that lives in the repo:
The script uploads every variable that is exported to
/shared/prod/secrets/<NOMBRE> as SecureString. It silently
skips the ones that are not set.
-
Reference it from the task definition in
infrastructure/service.yml (the container Secrets list):
-
Deploy. The next deploy (push to
main) brings up the container
with the variable available in process.env.MI_SECRET_NUEVO.
Rotating a secret
For credentials without automatic rotation (everything we have today):
- Generate the new value in the provider (e.g.: new
STYTCH_SECRET
in the Stytch dashboard).
aws ssm put-parameter --overwrite --type SecureString ... (the
helper script already does this).
- Force a new deployment of the service so the tasks pick up the new
value:
aws ecs update-service --cluster <cluster> --service <service> --force-new-deployment.
- Revoke the previous value in the provider.
The container does not detect changes in SSM live. The values are
read only once at startup. That is why you must always
redeploy after rotating.
Reporting a leak
If you discover an exposed secret (in a public repo, in logs, in a
PR, in a screenshot), send the details to team@woku.app. The
response process:
- Immediate rotation of the compromised value.
- Investigation of the previous value’s usage in CloudTrail.
- Customer notification if the rotation affects their integrations.
The default SLA is 4 business hours, or whatever your Corporate
contract stipulates if it requires a shorter time. Última modificación el 26 de octubre de 2026