firmware_posture

How it works

firmware reports what the host’s own firmware says about itself and changes nothing: the vendor, version and release date of the BIOS or system firmware and, on Linux only, whether the fwupd service knows of a firmware update waiting for a device. The action takes no parameters and returns rows of the form firmware|<field>|<value>|<source>. Every leg is an in-process read (no helper program is started); no wmic, dmidecode, fwupdmgr or ioreg is ever run.

flowchart LR
  OP["Operator or workflow"] --> SRV["Server, authz Security Read"]
  SRV -->|"gRPC over mTLS"| EX["firmware_posture execute: firmware"]
  EX --> WIN["Windows leg: bounded Win32_BIOS WMI query plus GetSystemFirmwareTable RSMB"]
  EX --> LIN["Linux leg: sysfs DMI bios files, then fwupd over sd-bus: GetDevices, GetUpgrades per updatable device"]
  EX --> MAC["macOS leg: IORegistryEntryFromPath on IODeviceTree rom, chosen and root, sysctlbyname hw.model and hw.optional.arm64"]
  WIN & LIN & MAC --> ROWS["firmware rows: value, absent, unavailable or unreadable, status OK, CONSTRAINED or PERMISSION_DENIED"]
  ROWS --> RS[("ResponseStore")] --> API["REST /api/responses"]

• Windows asks two sources and reports both, so a disagreement between them is visible. wmi is a bounded Win32_BIOS query for exactly Manufacturer, SMBIOSBIOSVersion and ReleaseDate. smbios reads the raw SMBIOS table with GetSystemFirmwareTable('RSMB') and hands the bytes to the shared bounds-checked SMBIOS walker (agents/shared/smbios_parsers.hpp), which decodes the type-0 record: vendor, version, release date, ROM size, and the BIOS and embedded-controller release numbers. The WMI array column BIOSVersion is not read, so no bios_version_list row exists.
• Linux reads the four /sys/class/dmi/id/bios_* files (vendor, version, date, release), each once with a 4 KiB bound, then asks fwupd on the system D-Bus. It calls GetDevices, then GetUpgrades for each device flagged updatable, inside one 5 second budget for the whole fwupd read, and reports one fwupd_device row per device (at most 256) plus one aggregate update_pending row. sd-bus comes from the system package libsystemd, never from vcpkg.json; a build without it reports update_pending as unreadable with fwupd:not_built.
• macOS reads the IODeviceTree plane through IOKit. An Intel Mac has /rom (version, release date, vendor). An Apple Silicon Mac has no /rom, so the version is /chosen system-firmware-version (else firmware-version) and the vendor is the tree root manufacturer. The plugin also reads hw.model, and uses hw.optional.arm64 to decide whether a missing /rom is expected. No update_pending row is produced, and Apple Silicon has no release date.

Every fact reads as exactly one of four things: a value; absent (the OS definitively reports nothing, such as no DMI in a container or a missing property); unavailable (update_pending only: the system bus answered and fwupd is not on it); or unreadable (the read failed). absent and unavailable are states, not failures: they add no reason token and the result stays OK. A failed read is never shown as absent; it is an unreadable row with a <source>:<cause> reason and a non-OK status. A non-OK status also makes the action return 1, which the agent core records as a command failure although the rows and the typed status still reach the server.

What you can decide with it

update_pending is an aggregate over the devices fwupd flags as updatable, so read it with this table:

A device that is not updatable shows update_pending=unknown on its own fwupd_device row because it is never asked, and that does not change the aggregate. The verdict reflects whatever update metadata the fwupd daemon already holds; the plugin never asks fwupd to refresh it.

A clean result (OK with values) proves that the OS reported those strings. It does not prove the firmware is current, genuine or unmodified, and it says nothing about Secure Boot or the TPM (see platform_security). absent in a container or VM means the guest sees no DMI, not that the host has no firmware, so treat absent and unreadable as “unknown” when comparing against a baseline, never as “fine”. On the shipped container agent image every run is recorded as a failure (see caveat 2), so target native agents for firmware questions.

Diagrams

The Linux leg is the only multi-step one: a sysfs read, then a bounded exchange with fwupd.

sequenceDiagram
  participant A as Agent leg
  participant S as sysfs DMI files
  participant B as System D-Bus
  participant F as fwupd daemon
  A->>S: read bios_vendor, bios_version, bios_date, bios_release
  S-->>A: text, ENOENT is absent, any other error is unreadable
  A->>B: open the system bus
  alt bus cannot be opened
    B-->>A: error, so update_pending is unreadable with a bus_open token
  else bus opens
    A->>F: GetDevices
    F-->>A: devices with flags, or ServiceUnknown
    Note over A,F: ServiceUnknown means update_pending is unavailable
    loop each updatable device, inside one 5 second budget
      A->>F: GetUpgrades for that device id
      F-->>A: releases, or NothingToDo
    end
    A->>A: aggregate to yes, no or unknown
  end

