windows_updates

How it works

installed and missing each read update state through a different mechanism per OS and emit whatever shape that mechanism naturally returns — there is no shared cross-platform schema. installed runs first: a bounded WMI query on Windows, rpm --last falling back to apt list --installed on Linux, system_profiler SPInstallHistoryDataType on macOS. missing mirrors that fan-out with a different mechanism per OS (WUA COM search, apt/yum, softwareupdate -l). On Windows this is not a single blocking call: do_missing calls IUpdateSearcher::BeginSearch (async) then polls ISearchJob::get_IsCompleted every 500ms until it returns true or a 120s deadline elapses (windows_updates_plugin.cpp:381-398) — the real WUA search against the Windows Update service is what makes this action’s measured runtime (~12s in the capture below) far longer than every other action here, all of which are local reads. pending_reboot is independent of both — three-to-four per-OS existence/comparison checks, each written as its own row, folded into one trailing reboot_required summary row. patch_connectivity is the odd one out: a pure network probe (DNS + TCP, no update-manager call at all) against either the caller’s targets parameter or a built-in per-OS default list, so it is the plugin’s only action that takes parameters and the only one whose mechanism is identical on every OS.

This plugin is deliberately never a mutator: it has no install/patch-apply action anywhere in it (that lives in other plugins, e.g. sccm, software_actions). It is also deliberately not an exhaustive history: installed is bounded (512 rows on Windows, 50 lines on Linux, 100 matched lines on macOS), never a full historical log.

flowchart LR
  OP[Operator / workflow] --> SRV[Server<br/>authz: SoftwareDeployment.Read]
  SRV -- gRPC mTLS --> HOST[Agent plugin host] --> EX[windows_updates.execute]
  EX --> WIN[Windows leg<br/>WMI Win32_QuickFixEngineering<br/>WUA COM async search<br/>registry presence checks<br/>BSD sockets]
  EX --> MAC[macOS leg<br/>system_profiler<br/>softwareupdate -l<br/>BSD sockets]
  EX --> LIN[Linux leg<br/>rpm / apt / yum<br/>filesystem + uname + needs-restarting<br/>BSD sockets]
  WIN & MAC & LIN --> ROWS[rows + typed result status<br/>only on installed/missing] --> RS[(ResponseStore)] --> API[REST /api/responses]
  ROWS -.-> PF["/auto Pre-flight<br/>reboot readiness check"]

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• pending_reboot / macOS — bounded (60s deadline) since this migration, but still a slow network call — no longer able to hang indefinitely on an offline/headless Mac

Privileges and prerequisites

No row exists in docs/agent-privilege-model.md for windows_updates.

