From 92d0548649ba4ca8f27310ccd938e3216ffdb758 Mon Sep 17 00:00:00 2001 From: coreybutler <770982+coreybutler@users.noreply.github.com> Date: Sun, 18 Oct 2026 23:07:33 -0500 Subject: [PATCH] docs: describe permission grant audit fields Administrators need the registry and security docs to show which allow flags the caller supplied and which ones policy applied or removed. --- docs/cfg/enterprise/ad.md | 3 +++ docs/cfg/enterprise/registry.md | 7 +++++-- docs/features/log.md | 2 ++ docs/guide/security.md | 5 ++++- .../current/cfg/enterprise/ad.md | 3 +++ .../current/cfg/enterprise/registry.md | 7 +++++-- .../docusaurus-plugin-content-docs/current/features/log.md | 2 ++ .../current/guide/security.md | 5 ++++- 8 files changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/cfg/enterprise/ad.md b/docs/cfg/enterprise/ad.md index 9df4184..aa85aa5 100644 --- a/docs/cfg/enterprise/ad.md +++ b/docs/cfg/enterprise/ad.md @@ -125,6 +125,9 @@ Computer Configuration └── Shim mode ├── Enable audit logging ├── Enforce Node.js permission model + ├── Audit Node.js permission grants + ├── Default Node.js permission grants + ├── Allowed Node.js permission grants ├── Prevent modification of global JavaScript prototypes ├── Disallow dynamic code generation from strings └── Configure npm package minimum release age diff --git a/docs/cfg/enterprise/registry.md b/docs/cfg/enterprise/registry.md index 72ade45..b9234a4 100644 --- a/docs/cfg/enterprise/registry.md +++ b/docs/cfg/enterprise/registry.md @@ -46,12 +46,15 @@ See [Administrative Templates](ad) for GPO and Intune deployment. Download ADMX/ |**Disallow eval/string code gen**|`DisableEvalAndStringExecution`|**Overridable** (`disable_eval_and_string_execution`). Shim prepends `--disallow-code-generation-from-strings`, blocking `eval()` and `new Function()` (shim-only). Does not affect `node:vm`.

- `0` = off
- `1` = on

Default: `0`

`REG_DWORD`| |**Disable NVM upgrades**|`DisableUpgrade`|**Overridable.** Block in-app NVM upgrades (does not block AD/GPO package deployment).

- `0` = allowed
- `1` = blocked

Default: `0`

`REG_DWORD`| |**Disable version management**|`Enabled`|**Overridable** (`nvm on`/`nvm off`). Forces version management on or off. When off, NVM does not manage or redirect Node.js commands.

- `0` = off (`nvm off`)
- `1` = on

Default: `1`

`REG_DWORD`| -|**Enforce permission model**|`EnforcePermissionModel`|**Overridable** (`enforce_permission_model`). Shim prepends Node permission-model flag on every `node.exe` launch (shim-only). Default-deny FS/network unless the process passes `--allow-*` at runtime. NVM does not inject `--allow-*` grants.

- Node 23+: `--permission`
- Node 20–22: `--experimental-permission`
- Node <20: no flag (unsupported)

- `0` = off
- `1` = on

Default: `0`

`REG_DWORD`| +|**Enforce permission model**|`EnforcePermissionModel`|**Overridable** (`enforce_permission_model`). Shim prepends Node permission-model flag on every `node.exe` launch (shim-only). Default-deny FS/network unless the process passes `--allow-*` at runtime. NVM injects `--allow-*` only from `DefaultPermissionGrants`, and only when this key itself turns the permission model on.

- Node 23+: `--permission`
- Node 20–22: `--experimental-permission`
- Node <20: no flag (unsupported)

- `0` = off
- `1` = on

Default: `0`

`REG_DWORD`| +|**Permission grant audit**|`PermissionGrantAudit`|**Overridable** (`permission_grant_audit`). When on, or when `EnforcePermissionModel` is on, the node shim writes one `nodejs.permission_grants` event when the caller passed `--allow-*` or a permission-model flag, or when policy applied or removed allow flags. `permission_allow.supplied` is the caller tokens. `permission_allow.applied` is the `DefaultPermissionGrants` tokens inserted. `permission_allow.removed` is the caller `--allow-*` tokens dropped. The same object is on `nodejs.executed` when `LogExecutions` is on. The event does not change the command and does not block. A failed write still starts Node.js. Link mode ignores this key.