The DMI files are read first and independently of fwupd, so a host with DMI but no usable D-Bus still reports its firmware version alongside an unreadable update_pending. The bus is opened once, devices are listed once, and GetUpgrades is asked only for devices flagged updatable; a refusal or an unexpected D-Bus error is recorded as a token rather than treated as “no update”.

The macOS leg decides, from one architecture signal, whether a missing /rom is normal.

flowchart TD
  A["Look up the rom, chosen and root nodes, then hw.model and hw.optional.arm64"] --> B{"hw.optional.arm64 is 1?"}
  B -- "yes, Apple Silicon" --> C["A missing rom node is expected, so release_date reads absent"]
  B -- "no, or the key cannot be read" --> D["Treated as Intel, so a missing rom node is a failed lookup and release_date reads unreadable"]
  C --> E["Version from chosen system-firmware-version, else firmware-version. Vendor from root manufacturer"]
  D --> E
  E --> F["Rows: vendor, version, release_date, version_source, model"]

A missing /chosen or root node is never expected on any Mac, so it always adds an iokit:<path>:lookup_failed token and the status is CONSTRAINED. A field row reads unreadable only when it had no other source: on an Intel Mac the version and vendor can still come from /rom, while the Apple Silicon version (from /chosen) and vendor (from the root node) cannot. version_source names the node and key that carried the version, so a consumer can tell an Intel /rom version from an Apple Silicon iBoot tag.

OS capability

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

• firmware / macOS — verified on Apple Silicon only (Mac16,10, macOS 26.6.2): there IODeviceTree:/rom does not exist and the version is IODeviceTree:/chosen system-firmware-version (an iBoot tag such as mBoot-18000.161.10, not a BIOS date); the Intel /rom version/release-date/vendor keys are UNVERIFIED on hardware. release_date reads absent on Apple Silicon and update_pending is not reported
• firmware / Linux — the fwupd leg needs libsystemd at build time (a system dependency, never vcpkg); without it update_pending reads unreadable with the fwupd:not_built token and the sysfs rows remain. Hosts without DMI (containers, some VMs) report the DMI fields absent and a reachable system bus with no fwupd daemon reports update_pending unavailable: neither is a failure. A system bus that cannot be opened (a container without the bus socket) reads update_pending unreadable with fwupd:bus_open: and the action CONSTRAINED (or PERMISSION_DENIED when the connect is refused). The populated-DMI shape is not captured from a physical Linux host

Privileges and prerequisites

Binaries and subprocesses: none. Every leg is an in-process read (WMI and the firmware table API, sysfs and sd-bus, IOKit and sysctlbyname). Network: none; the fwupd call is a local D-Bus method call, and the daemon may itself reach a remote metadata service, which this plugin does not request (it only calls GetDevices and GetUpgrades) and does not observe.

Data contract

Inputs

The action takes no parameters.

Outputs

Pipe-delimited rows written via write_output(). The first field is the fixed tag firmware (or constrained for the single catch-all row constrained|internal_error, which has only a reason after the tag). Then <field>, <value> and <source>. Every field goes through the shared untrusted-output escaper. vendor, version and release_date are emitted on every source that ran AND read cleanly, as data or absent. A Windows source whose read itself failed (not merely absent) reports every field it can emit unreadable (one row per field, like Linux): vendor, version and release_date for wmi; those plus rom_size_bytes, bios_release and ec_release for smbios, one <source>:<cause> reason and a non-OK typed status. Linux dmi reads each of vendor, version and release_date from its own sysfs file, so a single file’s failure marks only that field unreadable; the other two still report their own value or absent. release_date is normalised to YYYY-MM-DD when the source used a recognised date shape and otherwise passes through unchanged. Windows adds rom_size_bytes, bios_release and ec_release from SMBIOS when the table specifies them; a release pair with only one of its major/minor bytes specified reads unreadable with an smbios:<field>:partial token. Linux adds bios_release from DMI when well formed (a malformed one reads unreadable with dmi:bios_release), one fwupd_device row per fwupd device (id=..;name=..;version=..;updatable=..;needs_reboot=..;update_pending=..;unmodelled=.., where unmodelled=yes means a device flag bit the plugin does not name) and one update_pending row (yes, no, unknown, unavailable or unreadable). macOS adds version_source (the node and key that carried the version) and model. On Windows both wmi and smbios rows can appear for the same field. A host with several fwupd devices past the 256-device cap reports fwupd:row_cap.

crossplatform.firmware_posture.firmware — row_kind|field|value|source

Result status

Any status other than OK makes the action return 1, which the agent core reports as a command FAILURE; the typed status still reaches the server with the rows. The per-failure reason tokens below are written to the agent log (provenance=), not sent on the wire. In a fwupd token, <call> is bus_open, get_devices or get_upgrades, <errno> is a lowercase errno name (enoent, enotdir, eio, …) or errno_<n>, and a failed call that carried a D-Bus error name ends dbus_<name> instead (the last dot-segment of the name, lowercased, non-alphanumerics as _, at most 32 bytes, for example fwupd:get_devices:dbus_noreply).

