From 209cd8463bccab9363bcc8b90ef9bf99aa75bbaf Mon Sep 17 00:00:00 2001 From: Corey Butler <770982+coreybutler@users.noreply.github.com> Date: Mon, 2 Nov 2026 09:02:51 -0600 Subject: [PATCH] docs: document upgrade structured events and nvm_version Cover NVM4701-4703, SIEM event names, and the common nvm_version Payload field for Advanced Logging. Signed-off-by: Corey Butler <770982+coreybutler@users.noreply.github.com> --- docs/features/certified-builds/advanced-logging.md | 6 +++++- docs/guide/siem.md | 5 ++++- docs/troubleshooting/error-codes.md | 5 +++++ 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/features/certified-builds/advanced-logging.md b/docs/features/certified-builds/advanced-logging.md index fd62b54..dd16b42 100644 --- a/docs/features/certified-builds/advanced-logging.md +++ b/docs/features/certified-builds/advanced-logging.md @@ -28,6 +28,7 @@ With Advanced Logging you can answer fleet questions from Event Logs / SIEM pipe - Malware definition updates and malware blocks as Event Log records (not terminal-only) - Network deadline budget hits (`network.deadline_exceeded`) - When policy blocks package-manager lifecycle scripts on an install-class command (`package_manager.lifecycle_scripts_blocked`) +- In-app product upgrades (`nvm.upgrade.started`, `nvm.upgrade.failed`, `nvm.upgrade.blocked`) ## What you get only with this add-on @@ -39,6 +40,9 @@ These records appear on **NVM for Windows/Operational** as structured events (`E | `network.deadline_exceeded` | **NVM4501** | Catalog / mirror / download time budget used up | | `malware.definitions_updated` | **NVM4601** | Successful `malware.db` change | | `malware.package_blocked` | **NVM4602** | Shim blocked a package; terminal still prints without this add-on | +| `nvm.upgrade.started` | **NVM4701** | In-app / notification product upgrade began downloading the installer | +| `nvm.upgrade.failed` | **NVM4702** | Product upgrade download or installer launch failed | +| `nvm.upgrade.blocked` | **NVM4703** | Product upgrade blocked by `disable_upgrade` policy | Module-firewall allow/deny, Node trust failures, and similar conditions still produce classic `Code` values without the add-on. With Advanced Logging they also get queryable `EventName` / `Payload` (for example `package_manager.install`, `firewall.*`, `node.security.*`). @@ -69,7 +73,7 @@ Each Advanced Logging event carries: | Field | Role | |:-|:-| | `EventName` | Stable name for queries (for example `nodejs.executed`) | -| `Payload` | JSON context (user, host, package, paths, and more) | +| `Payload` | JSON context (user, host, package, paths, and more). Every structured payload includes `nvm_version` (the NVM for Windows build that wrote the event) | | `Code` | `NVM####` as `UInt32` (`EventData.Code`) | Structured templates use Event IDs **120** (info), **121** (warning), and **122** (error) on the same Operational channel. diff --git a/docs/guide/siem.md b/docs/guide/siem.md index a3562df..6cfaef3 100644 --- a/docs/guide/siem.md +++ b/docs/guide/siem.md @@ -49,7 +49,7 @@ There is a full list of [Error Codes](../troubleshooting/error-codes) (and expla |Field|Detail| |:-|:-| -|`Payload`|JSON string - Do not look for the NVM number inside this field.| +|`Payload`|JSON string - Do not look for the NVM number inside this field. Structured payloads include `nvm_version` (the NVM for Windows version that wrote the event).| |`Code`|Separate `UInt32` - `Code` is `0` when the event is not an `NVM####` condition.| Collectors flatten EventData in different ways. Use the names your platform created if a sample field is missing. @@ -185,6 +185,9 @@ Match `Code` to the number in [Error Codes](../troubleshooting/error-codes). | `network.deadline_exceeded` | 4501 | `nvm.exe` or `sync.exe` | | `malware.definitions_updated` | 4601 | `sync.exe`. Advanced Logging only. | | `malware.package_blocked` | 4602 | Shim. Advanced Logging only. | +| `nvm.upgrade.started` | 4701 | `sync.exe`. Advanced Logging only. Payload: `from_version`, `to_version`, `outcome`. | +| `nvm.upgrade.failed` | 4702 | `sync.exe`. Advanced Logging only. Payload includes `detail` when available. | +| `nvm.upgrade.blocked` | 4703 | `sync.exe`. Advanced Logging only. `disable_upgrade` policy blocked the upgrade. | | `firewall.elevation_required` | 4404 | `nvm.exe` | | `firewall.invalid_rule` | 4405 | `nvm.exe` | | `firewall.untrusted_module_changed` | 4406 | `nvm.exe` or `proxy` | diff --git a/docs/troubleshooting/error-codes.md b/docs/troubleshooting/error-codes.md index c365330..bd2509b 100644 --- a/docs/troubleshooting/error-codes.md +++ b/docs/troubleshooting/error-codes.md @@ -52,6 +52,9 @@ NVM for Windows uses stable `NVM####` codes in CLI messages, shim/proxy output, | **NVM4501** | Network deadline exceeded | Informational: a catalog, mirror, reachability, or download attempt used up its millisecond budget. Structured event `network.deadline_exceeded` (Certified Builds with Advanced Logging) | | **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, command, `source` (`OpenSSF` or `MalwareBlockList`), and `reason`. The terminal line is `NVM blocked — . (NVM4602)`. It still prints without the advanced logging license. Windows Event ID 120 | +| **NVM4701** | Product upgrade started | Informational, advanced logging only. `nvm upgrade` / notification upgrade began downloading the installer. EventName `nvm.upgrade.started`. Payload: `from_version`, `to_version`, `outcome`, `nvm_version`. Windows Event ID 120 | +| **NVM4702** | Product upgrade failed | Informational, advanced logging only. Download or installer launch failed. EventName `nvm.upgrade.failed`. Payload includes `detail` when available. Windows Event ID 120 | +| **NVM4703** | Product upgrade blocked | Informational, advanced logging only. Machine policy `disable_upgrade` blocked the upgrade. EventName `nvm.upgrade.blocked`. Windows Event ID 120 | ## Ranges @@ -62,6 +65,7 @@ NVM for Windows uses stable `NVM####` codes in CLI messages, shim/proxy output, | **NVM44xx** | NVM Firewall (version / module / trust policy) | | **NVM45xx** | Network deadlines | | **NVM46xx** | Malware feed. Informational and advanced logging only | +| **NVM47xx** | Product self-upgrade. Informational and advanced logging only | ## Tips @@ -74,6 +78,7 @@ NVM for Windows uses stable `NVM####` codes in CLI messages, shim/proxy output, - **NVM4412** is an audit/info event that the lifecycle-script lock was applied to an install-class command. It is not a failed install. Community Builds and Certified Builds without Advanced Logging do not write it. - **NVM4501** is informational, not a failure. The plaintext error names `TimeoutCatalogMs` and `TimeoutCatalogMirrorMs` (or `TimeoutDownloadMs` / `TimeoutReachabilityMs`) and where that budget came from: `machine policy`, `machine settings`, `your settings`, `default`, or `command flag`. - Structured execution and install audits may include `project_name`, `project_path`, `parent_process`, `parent_pid`, and `sid` when the host can resolve them. A missing value is empty or `unknown`. +- Every Advanced Logging structured `Payload` includes `nvm_version` (the NVM for Windows version that wrote the entry) so SIEM queries can filter by product version. - `nodejs.executed` is written on Community and Certified Builds when `LogExecutions` is `1`. No Advanced Logging license. - `package_manager.executed` is written on Certified Builds when `LogExecutions` is `1`. No Advanced Logging license. `package_manager.install` records an allowed install (**NVM4408**) or a blocked install (**NVM4403**). - Symptom-based fixes without a code: [General Troubleshooting](./general).