diff --git a/docs/command/nvm/malware.md b/docs/command/nvm/malware.md new file mode 100644 index 0000000..20f8af5 --- /dev/null +++ b/docs/command/nvm/malware.md @@ -0,0 +1,27 @@ +--- +title: malware +sidebar_position: 11 +--- + +# nvm malware + +Show the **local** malware verdict for package names. This command does not POST to an organization URL. + +A block at install time is separate. The package-manager shim prints **NVM4602** and may show a toast. + +## Usage + +```powershell +nvm malware status [ ...] [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| [`status`](./malware/status) | Local verdict for each name. Does not consult a remote policy URL. | + +## Notes + +- `evaluate` and `notify-block` stay internal. The shim calls them during an install. +- Verdicts are not written back to policy. diff --git a/docs/command/nvm/malware/status.md b/docs/command/nvm/malware/status.md new file mode 100644 index 0000000..e6644ed --- /dev/null +++ b/docs/command/nvm/malware/status.md @@ -0,0 +1,71 @@ +--- +title: status +sidebar_position: 1 +--- + +# nvm malware status + +Show the local malware verdict for one or more package names. + +The command reads `malware.db`, `MalwareAllowList`, and (Certified Builds) `MalwareBlockList`. It does **not** POST to an organization HTTPS URL. If that URL is configured, JSON includes `remote_configured` and `remote` is `configured, not consulted`. + +A later `npm install` (or equivalent) still runs the remote check. Use this command to inspect the local lists. + +## Usage + +```powershell +nvm malware status [ ...] [flags] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--json` | Write one JSON array of verdict rows. | + +## Output + +Three aligned columns. No header. Status is `blocked` or `allowed`. + +```text +left-pad blocked recognized as malware by OpenSSF +eslint allowed OpenSSF block overruled by malware acceptance policy +evil allowed Malware block overruled by module trust policy +lodash@1.0.0 allowed OpenSSF block overruled by approved module policy +chalk allowed no malware detected +``` + +| Message | When | +|---------|------| +| recognized as malware by OpenSSF | Name hits `malware.db` | +| blocked by organization malware policy | Certified Builds, local `MalwareBlockList` pattern | +| OpenSSF block overruled by malware acceptance policy | `MalwareAllowList` cleared an OpenSSF hit | +| OpenSSF block overruled by module trust policy | `MalwareTrustConflict=continue` and TrustedModules | +| Malware block overruled by module trust policy | same, for a local org-list hit | +| OpenSSF block overruled by approved module policy | `continue` and ApprovedModules | +| OpenSSF block overruled by approved global module policy | `continue` and ApprovedGlobalModules | +| malware checks skipped | `skip_malware_checks` is on | +| malware definitions are missing or invalid | `malware.db` missing or invalid | +| no malware detected | Name missed every list | + +An `allowed` row with an "overruled" message still means OpenSSF (or the org list) hit. The named policy let it through. + +`--json` uses `status` (`allowed` / `blocked`), `message` (same sentences), and `source` (`OpenSSF`, `MalwareAllowList`, `TrustedModules`, …). + +`MalwareAllowList` wins if it also matches. If more than one grant matches, the source is TrustedModules, then ApprovedModules, then ApprovedGlobalModules. + +Trusted or approved names follow `MalwareTrustConflict`. `continue` matches the shim: `allowed` plus the overruled message. `prevent` (default) still blocks. + +Community Builds ignore `MalwareBlockList`. + +## Examples + +```powershell +nvm malware status left-pad +nvm malware status left-pad@1.0.0 eslint --json +``` + +## Related + +- [Malicious Package Blocker](../../../features/malicious-package-blocker) +- [`nvm cache remove malware`](../cache/remove/malware) diff --git a/docs/features/certified-builds/advanced-logging.md b/docs/features/certified-builds/advanced-logging.md index 32a8cfb..9fd2060 100644 --- a/docs/features/certified-builds/advanced-logging.md +++ b/docs/features/certified-builds/advanced-logging.md @@ -90,7 +90,7 @@ Blocked activities still print in the terminal when Advanced Logging is off, but | Code | Event | Payload | |------|--------|---------| | **NVM4601** | `malware.definitions_updated` | `added`, `removed`, `seq`, `previous_seq` | -| **NVM4602** | `malware.package_blocked` | package name, version when known, command | +| **NVM4602** | `malware.package_blocked` | package name, version when known, command, `source`, `reason` | See [SIEM](../../guide/siem) for queries. See [Error Codes](../../troubleshooting/error-codes) for each `NVM####` value. diff --git a/docs/features/log.md b/docs/features/log.md index 89ff41b..b6f4ca4 100644 --- a/docs/features/log.md +++ b/docs/features/log.md @@ -27,4 +27,4 @@ These events are written only when advanced logging is on. They use Windows Even | Code | Event | Payload | |------|--------|---------| | **NVM4601** | `malware.definitions_updated` | `added`, `removed`, `seq`, `previous_seq` | -| **NVM4602** | `malware.package_blocked` | package name, version when known, command | +| **NVM4602** | `malware.package_blocked` | package name, version when known, command, `source`, `reason` | diff --git a/docs/features/malicious-package-blocker.md b/docs/features/malicious-package-blocker.md index 551b246..a5dd21b 100644 --- a/docs/features/malicious-package-blocker.md +++ b/docs/features/malicious-package-blocker.md @@ -22,6 +22,10 @@ They are on by default on Community Builds and Certified Builds. A match is a terminal error. That install command does not continue. +Each blocked name prints `NVM blocked — . (NVM4602)`. +OpenSSF uses `recognized as malware (OpenSSF)`. +A local organization pattern uses `organization malware block`. +A remote 403 uses `remote malware policy`, then `: ` when the TSV column is present. ## What it checks @@ -85,11 +89,35 @@ Bundled package-manager trust seeds (`npm`, `npx`, `yarn`, `yarnpkg`, `corepack` A malware block does not write `package_manager.install`. **NVM4602** is the record when Advanced Logging is on. +### Remote HTTPS body (Certified Builds) + +When `MalwareBlockList` is one `https://` URL, the shim POSTs hits during install. A **403** body is TSV: + +```text +namedatereason +``` + +`reason` is optional. Empty reason uses `remote malware policy`. A custom reason is used only for that request. It is not written back to policy. + +Local `MalwareBlockList` patterns stay `organization malware block`. They do not take a custom reason. + +### Inspect a name + +```powershell +nvm malware status left-pad +nvm malware status left-pad --json +``` + +`status` is local only. It does not POST. +An `allowed` row whose message says the block was overruled still means OpenSSF (or the org list) hit. That policy let it through. +See [`nvm malware status`](../command/nvm/malware/status). + ## Notifications A hit always prints in the terminal. -When the console is in the background, Windows also shows **Malicious package blocked**. +When the console is in the background, Windows also shows a toast. +The title is **Malicious package blocked** for OpenSSF-only hits, **Organization malware block** for local-list-only hits, and **Package blocked** when sources mix or a remote 403 kept the name. The body names at most three packages, then `and N more`. The cue is `Notification.Reminder`. [`disable_announcements`](../cfg/core#logging-and-announcements) does not hide this toast. @@ -123,7 +151,7 @@ They use Windows Event ID 120 on **NVM for Windows/Operational**. | Code | Event | |:-|:-| | **NVM4601** | `malware.definitions_updated` | -| **NVM4602** | `malware.package_blocked` | +| **NVM4602** | `malware.package_blocked` — package, version, command, `source`, `reason` | See [Event Logging](./log) and [Error Codes](../troubleshooting/error-codes). diff --git a/docs/guide/siem.md b/docs/guide/siem.md index dfe9d56..37e749b 100644 --- a/docs/guide/siem.md +++ b/docs/guide/siem.md @@ -106,7 +106,7 @@ A malware block does not write this event. Use **NVM4602** instead. -Inspect `Payload` for the package name, version when known, and command. +Inspect `Payload` for the package name, version when known, command, `source`, and `reason`. ### Integrity verification failures diff --git a/docs/troubleshooting/error-codes.md b/docs/troubleshooting/error-codes.md index cb79597..f91ee31 100644 --- a/docs/troubleshooting/error-codes.md +++ b/docs/troubleshooting/error-codes.md @@ -38,7 +38,7 @@ NVM for Windows uses stable `NVM####` codes in CLI messages, shim/proxy output, | **NVM4411** | Version firewall blocked a Node.js version | Certified `VersionAllowList` / `VersionBlockList` denied `nvm install`, `nvm use`, or a Certified shim launch. Community ACL is a no-op | | **NVM4412** | Package-manager lifecycle scripts blocked | Audit (non-error), Advanced Logging on Certified Builds only. HKLM `BlockPackageManagerLifecycleScripts` rewrote an install-class command (`install` / `ci` / `add` / …). `npm --version` and `npm run` do not write this event. EventName `package_manager.lifecycle_scripts_blocked`. Windows Event ID 120 | | **NVM4601** | Malware definitions updated | Informational, advanced logging only. A successful `malware.db` write changed the database. Payload: `added`, `removed`, `seq`, `previous_seq`. Windows Event ID 120 | -| **NVM4602** | Malicious package blocked | Informational, advanced logging only. The shim blocked a package before the install audit. Payload includes the package name, version when known, and command. The terminal message still prints without the advanced logging license. Windows Event ID 120 | +| **NVM4602** | Malicious package blocked | Informational, advanced logging only. The shim blocked a package before the install audit. Payload includes the package name, version when known, command, `source` (`OpenSSF`, `MalwareBlockList`, or `remote`), and `reason`. The terminal line is `NVM blocked — . (NVM4602)`. It still prints without the advanced logging license. Windows Event ID 120 | ## Ranges diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/command/nvm/malware.md b/i18n/ru/docusaurus-plugin-content-docs/current/command/nvm/malware.md new file mode 100644 index 0000000..63d3d04 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/command/nvm/malware.md @@ -0,0 +1,27 @@ +--- +title: malware +sidebar_position: 11 +--- + +# nvm malware + +Показать **локальный** вердикт malware для имён пакетов. Эта команда не делает POST на URL организации. + +Блок при установке — отдельно. Shim менеджера пакетов печатает **NVM4602** и может показать toast. + +## Использование + +```powershell +nvm malware status [ ...] [flags] +``` + +## Подкоманды + +| Подкоманда | Описание | +|------------|----------| +| [`status`](./malware/status) | Локальный вердикт для каждого имени. Не обращается к удалённому URL политики. | + +## Примечания + +- `evaluate` и `notify-block` остаются внутренними. Shim вызывает их при установке. +- Вердикты не пишутся обратно в политику. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/command/nvm/malware/status.md b/i18n/ru/docusaurus-plugin-content-docs/current/command/nvm/malware/status.md new file mode 100644 index 0000000..0f31224 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/command/nvm/malware/status.md @@ -0,0 +1,71 @@ +--- +title: status +sidebar_position: 1 +--- + +# nvm malware status + +Показать локальный вердикт malware для одного или нескольких имён пакетов. + +Команда читает `malware.db`, `MalwareAllowList` и (Certified Builds) `MalwareBlockList`. Она **не** делает POST на HTTPS URL организации. Если URL задан, JSON содержит `remote_configured`, а `remote` равно `configured, not consulted`. + +Позже `npm install` (или эквивалент) всё равно выполнит удалённую проверку. Эта команда смотрит локальные списки. + +## Использование + +```powershell +nvm malware status [ ...] [flags] +``` + +## Флаги + +| Флаг | Описание | +|------|----------| +| `--json` | Записать один JSON-массив строк вердикта. | + +## Вывод + +Три выровненных столбца. Без заголовка. Статус — `blocked` или `allowed`. + +```text +left-pad blocked recognized as malware by OpenSSF +eslint allowed OpenSSF block overruled by malware acceptance policy +evil allowed Malware block overruled by module trust policy +lodash@1.0.0 allowed OpenSSF block overruled by approved module policy +chalk allowed no malware detected +``` + +| Сообщение | Когда | +|-----------|-------| +| recognized as malware by OpenSSF | Имя есть в `malware.db` | +| blocked by organization malware policy | Certified Builds, локальный шаблон `MalwareBlockList` | +| OpenSSF block overruled by malware acceptance policy | `MalwareAllowList` снял попадание OpenSSF | +| OpenSSF block overruled by module trust policy | `MalwareTrustConflict=continue` и TrustedModules | +| Malware block overruled by module trust policy | то же, для локального оргсписка | +| OpenSSF block overruled by approved module policy | `continue` и ApprovedModules | +| OpenSSF block overruled by approved global module policy | `continue` и ApprovedGlobalModules | +| malware checks skipped | включён `skip_malware_checks` | +| malware definitions are missing or invalid | нет или неверен `malware.db` | +| no malware detected | Имя не попало ни в один список | + +Строка `allowed` с текстом "overruled" всё равно значит попадание OpenSSF (или оргсписка). Названная политика пропустила имя. + +`--json` использует `status` (`allowed` / `blocked`), `message` (те же фразы) и `source` (`OpenSSF`, `MalwareAllowList`, `TrustedModules`, …). + +`MalwareAllowList` важнее, если тоже совпал. Если грантов несколько, источник — TrustedModules, затем ApprovedModules, затем ApprovedGlobalModules. + +Доверенные или одобренные имена следуют `MalwareTrustConflict`. `continue` совпадает с shim: `allowed` плюс сообщение overruled. `prevent` (по умолчанию) всё равно блокирует. + +Community Builds игнорируют `MalwareBlockList`. + +## Примеры + +```powershell +nvm malware status left-pad +nvm malware status left-pad@1.0.0 eslint --json +``` + +## Связанные материалы + +- [Блокировщик вредоносных пакетов](../../../features/malicious-package-blocker) +- [`nvm cache remove malware`](../cache/remove/malware) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/features/certified-builds/advanced-logging.md b/i18n/ru/docusaurus-plugin-content-docs/current/features/certified-builds/advanced-logging.md index a71838b..469542c 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/features/certified-builds/advanced-logging.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/features/certified-builds/advanced-logging.md @@ -85,7 +85,7 @@ Certified Builds уже пишут в **NVM for Windows/Operational** без э | Код | Событие | Payload | |------|--------|---------| | **NVM4601** | `malware.definitions_updated` | `added`, `removed`, `seq`, `previous_seq` | -| **NVM4602** | `malware.package_blocked` | имя пакета, версия если известна, команда | +| **NVM4602** | `malware.package_blocked` | имя пакета, версия если известна, команда, `source`, `reason` | См. [SIEM](../../guide/siem) для запросов. См. [Коды ошибок](../../troubleshooting/error-codes) для каждого значения `NVM####`. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/features/malicious-package-blocker.md b/i18n/ru/docusaurus-plugin-content-docs/current/features/malicious-package-blocker.md index 4ea101a..5b0459a 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/features/malicious-package-blocker.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/features/malicious-package-blocker.md @@ -22,6 +22,10 @@ Module firewall применяет **ваши** списки allow и deny. Совпадение — терминальная ошибка. Эта команда установки не продолжается. +Каждое заблокированное имя печатает `NVM blocked — . (NVM4602)`. +OpenSSF использует `recognized as malware (OpenSSF)`. +Локальный шаблон организации использует `organization malware block`. +Удалённый 403 использует `remote malware policy`, затем `: `, если колонка TSV есть. ## Что проверяется \{#what-it-checks\} @@ -85,11 +89,35 @@ Certified Builds также читают: Блок malware не пишет `package_manager.install`. **NVM4602** — запись, когда включён Advanced Logging. +### Удалённое тело HTTPS (Certified Builds) \{#remote-https-body-certified-builds\} + +Когда `MalwareBlockList` — один URL `https://`, shim POSTит попадания при установке. Тело **403** — TSV: + +```text +namedatereason +``` + +`reason` необязателен. Пустой reason даёт `remote malware policy`. Свой reason живёт только в этом запросе. Он не пишется обратно в политику. + +Локальные шаблоны `MalwareBlockList` остаются `organization malware block`. Они не берут свой reason. + +### Проверить имя \{#inspect-a-name\} + +```powershell +nvm malware status left-pad +nvm malware status left-pad --json +``` + +`status` только локальный. Он не делает POST. +Строка `allowed` с текстом overruled всё равно значит попадание OpenSSF (или оргсписка). Эта политика пропустила имя. +См. [`nvm malware status`](../command/nvm/malware/status). + ## Уведомления \{#notifications\} Попадание всегда печатается в терминале. -Если консоль в фоне, Windows также показывает **Malicious package blocked**. +Если консоль в фоне, Windows также показывает toast. +Заголовок — **Malicious package blocked** только для OpenSSF, **Organization malware block** только для локального списка, и **Package blocked** при смеси источников или когда удалённый 403 оставил имя. Тело называет не более трёх пакетов, затем `and N more`. Сигнал — `Notification.Reminder`. [`disable_announcements`](../cfg/core#logging-and-announcements) это уведомление не скрывает. @@ -123,7 +151,7 @@ nvm cache remove malware --prompt | Код | Событие | |:-|:-| | **NVM4601** | `malware.definitions_updated` | -| **NVM4602** | `malware.package_blocked` | +| **NVM4602** | `malware.package_blocked` — пакет, версия, команда, `source`, `reason` | См. [журналирование событий](./log) и [коды ошибок](../troubleshooting/error-codes). diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/guide/siem.md b/i18n/ru/docusaurus-plugin-content-docs/current/guide/siem.md index b909f65..c611d32 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/guide/siem.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/guide/siem.md @@ -111,7 +111,7 @@ Certified Builds пишут `package_manager.install`, когда межсете -Смотрите `Payload` для имени пакета, версии если известна, и команды. +Смотрите `Payload` для имени пакета, версии если известна, команды, `source` и `reason`. ## Сбои проверки целостности \{#integrity-verification-failures\} diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/troubleshooting/error-codes.md b/i18n/ru/docusaurus-plugin-content-docs/current/troubleshooting/error-codes.md index 9798c6d..96dd597 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/troubleshooting/error-codes.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/troubleshooting/error-codes.md @@ -32,6 +32,8 @@ NVM for Windows использует стабильные коды `NVM####` в | **NVM4410** | Изменена политика firewall | Аудит: `nvm firewall` изменил список политики | | **NVM4411** | Version firewall заблокировал версию Node.js | Certified `VersionAllowList` / `VersionBlockList` отклонил `nvm install`, `nvm use` или запуск Certified shim. Community ACL — no-op | | **NVM4412** | Заблокированы lifecycle-скрипты package manager | Аудит (не ошибка), только Advanced Logging на Certified Builds. HKLM `BlockPackageManagerLifecycleScripts` переписал install-команду (`install` / `ci` / `add` / …). `npm --version` и `npm run` это событие не пишут. EventName `package_manager.lifecycle_scripts_blocked`. Windows Event ID 120 | +| **NVM4601** | Обновлены определения malware | Информационное, только Advanced Logging. Успешная запись `malware.db` изменила базу. Payload: `added`, `removed`, `seq`, `previous_seq`. Windows Event ID 120 | +| **NVM4602** | Заблокирован вредоносный пакет | Информационное, только Advanced Logging. Shim заблокировал пакет до install-аудита. Payload: имя пакета, версия если известна, команда, `source` (`OpenSSF`, `MalwareBlockList` или `remote`) и `reason`. Строка терминала: `NVM blocked — . (NVM4602)`. Печатается и без лицензии Advanced Logging. Windows Event ID 120 | ## Диапазоны @@ -40,6 +42,7 @@ NVM for Windows использует стабильные коды `NVM####` в | **NVM41xx** | Установщик / граница поддержки Community layout | | **NVM43xx** | Runtime trust Node, активация, gatekeeping package manager и путь хранения Node | | **NVM44xx** | NVM Firewall (version / module / trust policy) | +| **NVM46xx** | Лента malware. Информационное, только Advanced Logging | ## Подсказки