From 02e3bc27d0e3d8832104212271fbcb2c49b9ebac Mon Sep 17 00:00:00 2001 From: Hans Ott Date: Tue, 9 Dec 2025 14:38:49 +0100 Subject: [PATCH 1/2] Add note about loading env variables in ESM mode --- docs/esm.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/esm.md b/docs/esm.md index 3a97a8705..5169668c9 100644 --- a/docs/esm.md +++ b/docs/esm.md @@ -15,9 +15,22 @@ Alternatively, you can set the `NODE_OPTIONS` environment variable to include th export NODE_OPTIONS='-r @aikidosec/firewall/instrument' ``` -> [!IMPORTANT] +> [!IMPORTANT] > Please also check the documentation on how to integrate Zen with your used web framework. +## Loading environment variables + +When using `--require`/`-r` to preload the Zen firewall, the instrumentation hook runs before your application code. This means environment variables loaded by packages like `dotenv` will not be available when the firewall starts. + +To ensure `AIKIDO_TOKEN` and other environment variables are available during instrumentation, use Node.js's native `--env-file` flag: + +```sh +node --env-file=.env -r @aikidosec/firewall/instrument your-app.js +``` + +> [!NOTE] +> The `--env-file` flag cannot be used in `NODE_OPTIONS`. + ## Known issues - Zen can not protect ESM sub-dependencies of an ESM package. For example if an ESM package `foo` imports a sub-dependency `bar` that is also an ESM package, Zen will not be able to protect the code in `bar`. This is because the V8 engine does not allow Node.js to observe the evaluation of inner ESM packages (yet). Open issue: [Adding an evaluation hook for v8::Module](https://issues.chromium.org/u/1/issues/384413088). See a full example below. From 1f045b7da4f79d7d12b1907aa930ffb84112a0bc Mon Sep 17 00:00:00 2001 From: Hans Ott Date: Tue, 9 Dec 2025 14:40:03 +0100 Subject: [PATCH 2/2] When Zen starts --- docs/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/esm.md b/docs/esm.md index 5169668c9..0756d5d03 100644 --- a/docs/esm.md +++ b/docs/esm.md @@ -20,7 +20,7 @@ export NODE_OPTIONS='-r @aikidosec/firewall/instrument' ## Loading environment variables -When using `--require`/`-r` to preload the Zen firewall, the instrumentation hook runs before your application code. This means environment variables loaded by packages like `dotenv` will not be available when the firewall starts. +When using `--require`/`-r` to preload the Zen firewall, the instrumentation hook runs before your application code. This means environment variables loaded by packages like `dotenv` will not be available when Zen starts. To ensure `AIKIDO_TOKEN` and other environment variables are available during instrumentation, use Node.js's native `--env-file` flag: