hardware

How it works

Twelve independent actions, dispatched by action name (hardware_plugin.cpp:963). manufacturer/model/processors/system are single native calls per OS (WMI, sysctlbyname/IOKit, or a /sys//proc file read) with no subprocess. bios and disks need data no native API on macOS exposes, so those two legs shell out through the agent’s bounded subprocess runner (run_bounded_subprocess, fixed deadline, no shell) to system_profiler and parse its output with a pure header-only parser (hardware_macos_bios.hpp, hardware_disks_macos.hpp). memory tries dmidecode on Linux (also via the bounded runner) and falls back to /proc/meminfo’s aggregate total when dmidecode is missing or fails. drivers enumerates Win32_PnPSignedDriver on Windows or reads /proc/modules on Linux; it is not implemented on macOS (no public per-driver/kext enumeration API). The four newest actions (chassis, baseboard, swap, machine_id) read nothing yet: each answers with exactly one status|<action>|unsupported|<os>:planned row from the shared planned-leg reporter (agents/shared/planned_leg.hpp, called from the dispatch in hardware_plugin.cpp), until the per-OS leg PRs land the real reads.

Every action that can find nothing still emits one row carrying the literal unknown in place of an unread value (hardware_plugin.cpp:243, :257, :342-344 and equivalents) — never a silent zero-row output — so a consumer can tell “the probe ran and found nothing” from “this action produced no output for an unrelated reason.” This plugin is deliberately not a live-monitoring feed: every action is a point-in-time read with no polling, no event stream, and (except drivers, whose WMI query can take several seconds) no expectation of taking more than a few milliseconds.

flowchart LR
  OP[Operator / workflow] --> SRV[Server<br/>authz: Inventory.Read]
  SRV -- gRPC mTLS --> HOST[Agent plugin host] --> EX[hardware.execute]
  EX --> WIN[Windows leg<br/>WMI Win32_ComputerSystem/BIOS/Processor/PhysicalMemory/DiskDrive/PnPSignedDriver]
  EX --> MAC[macOS leg<br/>sysctlbyname + IOKit; system_profiler via bounded runner for bios/disks]
  EX --> LIN[Linux leg<br/>/sys/class/dmi, /proc/cpuinfo, /proc/modules; dmidecode via bounded runner for memory]
  WIN & MAC & LIN --> ROWS[pipe rows +<br/>typed result status] --> RS[(ResponseStore)] --> API[REST /api/responses]

OS capability

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

• baseboard / Windows — not read yet: one unsupported status row, windows:planned
• baseboard / macOS — not read yet: one unsupported status row, macos:planned
• baseboard / Linux — not read yet: one unsupported status row, linux:planned
• chassis / Windows — not read yet: one unsupported status row, windows:planned
• chassis / macOS — not read yet: one unsupported status row, macos:planned
• chassis / Linux — not read yet: one unsupported status row, linux:planned
• machine_id / Windows — not read yet: one unsupported status row, windows:planned
• machine_id / macOS — not read yet: one unsupported status row, macos:planned
• machine_id / Linux — not read yet: one unsupported status row, linux:planned
• memory / macOS — aggregate total only, no per-DIMM breakdown (macOS has no public per-DIMM API)
• memory / Linux — falls back to the aggregate MemTotal from /proc/meminfo (no per-DIMM detail) when dmidecode is unavailable or unprivileged
• swap / Windows — not read yet: one unsupported status row, windows:planned
• swap / macOS — not read yet: one unsupported status row, macos:planned
• swap / Linux — not read yet: one unsupported status row, linux:planned

Privileges and prerequisites

The four planned actions (chassis, baseboard, swap, machine_id) read nothing on any OS and need no grant.

Binaries/subprocesses: /usr/sbin/system_profiler (macOS bios, disks, via run_bounded_subprocess) and dmidecode (Linux memory, resolved via probe_tool_path, also via run_bounded_subprocess) — both bounded, no shell. No network access. Windows uses in-process WMI (COM), no child process.

Data contract

Inputs

No action takes parameters.

Outputs

Pipe-delimited rows, one per record via write_output(). Scalar actions (manufacturer, model) emit key|value; the rest emit one or more key|field1|field2|... rows. A field the underlying probe could not read is the literal string unknown rather than an omitted field or an empty row — this applies to every read action’s identity/value fields (manufacturer, model, bios, processors, memory, disks, system); processors rows end in two appended columns (socket_designation, stepping) and memory rows in three (manufacturer, part_number, serial), every one the literal - until a leg reads it (a DIMM serial is personal data, classified with the system serial, and is not read in this release). The four planned actions emit one typed status row (status|<action>|unsupported|<os>:planned) and nothing else. drivers additionally emits __truncated__ in the name field when the Windows WMI row cap (512, agents/shared/wmi_bounded.hpp) is hit (hardware_plugin.cpp:746-753).

device.hardware.baseboard — row_kind|vendor|product|serial|source

device.hardware.bios — bios_vendor|bios_version|bios_date

device.hardware.chassis — row_kind|type|serial|asset_tag|source

device.hardware.disks — index|model|size_gb|media_type|interface

device.hardware.drivers — index|name|version|date|provider|device_class

device.hardware.machine_id — row_kind|hash_hex|algorithm|source

device.hardware.manufacturer — manufacturer

device.hardware.memory — slot|size_mb|type|speed_mhz|manufacturer|part_number|serial

device.hardware.model — model

device.hardware.processors — index|model|cores|threads|clock_mhz|socket_designation|stepping

device.hardware.swap — row_kind|device|total_mb|used_mb|source

device.hardware.system — serial|system_uuid

Result status

Only the four planned actions set a typed result status: UNAVAILABLE / UNKNOWN, provenance <os>:planned (windows:planned, linux:planned or macos:planned), one unsupported status row. Every other action leaves the status undeclared; the agent records UNDECLARED and the sample shows UNDECLARED / UNKNOWN / for them on every OS.

Where the data goes

• Instruction result, plus a daily-sync consumer for seven of the twelve actions. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore, queryable at /api/responses/{id}. The device_ci daily-sync source (ADR-0016) additionally invokes manufacturer, model, system, bios, processors, memory, and disks in-process via LocalDispatcher and folds their output into its canonical CI record (agents/core/src/sync_source_device_ci.hpp:62-68), which the server reconstructs field-for-field (server/core/src/device_ci_ingestion.cpp:94-115). drivers and the four planned actions (chassis, baseboard, swap, machine_id; on-demand only, no gather block) are not part of that record. content/definitions/hardware.yaml:517-518 documents this for the system action specifically.
• Not consumed by Echo, DEX, or metrics. manufacturer/model/bios/processors/memory/disks gather on a 3600s TTL; drivers and system on an 86400s TTL (content/definitions/hardware.yaml); nothing polls continuously.
• Sensitivity. system rows carry the hardware serial number and SMBIOS/firmware UUID — direct, stable device identifiers; manufacturer/model/bios/disks name the specific hardware but not a person; drivers rows name installed driver software (name/provider) — a software inventory by another route. No row carries a username or account name.
• Siblings: device_identity (domain/OU join state, same Wave 3 native-acquisition migration), disk_actions (SMART health and volume-to-drive mapping — hardware.disks reports the drive inventory, disk_actions reports its health and logical mounts).
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("device.hardware.system"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}.

Sample output

Windows — captured: windows Windows 10.0.26200 x86_64 · bare-metal · 2026-10-27 · LocalSystem (elevated) · leg-hash c78d09361368

== action=manufacturer
manufacturer|Micro Computer (HK) Tech Limited
[result_status] UNDECLARED / UNKNOWN

== action=model
model|EliteMini Series
[result_status] UNDECLARED / UNKNOWN

== action=bios
bios_vendor|American Megatrends International, LLC.
bios_version|1.06
bios_date|2025-11-10
[result_status] UNDECLARED / UNKNOWN

== action=processors
cpu|0|AMD Ryzen 9 PRO 8945HS w/ Radeon 780M Graphics|8|16|4001|-|-
[result_status] UNDECLARED / UNKNOWN

== action=memory
dimm|DIMM 0|32768|DDR5|5600|-|-|-
[result_status] UNDECLARED / UNKNOWN

== action=disks
disk|0|YMTC PC41Q-1TB-B|953|HDD|SCSI
[result_status] UNDECLARED / UNKNOWN

== action=drivers
driver|0|Microsoft iSCSI Initiator|10.0.26100.9711|2006-06-21|Microsoft|SCSIADAPTER
driver|1|Tailscale Tunnel|0.14.0.0|2021-10-13|WireGuard LLC|NET
driver|2|WAN Miniport (Network Monitor)|10.0.26100.1|2006-06-21|Microsoft|NET
driver|3|WAN Miniport (IPv6)|10.0.26100.1|2006-06-21|Microsoft|NET
driver|4|WAN Miniport (IP)|10.0.26100.1|2006-06-21|Microsoft|NET
driver|5|WAN Miniport (PPPOE)|10.0.26100.1|2006-06-21|Microsoft|NET
driver|6|WAN Miniport (PPTP)|10.0.26100.1|2006-06-21|Microsoft|NET
driver|7|WAN Miniport (L2TP)|10.0.26100.1|2006-06-21|Microsoft|NET
driver|8|WAN Miniport (IKEv2)|10.0.26100.1|2006-06-21|Microsoft|NET
driver|9|WAN Miniport (SSTP)|10.0.26100.1|2006-06-21|Microsoft|NET
driver|10|Generic software device|10.0.26100.1|2006-06-21|Microsoft|SOFTWAREDEVICE
driver|11|Hyper-V Virtual Switch Extension Adapter|10.0.26100.1|2006-06-21|Microsoft|NET
… 12 of 178 rows shown
[result_status] UNDECLARED / UNKNOWN

== action=system
serial|1234567890
system_uuid|00000000-0000-0000-0000-000000000002
[result_status] UNDECLARED / UNKNOWN

== action=chassis
status|chassis|unsupported|windows:planned
[result_status] UNAVAILABLE / UNKNOWN / windows:planned

== action=baseboard
status|baseboard|unsupported|windows:planned
[result_status] UNAVAILABLE / UNKNOWN / windows:planned

== action=swap
status|swap|unsupported|windows:planned
[result_status] UNAVAILABLE / UNKNOWN / windows:planned

== action=machine_id
status|machine_id|unsupported|windows:planned
[result_status] UNAVAILABLE / UNKNOWN / windows:planned

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-10-27 · euid 501 · leg-hash c78d09361368

== action=manufacturer
manufacturer|Apple Inc.
[result_status] UNDECLARED / UNKNOWN

== action=model
model|Mac16,10
[result_status] UNDECLARED / UNKNOWN

== action=bios
bios_vendor|Apple
bios_version|18000.161.10
bios_date|N/A
[result_status] UNDECLARED / UNKNOWN

== action=processors
cpu|0|Apple M4|10|10|0|-|-
[result_status] UNDECLARED / UNKNOWN

== action=memory
dimm|total|32768|unknown|0|-|-|-
[result_status] UNDECLARED / UNKNOWN

== action=disks
disk|0|APPLE SSD AP0512Z|465|SSD|NVMe
[result_status] UNDECLARED / UNKNOWN

== action=drivers
driver|0|unknown||||
[result_status] UNDECLARED / UNKNOWN

== action=system
serial|EXAMPLE0001
system_uuid|00000000-0000-0000-0000-000000000001
[result_status] UNDECLARED / UNKNOWN

== action=chassis
status|chassis|unsupported|macos:planned
[result_status] UNAVAILABLE / UNKNOWN / macos:planned

== action=baseboard
status|baseboard|unsupported|macos:planned
[result_status] UNAVAILABLE / UNKNOWN / macos:planned

== action=swap
status|swap|unsupported|macos:planned
[result_status] UNAVAILABLE / UNKNOWN / macos:planned

== action=machine_id
status|machine_id|unsupported|macos:planned
[result_status] UNAVAILABLE / UNKNOWN / macos:planned

Linux — captured: linux Ubuntu 26.04.1 LTS x86_64 · vm · 2026-10-27 · euid 0 · leg-hash c78d09361368

== action=manufacturer
manufacturer|unknown
[result_status] UNDECLARED / UNKNOWN

== action=model
model|unknown
[result_status] UNDECLARED / UNKNOWN

== action=bios
bios_vendor|unknown
bios_version|unknown
bios_date|unknown
[result_status] UNDECLARED / UNKNOWN

== action=processors
cpu|0|AMD Ryzen 9 PRO 8945HS w/ Radeon 780M Graphics|8|16|3993|-|-
[result_status] UNDECLARED / UNKNOWN

== action=memory
dimm|total|15993|unknown|0|-|-|-
[result_status] UNDECLARED / UNKNOWN

== action=disks
disk|0|Virtual Disk|1024|HDD|unknown
disk|1|Virtual Disk|0|HDD|unknown
disk|2|Virtual Disk|8|HDD|unknown
disk|3|Virtual Disk|0|HDD|unknown
[result_status] UNDECLARED / UNKNOWN

== action=drivers
driver|0|xt_nat|||kernel|module
driver|1|nf_conntrack_netlink|||kernel|module
driver|2|xt_conntrack|||kernel|module
driver|3|xt_MASQUERADE|||kernel|module
driver|4|xfrm_user|||kernel|module
driver|5|xfrm_algo|||kernel|module
driver|6|xt_set|||kernel|module
driver|7|ip_set|||kernel|module
driver|8|xt_addrtype|||kernel|module
driver|9|nft_compat|||kernel|module
driver|10|sch_fq_codel|||kernel|module
driver|11|autofs4|||kernel|module
… 12 of 18 rows shown
[result_status] UNDECLARED / UNKNOWN

== action=system
serial|unknown
system_uuid|unknown
[result_status] UNDECLARED / UNKNOWN

== action=chassis
status|chassis|unsupported|linux:planned
[result_status] UNAVAILABLE / UNKNOWN / linux:planned

== action=baseboard
status|baseboard|unsupported|linux:planned
[result_status] UNAVAILABLE / UNKNOWN / linux:planned

== action=swap
status|swap|unsupported|linux:planned
[result_status] UNAVAILABLE / UNKNOWN / linux:planned

== action=machine_id
status|machine_id|unsupported|linux:planned
[result_status] UNAVAILABLE / UNKNOWN / linux:planned

Caveats and known gaps

1. The eight read actions never set a typed result status. Every such sample line reads UNDECLARED / UNKNOWN / regardless of whether the underlying probe succeeded, partially failed, or hit an unsupported leg (e.g. Linux manufacturer/model/bios/system all read unknown in the sample, and get the same UNDECLARED status as a clean Windows read). A consumer must inspect the row content (unknown fields, the drivers action’s __truncated__ marker), not the status, to tell success from degradation.
2. Two legs are partial: drivers on macOS, memory on Linux and macOS. drivers is not implemented on macOS. No public per-driver/kext enumeration API exists; the descriptor declares it YUZU_SUPPORT_UNSUPPORTED (hardware_plugin.cpp:858) and the macOS sample shows the house unknown row rather than a capture. memory is aggregate-only on Linux and macOS. Linux needs dmidecode (typically root) for per-DIMM detail and falls back to /proc/meminfo’s total when unavailable or unprivileged; the Linux sample (captured as root/euid 0 in a container) still shows the aggregate total row, meaning dmidecode itself found nothing usable in that environment even with root. macOS has no public per-DIMM API at all and always reports the aggregate.
3. A connected-but-empty WMI query now emits an explicit unknown row instead of silently emitting nothing — a deliberate divergence from the plugin’s pre-#3404 behavior, made so a consumer can distinguish “the probe ran and found nothing” from an unrelated dispatch failure (hardware_plugin.cpp:190-205). Do not revert this to match the old silent-gap behavior.
4. Windows disks.interface reports the WMI-layer bus (SCSI), not the physical bus — both drives in the Windows sample are NVMe/SATA but report SCSI, because Win32_DiskDrive.InterfaceType reports the storage stack layer WMI actually asks, not the physical connector. disk_actions.smart decodes the true bus (nvme/sata/usb) via a lower-level IOCTL and is the more accurate source when that distinction matters.
5. Some planned actions can never have a source. On macOS there is no public source for chassis, baseboard or machine_id (the hardware UUID from system already identifies the machine), yet all four new actions are advertised planned on every OS. The per-OS leg PRs move such legs to a typed unsupported with a reason; until then a consumer must read <os>:planned as “not read”, never as “this host has no value”. The appended cpu/dimm columns are likewise always -: socket_designation, stepping, manufacturer, part_number and serial ride on every cpu/dimm row so downstream schemas are final, but no leg fills them yet.

Source and tests

• Plugin: agents/plugins/hardware/src/hardware_disks_macos.hpp · agents/plugins/hardware/src/hardware_estate_legs.hpp · agents/plugins/hardware/src/hardware_linux_parsers.hpp · agents/plugins/hardware/src/hardware_macos_bios.hpp · agents/plugins/hardware/src/hardware_plugin.cpp
• Definitions: content/definitions/hardware.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_b.hpp
• Tests: tests/test_hardware_definition.py · tests/unit/server/test_hardware_list_model.cpp · tests/unit/server/test_hardware_routes.cpp · tests/unit/server/test_hardware_sync_routes.cpp · tests/unit/server/test_hardware_ui.cpp · tests/unit/test_hardware_device_identity_posix_actions.cpp · tests/unit/test_hardware_disks_macos.cpp · tests/unit/test_hardware_linux_parsers.cpp · tests/unit/test_hardware_local_dispatcher.cpp · tests/unit/test_hardware_macos_bios.cpp
• Privilege row: docs/agent-privilege-model.md