- `0` = off
- `1` = on

Default: `0`

`REG_DWORD`| +|**Default permission grants**|`DefaultPermissionGrants`|**Overridable** (`default_permission_grants`). argv tokens inserted immediately after the permission flag when the shim itself injects it. One token per entry, for example `--allow-fs-read=*`. Empty injects nothing. A token the caller already passed is skipped. Ignored when the caller turned the permission model on themselves.

`REG_MULTI_SZ`| +|**Allowed permission grants**|`AllowedPermissionGrants`|**Overridable** (`allowed_permission_grants`). When non-empty, caller `--allow-*` tokens not in this list are removed, only when the shim itself injects the permission flag. Empty leaves caller flags unchanged. `DefaultPermissionGrants` are not filtered by this list. One argv token per entry.

`REG_MULTI_SZ`| |**Freeze V8 global objects**|`FreezeV8GlobalObjects`|**Overridable** (`freeze_v8_global_objects`). Shim prepends `--frozen-intrinsics` so built-in prototypes cannot be patched (shim-only; Node.js 12+). Adds measurable startup cost.

- `0` = off
- `1` = on

Default: `0`

`REG_DWORD`| |**Install root**|`InstallRoot`|**Overridable** (`root`). Directory where Node.js versions are stored. Overrides machine and user preferences.

Default: `%LOCALAPPDATA%\Author Software\nvm\installs`

`REG_SZ`| |**Local install source**|`LocalInstallDir`|**Overridable** (`local_dir`). Alternate local directory for Node.js archives (air-gapped mirrors). Overrides cache.

`REG_SZ`| |**Local install only**|`LocalInstallOnly`|**Overridable** (`local_install_only`). Restrict installs to `LocalInstallDir` only.

- `0` = off
- `1` = on

Default: `0`

`REG_DWORD`| -|**Audit logging**|`LogExecutions`|**Overridable** (`log_executions`). Log every Node.js invocation to the Windows Event Log (shim-only). Most useful on **Audit+** (structured ETW).

- `0` = off
- `1` = on

Default: `0`

`REG_DWORD`| +|**Audit logging**|`LogExecutions`|**Overridable** (`log_executions`). Log every Node.js invocation to the Windows Event Log (shim-only). The event name is `nodejs.executed`. When permission allow flags were supplied, applied, or removed, the payload includes `permission_allow.supplied`, `permission_allow.applied`, and `permission_allow.removed`.

- `0` = off
- `1` = on

Default: `0`

`REG_DWORD`| |**Node.js download mirrors**|`MirrorNode`|**Overridable** (`node_mirror`). Ordered mirror list; first successful response wins. See [Download Mirrors](../features/mirrors). Author `*.author.io` mirrors need Governance licensing — see [Version Firewall + Author Mirror](../features/author-mirror).

Default: `https://nodejs.org/dist`

`REG_MULTI_SZ`| |**npm registry mirrors**|`MirrorNpm`|**Overridable** (`npm_mirror`). Ordered npm registry list. Used as shim registry fallback.

Default: `https://registry.npmjs.org`

`REG_MULTI_SZ`| |**Operating mode**|`OperatingMode`|**Overridable** (`mode`). How NVM for Windows manages Node.js versions.

**Shim** (recommended) uses signed shims to intercept `node`, `npm`, `npx`, `yarn`, and `pnpm`. Required for runtime policies (audit logging, auto-detect, ACL).

**Link** uses NTFS junctions/symlinks on PATH.

Default: `shim`