Where the data goes

• Instruction result. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore, queryable at /api/responses/{id}. firmware is also a gathered definition (crossplatform.firmware_posture.firmware, 300s TTL).
• Not consumed by daily-sync, Echo, DEX, or metrics.
• Sensitivity. Rows carry firmware vendor, version, release date, ROM size and, on Linux, fwupd device names and versions (for example a laptop’s embedded controller or an NVMe drive firmware). No username, path or process name. Firmware versions identify a specific hardware model and revision, and an out-of-date one tells an attacker which known firmware flaw applies, so treat the rows like other Security posture data.
• Siblings: hardware (its bios action reads the same DMI and WMI fields as an inventory fact without the update-pending verdict) and bitlocker (disk encryption posture).

Sample output

Windows — captured: windows Windows 10.0.26200 x86_64 · bare-metal · 2026-09-21 · LocalSystem (elevated) · leg-hash 35cf8bb6e007

== action=firmware
firmware|vendor|American Megatrends Inc.|wmi
firmware|version|3801|wmi
firmware|release_date|2021-07-30|wmi
firmware|vendor|American Megatrends Inc.|smbios
firmware|version|3801|smbios
firmware|release_date|2021-07-30|smbios
firmware|rom_size_bytes|16777216|smbios
firmware|bios_release|5.17|smbios
[result_status] OK / FULL

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-10-03 · euid 501 · leg-hash 35cf8bb6e007

== action=firmware
firmware|vendor|Apple Inc.|iokit
firmware|version|mBoot-18000.161.10|iokit
firmware|release_date|absent|iokit
firmware|version_source|IODeviceTree:/chosen#system-firmware-version|iokit
firmware|model|Mac16,10|sysctl
[result_status] OK / FULL

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-24 · euid 0 · leg-hash 35cf8bb6e007

== action=firmware
firmware|vendor|absent|dmi
firmware|version|absent|dmi
firmware|release_date|absent|dmi
firmware|update_pending|unreadable|fwupd
[result_status] CONSTRAINED / PARTIAL / fwupd:bus_open:enoent
[rc] 1

Caveats and known gaps

1. Only Apple Silicon is verified on macOS. The capture host has no IODeviceTree:/rom, so the Intel version, release-date and vendor keys are unverified on hardware. On Apple Silicon the version is an iBoot tag such as mBoot-18000.161.10, not a BIOS date, release_date reads absent and no update_pending row is reported.
2. Update-pending is Linux-only and needs fwupd. Windows and macOS report no update verdict, and on Linux the verdict covers only devices fwupd knows about and only their updatable ones. A host whose system bus cannot be opened reports update_pending|unreadable with fwupd:bus_open:<errno> (enoent when the socket is missing; a refused connect reads permission_denied and the action PERMISSION_DENIED), which is the normal result on the shipped container agent image because it has libsystemd but no D-Bus, so every run there is recorded as a command failure. To read update state in a container, mount the host’s /run/dbus/system_bus_socket (a security decision that widens the container’s authority) or target firmware at native agents by tag.
3. Some failures cannot be told from an absence. On macOS, IORegistryEntryFromPath and IORegistryEntryCreateCFProperty have no error channel, so a transient failure to look up /rom on Apple Silicon, or to read a property of a node that exists, reads absent (#4897). On Linux a sandbox that hides /sys/class/dmi from a host that has DMI looks the same as a host with none, and on Windows a missing root\CIMV2 namespace or Win32_BIOS class reads absent (as does a damaged WMI repository that presents as one of those two answers, #4900), while any other WMI fault reads unreadable with a wmi:<token> token.
4. The Linux sample shows the degenerate shape. It is a real run in a container with no DMI and no system bus, so every DMI field is absent and update_pending is unreadable with fwupd:bus_open:enoent; no fwupd_device row and no populated-DMI shape has been captured from a physical host. The unavailable and device-row shapes are proven by unit fixtures only, not end to end.
5. Read-only by design, and not boot integrity. The plugin lists devices and upgrades and never installs, verifies or activates firmware, and it does not read Secure Boot state or the TPM. A version string is what the firmware reports about itself, so it is a fleet-comparison fact, not evidence that the firmware is genuine or unmodified.

Source and tests

• Plugin: agents/plugins/firmware_posture/src/firmware_posture_legs.hpp · agents/plugins/firmware_posture/src/firmware_posture_linux.cpp · agents/plugins/firmware_posture/src/firmware_posture_macos.cpp · agents/plugins/firmware_posture/src/firmware_posture_parsers.hpp · agents/plugins/firmware_posture/src/firmware_posture_plugin.cpp · agents/plugins/firmware_posture/src/firmware_posture_win.cpp
• Definitions: content/definitions/firmware_posture.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_firmware_posture.hpp
• Tests: tests/test_firmware_posture_definition.py · tests/unit/test_firmware_posture_local_dispatcher.cpp · tests/unit/test_firmware_posture_parsers.cpp
• Privilege row: docs/agent-privilege-model.md