Binaries/subprocesses: Linux — /usr/bin/rpm, /usr/bin/apt, /usr/bin/yum (argv, ADR-3002 rung 2) plus uname -r / ls -t /boot/vmlinuz-* / needs-restarting -r (rung 3 shell strings via popen, grandfathered, tracked #2380). macOS — /usr/sbin/system_profiler, /usr/sbin/softwareupdate (argv). Windows — none (in-process WMI/WUA COM/registry). Network: patch_connectivity’s DNS resolution + TCP connect on every OS; missing’s Windows WUA search and macOS softwareupdate -l call also reach a vendor update service.

Data contract

Inputs

patch_connectivity’s definition (device.windows_updates.patch_connectivity) is declared in content/definitions/t2_capabilities.yaml, not in this plugin’s own windows_updates.yaml — see Siblings below.

Outputs

Pipe-delimited rows, one write_output() call per line. installed and missing are not a single stable schema: the field count and the meaning of each field vary by OS, and on Linux by which tool ran (rpm vs its apt fallback for installed; apt vs its yum fallback for missing). pending_reboot is a stable 3-field source|pending|detail shape for every row including the summary. patch_connectivity multiplexes three distinct row shapes (DNS, TCP, summary) as tag|value pairs after a shared target|<url>| (or summary|) prefix — an unpopulated field is simply absent from that row, never a - placeholder.

device.windows_updates.installed — identifier|description|install_date

device.windows_updates.missing — title|severity

device.windows_updates.patch_connectivity — target|dns_ok|dns_ms|ip|tcp_ok|tcp_ms|tcp_error|targets_tested|targets_reachable|targets_failed

device.windows_updates.pending_reboot — source|pending|detail

workflow.patch_connectivity_audit — target|dns_ok|dns_ms|tcp_ok|tcp_ms|targets_tested|targets_reachable|targets_failed

Result status

Where the data goes

• Instruction result only. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore, queryable at /api/responses/{id}. The dashboard renders every action of this plugin generically as Agent/Key/Value rows (result_parsing.hpp’s kKeyValuePlugins), not a plugin-specific table.
• pending_reboot also feeds /auto Pre-flight. preflight_parse.hpp parses its trailing reboot_required|<bool>|<reasons> row as an unconditional summary for the “reboot” readiness check.
• Not consumed by the daily-sync inventory framework (ADR-0016), Echo, DEX, or metrics.
• Sensitivity. installed/missing rows can name specific installed software indirectly — a Windows KB title/description often embeds a product name (e.g. “…for Microsoft Defender Antivirus…”) — an installed-software signal by another route; pending_reboot and patch_connectivity rows carry nothing beyond boolean/timing/target-URL data and the device id.
• Siblings: content/definitions/t2_capabilities.yaml (device.windows_updates.patch_connectivity, the definition that actually declares this action’s parameters and result columns) and content/definitions/t2_chaining_examples.yaml (workflow.patch_connectivity_audit, a two-step compliance workflow chaining patch_connectivity into a log upload). sccm and software_actions cover the mutating side (deploying/applying updates) this plugin deliberately does not.
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("device.windows_updates.installed"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}, plus the /auto Pre-flight page for pending_reboot.

Sample output

Windows — captured: windows Microsoft Windows NT 10.0.26200.0 x64 · bare-metal · 2026-09-07 · SYSTEM · leg-hash 007b2e86015f

== action=installed
update|KB5122385|Update|9/1/2026
update|KB5054156|Update|2/16/2026
update|KB5120998|Update|9/1/2026
update|KB5120997|Update|8/31/2026
[result_status] UNDECLARED / UNKNOWN

== action=missing
available|Security Intelligence Update for Microsoft Defender Antivirus - KB2267602 (Version 1.459.91.0) - Current Channel (Broad)|
[result_status] UNDECLARED / UNKNOWN

== action=pending_reboot
windows_update_reboot|false|
cbs_reboot|false|
pending_file_rename|true|Non-empty value
reboot_required|true|pending_file_rename
[result_status] UNDECLARED / UNKNOWN

== action=patch_connectivity
target|https://windowsupdate.microsoft.com|dns_ok|true|dns_ms|3|ip|128.85.102.70
target|https://windowsupdate.microsoft.com|tcp_ok|true|tcp_ms|160
target|https://update.microsoft.com|dns_ok|true|dns_ms|0|ip|128.85.102.70
target|https://update.microsoft.com|tcp_ok|true|tcp_ms|170
target|https://download.windowsupdate.com|dns_ok|true|dns_ms|7|ip|199.232.54.172
target|https://download.windowsupdate.com|tcp_ok|true|tcp_ms|14
summary|targets_tested|3|targets_reachable|3|targets_failed|0
[result_status] UNDECLARED / UNKNOWN

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-07 · euid 501 (jsmith) · leg-hash 007b2e86015f

== action=installed
update|macOS 26.5.1|18/07/2026, 01:41
update|MAContent10_AssetPack_0048_AlchemyPadsDigitalHolyGhost|18/07/2026, 01:44
update|MAContent10_AssetPack_0310_UB_DrumMachineDesignerGB|18/07/2026, 01:44
update|MAContent10_AssetPack_0312_UB_UltrabeatKitsGBLogic|18/07/2026, 01:44
update|MAContent10_AssetPack_0314_AppleLoopsHipHop1|18/07/2026, 01:44
update|MAContent10_AssetPack_0315_AppleLoopsElectroHouse1|18/07/2026, 01:44
update|MAContent10_AssetPack_0316_AppleLoopsDubstep1|18/07/2026, 01:44
update|MAContent10_AssetPack_0317_AppleLoopsModernRnB1|18/07/2026, 01:44
update|MAContent10_AssetPack_0320_AppleLoopsChillwave1|18/07/2026, 01:44
update|MAContent10_AssetPack_0321_AppleLoopsIndieDisco|18/07/2026, 01:44
update|MAContent10_AssetPack_0322_AppleLoopsDiscoFunk1|18/07/2026, 01:44
update|MAContent10_AssetPack_0323_AppleLoopsVintageBreaks|18/07/2026, 01:44
… 12 of 50 rows shown
[result_status] UNDECLARED / UNKNOWN

== action=missing
[result_status] UNDECLARED / UNKNOWN

== action=pending_reboot
softwareupdate_restart|false|
reboot_required|false|
[result_status] UNDECLARED / UNKNOWN

== action=patch_connectivity
target|https://swscan.apple.com|dns_ok|true|dns_ms|12|ip|2.16.176.247
target|https://swscan.apple.com|tcp_ok|true|tcp_ms|22
target|https://swdist.apple.com|dns_ok|true|dns_ms|2|ip|17.253.29.150
target|https://swdist.apple.com|tcp_ok|true|tcp_ms|23
summary|targets_tested|2|targets_reachable|2|targets_failed|0
[result_status] UNDECLARED / UNKNOWN

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-06 · euid 0 · leg-hash 007b2e86015f

== action=installed
package|apt|3.0.3
package|autoconf|2.72-3.1
package|automake|1:1.17-4
package|autotools-dev|20240727.1
package|base-files|13.8+deb13u6
package|base-passwd|3.6.7
package|bash|5.2.37-2+b9
package|binutils-aarch64-linux-gnu|2.44-3
package|binutils-common|2.44-3
package|binutils|2.44-3
package|bison|2:3.8.2+dfsg-1+b2
package|bsdutils|1:2.41.5-0+deb13u1
… 12 of 49 rows shown
[result_status] OK / PARTIAL / subprocess_runner:line_limit

== action=missing
available|none|System is up to date
[result_status] UNDECLARED / UNKNOWN

== action=pending_reboot
reboot_required_file|false|
needs_restarting|false|
reboot_required|false|
[result_status] UNDECLARED / UNKNOWN

== action=patch_connectivity
target|https://archive.ubuntu.com|dns_ok|true|dns_ms|37|ip|185.125.190.83
target|https://archive.ubuntu.com|tcp_ok|true|tcp_ms|14
target|https://security.ubuntu.com|dns_ok|true|dns_ms|12|ip|185.125.190.82
target|https://security.ubuntu.com|tcp_ok|true|tcp_ms|19
summary|targets_tested|2|targets_reachable|2|targets_failed|0
[result_status] UNDECLARED / UNKNOWN

Caveats and known gaps

1. macOS missing can return zero rows with no placeholder. do_missing’s macOS branch only writes an available|none|... placeholder when softwareupdate -l’s raw output is empty (windows_updates_plugin.cpp:569-575); when the raw output is non-empty but entirely banner/status text, parse_softwareupdate_list filters every line out (windows_updates_parsers.hpp:228-243, drops "Software Update"/"Finding"/"No new" lines) and nothing is written at all — exactly what the macOS sample above shows for missing. A consumer cannot distinguish “no updates” from “the tool produced nothing recognisable” for this action on macOS.
2. installed/missing have no single field schema. The identifier|description|install_date and title|severity shapes declared in the definition YAML fit the Windows leg; on Linux and macOS both actions emit two data fields, not three (installed) or the raw tool line (missing/yum and macOS), and on Linux installed’s third field is a package version, not a date, whenever the apt fallback ran instead of rpm (windows_updates_plugin.cpp:252-272).
3. installed’s row order and cap changed with the WMI migration. The retired PowerShell path returned the 50 most-recently-installed hotfixes, newest first; the WMI-sourced path returns up to 512 rows in whatever order the provider yields (WQL has no ORDER BY for a data-class query) — disclosed in windows_updates_plugin.cpp:200-207 and the wave3-pr33d changelog entry, not a defect.
4. The raw_sockets mechanism name is ordinary TCP, not SOCK_RAW. test_dns/test_tcp (windows_updates_plugin.cpp:788-881) use getaddrinfo + a plain SOCK_STREAM connect(); the descriptor’s mechanism string is a convention shared across plugins for “direct BSD/Winsock sockets”, not a literal raw-socket claim.
5. missing’s Windows leg is unverified on real Windows. The header comment above do_missing’s WUA branch (windows_updates_plugin.cpp:309-320) states it “could not be verified on this (non-Windows) host” and was written from the documented COM API surface; test_windows_updates_win_actions.cpp deliberately exercises only installed, not missing, to avoid a network-dependent unit test.

Source and tests

• Plugin: agents/plugins/windows_updates/src/windows_updates_parsers.hpp · agents/plugins/windows_updates/src/windows_updates_plugin.cpp
• Definitions: content/definitions/t2_capabilities.yaml · content/definitions/t2_chaining_examples.yaml · content/definitions/windows_updates.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_d.hpp
• Tests: tests/unit/test_windows_updates_parsers.cpp · tests/unit/test_windows_updates_posix_actions.cpp · tests/unit/test_windows_updates_win_actions.cpp
• Privilege row: docs/agent-privilege-model.md (no row yet)