`REG_SZ`| diff --git a/docs/features/log.md b/docs/features/log.md index c3cb294..1229a16 100644 --- a/docs/features/log.md +++ b/docs/features/log.md @@ -10,6 +10,8 @@ Critical events — installations, configuration changes, and security events Only critical change events are logged by default. Additional logging is available through [configuration](../cfg/core#logging-and-announcements). It is possible to log every `node.exe` / `npm` / `npx` invocation (as well as other major package managers). +Set `LogExecutions` to `1` to record each `node.exe` launch. The event name is `nodejs.executed`. When permission allow flags were supplied, applied, or removed, that event includes `permission_allow.supplied`, `permission_allow.applied`, and `permission_allow.removed`. + :::warning[Event source registration] Community and Certified Builds both register an ETW provider (`NVMWindows.Events.man` + `NVMWindows.Events.dll` next to `nvm.exe`). Look under **Applications and Services Logs → NVM for Windows/Operational**, not only the classic Application log. diff --git a/docs/guide/security.md b/docs/guide/security.md index c39ba2b..4165717 100644 --- a/docs/guide/security.md +++ b/docs/guide/security.md @@ -185,7 +185,10 @@ Most teams never pass Node’s permission model flags. Governance policy can for | Policy | Effect | |:-|:-| -| `EnforcePermissionModel` | Prepend `--permission` (Node 23+) or `--experimental-permission` (20–22). Default-deny FS/network until the process passes `--allow-*`. NVM does not inject grants. | +| `EnforcePermissionModel` | Prepend `--permission` (Node 23+) or `--experimental-permission` (20–22). Default-deny FS/network until the process passes `--allow-*`. NVM injects grants only from `DefaultPermissionGrants`. | +| `PermissionGrantAudit` | Write one `nodejs.permission_grants` event when the caller passes `--allow-*` or a permission flag, or when policy applies or removes allow flags. `permission_allow` records supplied, applied, and removed tokens. Also written when `EnforcePermissionModel` is on. Does not block. The same object is on `nodejs.executed` when `LogExecutions` is on. | +| `DefaultPermissionGrants` | argv tokens inserted after the permission flag when the shim injects that flag. Empty adds nothing. | +| `AllowedPermissionGrants` | When non-empty, drop caller `--allow-*` tokens that are not listed. Empty leaves those flags unchanged. Used only when the shim injects the permission flag. | | `FreezeV8GlobalObjects` | Prepend `--frozen-intrinsics` | | `DisableEvalAndStringExecution` | Prepend `--disallow-code-generation-from-strings` (blocks `eval` / `new Function`; does not cover `node:vm`) | diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cfg/enterprise/ad.md b/i18n/ru/docusaurus-plugin-content-docs/current/cfg/enterprise/ad.md index de3d11c..9d491b8 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/cfg/enterprise/ad.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cfg/enterprise/ad.md @@ -125,6 +125,9 @@ _На контроллере домена:_ └── Режим shim ├── Включить аудит-логирование ├── Применять модель прав Node.js + ├── Аудит grants модели прав Node.js + ├── Grants модели прав Node.js по умолчанию + ├── Разрешённые grants модели прав Node.js ├── Запретить изменение глобальных прототипов JavaScript ├── Запретить динамическую генерацию кода из строк └── Настроить минимальный возраст релиза npm-пакета diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cfg/enterprise/registry.md b/i18n/ru/docusaurus-plugin-content-docs/current/cfg/enterprise/registry.md index a99c5f0..1ed83fe 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/cfg/enterprise/registry.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cfg/enterprise/registry.md @@ -46,12 +46,15 @@ certified: |**Disallow eval/string code gen**|`DisableEvalAndStringExecution`|**Overridable** (`disable_eval_and_string_execution`). Shim добавляет `--disallow-code-generation-from-strings`, блокируя `eval()` и `new Function()` (только shim). Не влияет на `node:vm`.

- `0` = выкл.
- `1` = вкл.

По умолчанию: `0`

`REG_DWORD`| |**Disable NVM upgrades**|`DisableUpgrade`|**Overridable.** Блокировать обновления NVM в приложении (не блокирует развёртывание пакетов AD/GPO).

- `0` = разрешено
- `1` = заблокировано

По умолчанию: `0`

`REG_DWORD`| |**Disable version management**|`Enabled`|**Overridable** (`nvm on`/`nvm off`). Принудительно включает или отключает управление версиями. При выкл. NVM не управляет и не перенаправляет команды Node.js.

- `0` = выкл. (`nvm off`)
- `1` = вкл.

По умолчанию: `1`

`REG_DWORD`| -|**Enforce permission model**|`EnforcePermissionModel`|**Overridable** (`enforce_permission_model`). Shim добавляет флаг permission model Node при каждом запуске `node.exe` (только shim). Запрет FS/сети по умолчанию, если процесс не передаёт `--allow-*` во время выполнения. NVM не добавляет grants `--allow-*`.

- Node 23+: `--permission`
- Node 20–22: `--experimental-permission`
- Node <20: без флага (не поддерживается)

- `0` = выкл.
- `1` = вкл.

По умолчанию: `0`

`REG_DWORD`| +|**Enforce permission model**|`EnforcePermissionModel`|**Overridable** (`enforce_permission_model`). Shim добавляет флаг permission model Node при каждом запуске `node.exe` (только shim). Запрет FS/сети по умолчанию, если процесс не передаёт `--allow-*` во время выполнения. NVM добавляет `--allow-*` только из `DefaultPermissionGrants`, и только когда этот ключ сам включает permission model.

- Node 23+: `--permission`
- Node 20–22: `--experimental-permission`
- Node <20: без флага (не поддерживается)

- `0` = выкл.
- `1` = вкл.

По умолчанию: `0`

`REG_DWORD`| +|**Permission grant audit**|`PermissionGrantAudit`|**Overridable** (`permission_grant_audit`). Когда включено, или когда включён `EnforcePermissionModel`, node shim пишет одно событие `nodejs.permission_grants`, если вызывающий передал `--allow-*` или флаг permission model, либо если политика добавила или удалила allow-флаги. `permission_allow.supplied` — токены вызывающего. `permission_allow.applied` — вставленные токены `DefaultPermissionGrants`. `permission_allow.removed` — удалённые токены `--allow-*` вызывающего. Тот же объект есть в `nodejs.executed`, когда включён `LogExecutions`. Событие не меняет команду и не блокирует её. Ошибка записи всё равно запускает Node.js. Режим link игнорирует этот ключ.

- `0` = выкл.
- `1` = вкл.

По умолчанию: `0`

`REG_DWORD`| +|**Default permission grants**|`DefaultPermissionGrants`|**Overridable** (`default_permission_grants`). Токены argv сразу после флага permission, когда shim сам его добавляет. Один токен на запись, например `--allow-fs-read=*`. Пустой список ничего не добавляет. Токен, который вызывающий уже передал, пропускается. Игнорируется, если вызывающий сам включил permission model.

`REG_MULTI_SZ`| +|**Allowed permission grants**|`AllowedPermissionGrants`|**Overridable** (`allowed_permission_grants`). Если список не пуст, токены `--allow-*` вызывающего, которых нет в списке, удаляются, только когда shim сам добавляет флаг permission. Пустой список оставляет флаги вызывающего. `DefaultPermissionGrants` этим списком не фильтруются. Один токен argv на запись.

`REG_MULTI_SZ`| |**Freeze V8 global objects**|`FreezeV8GlobalObjects`|**Overridable** (`freeze_v8_global_objects`). Shim добавляет `--frozen-intrinsics`, чтобы встроенные прототипы нельзя было изменять (только shim; Node.js 12+). Увеличивает время запуска.

- `0` = выкл.
- `1` = вкл.

По умолчанию: `0`

`REG_DWORD`| |**Install root**|`InstallRoot`|**Overridable** (`root`). Каталог хранения версий Node.js. Переопределяет настройки машины и пользователя.

По умолчанию: `%LOCALAPPDATA%\Author Software\nvm\installs`

`REG_SZ`| |**Local install source**|`LocalInstallDir`|**Overridable** (`local_dir`). Альтернативный локальный каталог архивов Node.js (air-gapped зеркала). Переопределяет кэш.

`REG_SZ`| |**Local install only**|`LocalInstallOnly`|**Overridable** (`local_install_only`). Ограничить установки только `LocalInstallDir`.

- `0` = выкл.
- `1` = вкл.

По умолчанию: `0`

`REG_DWORD`| -|**Audit logging**|`LogExecutions`|**Overridable** (`log_executions`). Журналировать каждый вызов Node.js в журнал событий Windows (только shim). Наиболее полезно на **Audit+** (структурированный ETW).

- `0` = выкл.
- `1` = вкл.

По умолчанию: `0`

`REG_DWORD`| +|**Audit logging**|`LogExecutions`|**Overridable** (`log_executions`). Журналировать каждый вызов Node.js в журнал событий Windows (только shim). Имя события — `nodejs.executed`. Если allow-флаги были переданы, добавлены или удалены, payload содержит `permission_allow.supplied`, `permission_allow.applied` и `permission_allow.removed`.

- `0` = выкл.
- `1` = вкл.

По умолчанию: `0`

`REG_DWORD`| |**Node.js download mirrors**|`MirrorNode`|**Overridable** (`node_mirror`). Упорядоченный список зеркал; побеждает первый успешный ответ. См. [Зеркала загрузки](../features/mirrors). Зеркала Author `*.author.io` требуют лицензию Governance — см. [Version Firewall + Author Mirror](../features/author-mirror).

По умолчанию: `https://nodejs.org/dist`

`REG_MULTI_SZ`| |**npm registry mirrors**|`MirrorNpm`|**Overridable** (`npm_mirror`). Упорядоченный список реестров npm. Используется как fallback реестра shim.

По умолчанию: `https://registry.npmjs.org`

`REG_MULTI_SZ`| |**Operating mode**|`OperatingMode`|**Overridable** (`mode`). Как NVM for Windows управляет версиями Node.js.

**Shim** (рекомендуется) использует подписанные shim для перехвата `node`, `npm`, `npx`, `yarn` и `pnpm`. Нужен для runtime-политик (audit logging, auto-detect, ACL).

**Link** использует NTFS junction/symlink в PATH.

По умолчанию: `shim`

`REG_SZ`| diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/features/log.md b/i18n/ru/docusaurus-plugin-content-docs/current/features/log.md index bf2379c..e7757e2 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/features/log.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/features/log.md @@ -10,6 +10,8 @@ tags: [native-integration] По умолчанию журналируются только критические события изменений. Дополнительное журналирование доступно через [конфигурацию](../cfg/core#logging-and-announcements). Можно логировать каждый вызов `node.exe` / `npm` / `npx` (и других основных менеджеров пакетов). +Установите `LogExecutions` в `1`, чтобы записывать каждый запуск `node.exe`. Имя события — `nodejs.executed`. Если allow-флаги были переданы, добавлены или удалены, событие содержит `permission_allow.supplied`, `permission_allow.applied` и `permission_allow.removed`. + :::warning[Регистрация источника событий] Community и Certified Builds регистрируют ETW provider (`NVMWindows.Events.man` + `NVMWindows.Events.dll` рядом с `nvm.exe`). Смотрите **Applications and Services Logs → NVM for Windows/Operational**, а не только классический Application log. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/guide/security.md b/i18n/ru/docusaurus-plugin-content-docs/current/guide/security.md index 848d279..6f1d1f8 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/guide/security.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/guide/security.md @@ -128,7 +128,10 @@ NVM **сейчас не** применяет allow/deny list **пакетов** | Политика | Эффект | |:-|:-| -| `EnforcePermissionModel` | Добавляет `--permission` (Node 23+) или `--experimental-permission` (20–22). Default-deny FS/network, пока процесс не передаст `--allow-*`. NVM не внедряет grants. | +| `EnforcePermissionModel` | Добавляет `--permission` (Node 23+) или `--experimental-permission` (20–22). Default-deny FS/network, пока процесс не передаст `--allow-*`. NVM внедряет grants только из `DefaultPermissionGrants`. | +| `PermissionGrantAudit` | Одно событие `nodejs.permission_grants`, если вызывающий передал `--allow-*` или флаг permission, либо если политика добавила или удалила allow-флаги. `permission_allow` хранит supplied, applied и removed. Также пишется, когда включён `EnforcePermissionModel`. Не блокирует. Тот же объект есть в `nodejs.executed`, когда включён `LogExecutions`. | +| `DefaultPermissionGrants` | Токены argv после флага permission, когда shim сам добавляет этот флаг. Пустой список ничего не добавляет. | +| `AllowedPermissionGrants` | Если список не пуст, удаляет токены `--allow-*` вызывающего, которых нет в списке. Пустой список оставляет эти флаги. Только когда shim сам добавляет флаг permission. | | `FreezeV8GlobalObjects` | Добавляет `--frozen-intrinsics` | | `DisableEvalAndStringExecution` | Добавляет `--disallow-code-generation-from-strings` (блокирует `eval` / `new Function`; не покрывает `node:vm`) |