From 36d6c1acd2a3e92bf2655964c83551f84fb38fb5 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sat, 19 Sep 2026 13:47:05 +0000 Subject: [PATCH 1/2] src,lib: add --allow-env permission Necessarily semver-major. When `--permission` is on, every env var not matched by `--allow-env` is removed at startup. It takes names, patterns (`PREFI_*`), or `*`, repeatable or comma-sep'd. There are a range of env vars that Node.js itself uses, and a default range that are generally known to be safe in common usage. These are never scrubbed. These include things like `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `PATH`, `HOME`, etc. Env vars can be dropped at runtime after reading using `permission.drop()`. This is a stronger protection than using `process.env.FOO = undefined` because it will scrub the env var also from the environment block. On Linux, the removed entries are overwritten in the initial environment block and fs reads of /proc/*/environ are denied. On Windows, removal also clears the C runtime's copy of the environ using _wputenv_s Reading a removed name returns undefined, warns once per name, and publishes to a diagnostics channel. Env file keys are allowed. If the user had reason to pass in an env file the assumption is they meant to allow them. File-source config (node.config.json and NODE_OPTIONS from a .env file can only narrow the allow list. Embedders must call ScrubProcessEnvironment() themselves on startup. This is left up to the embedder to determine the exact timing but needs to be called before startup actually happens. Child processes are started with `--allow-env=*`. Those either receive the explicit env they were started with or only the env they inherit from the parent. Since the parent process is scrubbed, it should never be more than what the parent can see. Main part of the impl was done by hand. Docs, tests, verification pass, and cleanup nits were automated. Signed-off-by: James M Snell Assisted-by: Opencode --- doc/api/cli.md | 48 ++ doc/api/embedding.md | 47 ++ doc/api/permissions.md | 108 +++- doc/api/process.md | 3 + doc/node.1 | 39 ++ lib/child_process.js | 12 + lib/internal/process/permission.js | 1 + node.gyp | 2 + src/env.cc | 15 + src/node.cc | 161 +++++- src/node.h | 36 ++ src/node_dotenv.cc | 9 + src/node_dotenv.h | 7 + src/node_env_var.cc | 50 ++ src/node_options.cc | 15 + src/node_options.h | 1 + src/permission/env_permission.cc | 499 ++++++++++++++++++ src/permission/env_permission.h | 121 +++++ src/permission/permission.cc | 39 +- src/permission/permission.h | 3 + src/permission/permission_base.h | 5 +- test/cctest/test_env_permission.cc | 83 +++ test/embedding/embedtest.cc | 22 + .../test-embedding-permission-env.js | 75 +++ .../test-fs-readdir-recursive-permission.js | 1 + ...on-audit-fs-lstat-symlink-does-not-deny.js | 2 +- .../test-permission-env-child-process.js | 77 +++ test/parallel/test-permission-env-cli.js | 41 ++ .../test-permission-env-config-file.js | 99 ++++ test/parallel/test-permission-env-drop.js | 70 +++ test/parallel/test-permission-env-file.js | 71 +++ .../test-permission-env-proc-environ.js | 84 +++ test/parallel/test-permission-env-scrub.js | 164 ++++++ test/parallel/test-permission-env-warning.js | 95 ++++ test/parallel/test-permission-fs-read.js | 4 +- ...test-permission-fs-symlink-target-write.js | 3 +- test/parallel/test-permission-fs-symlink.js | 3 +- .../test-permission-fs-traversal-path.js | 3 +- .../test-permission-fs-write-report.js | 2 +- test/parallel/test-permission-fs-write.js | 3 +- .../test-permission-has-reference-types.js | 1 + test/parallel/test-permission-net-fetch.js | 1 + test/parallel/test-permission-net-tcp.js | 1 + test/parallel/test-permission-net-warning.js | 2 +- .../parallel/test-permission-openssl-store.js | 2 +- 45 files changed, 2107 insertions(+), 23 deletions(-) create mode 100644 src/permission/env_permission.cc create mode 100644 src/permission/env_permission.h create mode 100644 test/cctest/test_env_permission.cc create mode 100644 test/embedding/test-embedding-permission-env.js create mode 100644 test/parallel/test-permission-env-child-process.js create mode 100644 test/parallel/test-permission-env-cli.js create mode 100644 test/parallel/test-permission-env-config-file.js create mode 100644 test/parallel/test-permission-env-drop.js create mode 100644 test/parallel/test-permission-env-file.js create mode 100644 test/parallel/test-permission-env-proc-environ.js create mode 100644 test/parallel/test-permission-env-scrub.js create mode 100644 test/parallel/test-permission-env-warning.js diff --git a/doc/api/cli.md b/doc/api/cli.md index 1fd1e9864338..3d0e86aaa5a4 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -191,6 +191,50 @@ This behavior also applies to `child_process.spawn()`, but in that case, the flags are propagated via the `NODE_OPTIONS` environment variable rather than directly through the process arguments. +### `--allow-env` + + + +> Stability: 1.1 - Active development + +When using the [Permission Model][], the process starts without the environment +variables it has not been granted access to. At startup, every variable that +`--allow-env` does not match is removed from the process environment. Removed +variables are absent from `process.env`, from diagnostic reports, from native +code calling `getenv()`, and from the environment of child processes and worker +threads. + +The valid values are: + +* `*` - Grants access to every environment variable. +* A variable name, for example `--allow-env=DATABASE_URL`. +* A variable name prefix followed by `*`, for example `--allow-env=APP_*`. + +Multiple values can be passed by repeating the flag, or by separating them with +commas: `--allow-env=PORT,APP_*`. Variable names are case-insensitive on +Windows. + +Example: + +```js +console.log(process.env.DATABASE_URL); +console.log(process.env.AWS_SECRET_ACCESS_KEY); +``` + +```console +$ node --permission --allow-fs-read=* --allow-env=DATABASE_URL index.js +postgres://localhost/app +undefined +(node:1234) Warning: The permission model removed the environment variable "AWS_SECRET_ACCESS_KEY" at startup. Use --allow-env to manage permissions. +``` + +The variables that Node.js and its bundled dependencies read, such as +`NODE_OPTIONS`, `PATH`, `HOME`, `TZ`, and `SSL_CERT_FILE`, are always kept, as +are the variables defined in [`--env-file`][] files. See +[Environment variable permissions][] for details. + ### `--allow-ffi` + +When the arguments passed to `node::InitializeOncePerProcess()` enable the +[Permission Model][] without `--allow-env=*`, the process environment must not +contain any variable that [`--allow-env`][] does not grant access to. +`node::InitializeOncePerProcess()` fails otherwise. Unlike the `node` +executable, embedders own the process environment, so Node.js does not remove +these variables itself. + +`node::ScrubProcessEnvironment()` removes them. Because it modifies the process +environment without any locking that native code calling `getenv()` +participates in, it must be called before starting any thread that may read the +environment, and before `node::InitializeOncePerProcess()`: + +```cpp +int main(int argc, char** argv) { + argv = uv_setup_args(argc, argv); + std::vector args(argv, argv + argc); + + // Keep the variables the embedder itself reads, in addition to the ones + // Node.js reads (see node::GetRuntimeEnvironmentDefaults()). + node::ProcessEnvironmentScrubOptions scrub_options; + scrub_options.allow = {"PORT", "APP_*"}; + if (node::ScrubProcessEnvironment(scrub_options).IsNothing()) { + return 1; + } + + // args contains, for example, --permission --allow-env=PORT + std::unique_ptr result = + node::InitializeOncePerProcess(args, { + node::ProcessInitializationFlags::kNoInitializeV8, + node::ProcessInitializationFlags::kNoInitializeNodeV8Platform + }); + // ... +} +``` + +`process.permission.drop('env', name)` removes a variable from the process +environment, so it throws when called from a `node::Environment` created +without `node::EnvironmentFlags::kOwnsProcessState`. + ### Setting up a per-instance state