From 9ecc6823c85834398c83a449f22bbbdc0e90861e Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Fri, 13 Nov 2026 23:00:23 +0100 Subject: [PATCH 1/2] feat(system-identity): read the system firmware with the identity get_system_identity() also reads bios_vendor, bios_version and bios_date from /sys/class/dmi/id, in the same round trip as the SMBIOS identity. The date is given as ISO 8601; anything that is no MM/DD/YYYY reads as empty. Only the vendors' text defaults are placeholders for the firmware: a version of "1" is a version, unlike a serial of one repeated character. Output of the three identity fields alone still parses, with the firmware empty. NetOrk/netork#2518 --- CHANGELOG.md | 6 +++ README.md | 3 ++ napalm_device_types/models.py | 5 +- napalm_device_types/system_identity.py | 64 +++++++++++++++++----- tests/test_system_identity.py | 75 ++++++++++++++++++++++++-- 5 files changed, 135 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a30fb2..4ba3128 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,12 @@ recorded here; their history is the git log. ## [Unreleased] ### Added +- `get_system_identity()` also reads the host's system firmware (BIOS or UEFI) from the + same SMBIOS tables in the same round trip: `bios_vendor`, `bios_version` and + `bios_date` (ISO 8601, from sysfs's `MM/DD/YYYY`; anything else reads as empty). Only + the vendors' text defaults (`To be filled by O.E.M.`, `Default string`) are + placeholders there -- a version of `1` is a version. Output of the three identity + fields alone still parses, with the firmware empty (NetOrk/netork#2518). - `ConfigRevisionsMixin`: a device's own configuration history (NetOrk/netork#2511). `get_config_revisions()` (newest first, the first in place now, as `ConfigRevisionDict`: id, UTC time, description, user, size) and diff --git a/README.md b/README.md index f8fc9b9..99c3aab 100644 --- a/README.md +++ b/README.md @@ -286,6 +286,9 @@ O.E.M.`, `Default string`, all-zero or the common `03000200-…-000700080009` UU empty: matching on them would join unrelated machines. `is_placeholder_identity` is the same filter for a BMC driver's side. `product_uuid` and `product_serial` are root's, so a driver supplies `_run_system_identity_command(command, privileged=)`. +The same round trip reads the host's system firmware (BIOS or UEFI): `bios_vendor`, +`bios_version` and `bios_date` (`YYYY-MM-DD`, from sysfs's `MM/DD/YYYY`). Only the vendors' +text defaults read as empty there; a short version such as `1` is a version. `OpenSshServerMixin` (`harden_ssh_server`, `get_ssh_server_algorithms`) takes algorithms out of what an OpenSSH server offers -- the ones ssh-audit flags. It reads the lists sshd diff --git a/napalm_device_types/models.py b/napalm_device_types/models.py index 94f9b30..3185226 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -1443,7 +1443,7 @@ class ManagementProtocolsDict(TypedDict): class SystemIdentityDict(TypedDict): - """A host's SMBIOS identity, what ties it to its BMC. + """A host's SMBIOS identity, what ties it to its BMC, and its system firmware. See :mod:`napalm_device_types.system_identity`. @@ -1452,3 +1452,6 @@ class SystemIdentityDict(TypedDict): system_uuid: str # lowercase product_serial: str board_serial: str + bios_vendor: str # the system firmware (BIOS or UEFI): its vendor, + bios_version: str # its version, + bios_date: str # its release date, YYYY-MM-DD diff --git a/napalm_device_types/system_identity.py b/napalm_device_types/system_identity.py index 6549d3b..325a551 100644 --- a/napalm_device_types/system_identity.py +++ b/napalm_device_types/system_identity.py @@ -1,6 +1,7 @@ -"""The SMBIOS identity of a host: system UUID, product serial, board serial. +"""The SMBIOS identity of a host: system UUID, product serial, board serial -- and +its system firmware (BIOS or UEFI): vendor, version, release date. -What ties a server to its BMC. The BMC reports the server's serial number and +The identity is what ties a server to its BMC. The BMC reports the server's serial number and system UUID; the host reads the same values from its firmware tables. Both sides read them the same way on every Linux host, so the command, its parse and the placeholder filter live here once, and a driver only carries the command across. @@ -13,11 +14,17 @@ Matching on those would join unrelated machines, so they read as empty. **Root.** ``product_uuid`` and ``product_serial`` are readable by root only; without it they come back empty, which is "not known", not a mismatch. + +**The firmware** comes from the same tables in the same round trip, so a driver that +reads the identity reads it too. It is a fact about the host, not part of its identity: +its placeholders are the vendors' text defaults, never a short value (a version of +``1`` is a version), and sysfs's ``MM/DD/YYYY`` release date is given as ISO 8601. """ from __future__ import annotations import re +from datetime import date from typing import TYPE_CHECKING from napalm_device_types.models import SystemIdentityDict @@ -27,13 +34,21 @@ _BEGIN = "IDBEGIN" _END = "IDEND" _DMI = "/sys/class/dmi/id" -#: Reads the three files in one round trip, framed so a banner or prompt around the -#: output cannot shift a field. -SYSTEM_IDENTITY_COMMAND = ( - f"printf '{_BEGIN}\\n%s\\n%s\\n%s\\n{_END}\\n' " - f'"$(cat {_DMI}/product_uuid 2>/dev/null)" ' - f'"$(cat {_DMI}/product_serial 2>/dev/null)" ' - f'"$(cat {_DMI}/board_serial 2>/dev/null)"' +#: The files read, in the order the output carries them. +_FILES = ( + "product_uuid", + "product_serial", + "board_serial", + "bios_vendor", + "bios_version", + "bios_date", +) + +#: Reads the files in one round trip, framed so a banner or prompt around the output +#: cannot shift a field. +_FIELDS = "%s\\n" * len(_FILES) +SYSTEM_IDENTITY_COMMAND = f"printf '{_BEGIN}\\n{_FIELDS}{_END}\\n' " + " ".join( + f'"$(cat {_DMI}/{name} 2>/dev/null)"' for name in _FILES ) #: Lowercased defaults board vendors leave in place. @@ -80,6 +95,22 @@ def _clean(value: str) -> str: return "" if is_placeholder_identity(value) else value +def _clean_text(value: str) -> str: + """A firmware text, empty for a vendor's text default; a short value stays.""" + value = value.strip() + return "" if value.lower() in _PLACEHOLDERS else value + + +def _iso_date(value: str) -> str: + """sysfs's ``MM/DD/YYYY`` as ``YYYY-MM-DD``; anything else is no date.""" + month, _, rest = value.strip().partition("/") + day, _, year = rest.partition("/") + try: + return date(int(year), int(month), int(day)).isoformat() + except ValueError: + return "" + + def parse_system_identity(output: str) -> SystemIdentityDict: """The identity from :data:`SYSTEM_IDENTITY_COMMAND`'s output, placeholders empty. @@ -91,12 +122,16 @@ def parse_system_identity(output: str) -> SystemIdentityDict: end = lines.index(_END, start) except ValueError: raise ValueError("system identity: no intact IDBEGIN/IDEND frame") from None - fields = (lines[start:end] + ["", "", ""])[:3] - uuid, product_serial, board_serial = (_clean(f) for f in fields) + fields = (lines[start:end] + [""] * len(_FILES))[: len(_FILES)] + uuid, product_serial, board_serial = (_clean(f) for f in fields[:3]) + bios_vendor, bios_version, bios_date = fields[3:] return { "system_uuid": uuid.lower(), "product_serial": product_serial, "board_serial": board_serial, + "bios_vendor": _clean_text(bios_vendor), + "bios_version": _clean_text(bios_version), + "bios_date": _iso_date(bios_date), } @@ -119,12 +154,15 @@ class SystemIdentityMixin: def get_system_identity(self) -> SystemIdentityDict: """ - Returns the host's SMBIOS identity, each value empty when unknown or a vendor - placeholder: + Returns the host's SMBIOS identity and system firmware, each value empty when + unknown or a vendor placeholder: * system_uuid (str) - lowercase * product_serial (str) * board_serial (str) + * bios_vendor (str) - the system firmware's vendor + * bios_version (str) + * bios_date (str) - its release date, ``YYYY-MM-DD`` :raises ValueError: if the output carried no intact reading. """ diff --git a/tests/test_system_identity.py b/tests/test_system_identity.py index c874b00..40365ca 100644 --- a/tests/test_system_identity.py +++ b/tests/test_system_identity.py @@ -14,8 +14,19 @@ from napalm_device_types import ( UUID = "31303043-534D-C40C-7A72-6F1300000000" -def _out(uuid: str, product_serial: str, board_serial: str) -> str: - return f"IDBEGIN\n{uuid}\n{product_serial}\n{board_serial}\nIDEND\n" +def _out( + uuid: str, + product_serial: str, + board_serial: str, + bios: tuple[str, str, str] = ("", "", ""), +) -> str: + vendor, version, date = bios + return ( + f"IDBEGIN\n{uuid}\n{product_serial}\n{board_serial}\n{vendor}\n{version}\n{date}\nIDEND\n" + ) + + +_NO_FIRMWARE = {"bios_vendor": "", "bios_version": "", "bios_date": ""} # ── parsing ─────────────────────────────────────────────────────────────────── @@ -26,6 +37,7 @@ def test_reads_uuid_and_both_serials(): "system_uuid": "31303043-534d-c40c-7a72-6f1300000000", "product_serial": "S123", "board_serial": "ZM155S026022", + **_NO_FIRMWARE, } @@ -81,9 +93,57 @@ def test_unreadable_files_read_as_empty(): "system_uuid": "", "product_serial": "", "board_serial": "BS1", + **_NO_FIRMWARE, } +# ── the system firmware ─────────────────────────────────────────────────────── + + +def test_reads_the_system_firmware(): + # pve-dual, a Supermicro X10DRL-i + out = _out(UUID, "", "ZM155S026022", ("American Megatrends Inc.", "3.4", "11/22/2021")) + identity = parse_system_identity(out) + assert identity["bios_vendor"] == "American Megatrends Inc." + assert identity["bios_version"] == "3.4" + assert identity["bios_date"] == "2021-11-22" + + +def test_a_virtual_machines_firmware_is_read_like_any_other(): + out = _out(UUID, "", "", ("EDK II", "4.2023.08-4", "02/15/2024")) + assert parse_system_identity(out)["bios_version"] == "4.2023.08-4" + + +@pytest.mark.parametrize("version", ["1", "0", "1.0", "A"]) +def test_a_short_firmware_version_is_no_placeholder(version): + # Serials of one repeated character are placeholders, versions are not. + out = _out(UUID, "", "", ("Vendor", version, "")) + assert parse_system_identity(out)["bios_version"] == version + + +@pytest.mark.parametrize("value", ["", "To be filled by O.E.M.", "Default string", "Not Specified"]) +def test_a_placeholder_firmware_version_reads_as_empty(value): + out = _out(UUID, "", "", (value, value, "")) + identity = parse_system_identity(out) + assert identity["bios_vendor"] == "" + assert identity["bios_version"] == "" + + +@pytest.mark.parametrize("date", ["", "not a date", "13/45/2021", "2021-11-22"]) +def test_a_firmware_date_that_is_no_smbios_date_reads_as_empty(date): + # sysfs writes the SMBIOS date as MM/DD/YYYY; anything else is no reading of it. + out = _out(UUID, "", "", ("Vendor", "1.2", date)) + assert parse_system_identity(out)["bios_date"] == "" + + +def test_output_of_the_identity_alone_has_no_firmware(): + # What a host answered before the firmware was read with it: three fields. + old = f"IDBEGIN\n{UUID}\nS1\nB1\nIDEND\n" + identity = parse_system_identity(old) + assert identity["board_serial"] == "B1" + assert {k: identity[k] for k in _NO_FIRMWARE} == _NO_FIRMWARE + + def test_output_without_its_frame_is_not_a_reading(): with pytest.raises(ValueError): parse_system_identity("sudo: a password is required\n") @@ -115,6 +175,13 @@ def test_the_driver_only_carries_the_command_across(): assert privileged is True -def test_the_command_reads_the_three_dmi_files(): - for name in ("product_uuid", "product_serial", "board_serial"): +def test_the_command_reads_the_dmi_files(): + for name in ( + "product_uuid", + "product_serial", + "board_serial", + "bios_vendor", + "bios_version", + "bios_date", + ): assert f"/sys/class/dmi/id/{name}" in SYSTEM_IDENTITY_COMMAND -- 2.54.1 From c25f39768fb918f3b614c9bdd4118e338166953b Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Fri, 13 Nov 2026 23:04:18 +0100 Subject: [PATCH 2/2] refactor(system-identity): keep SystemIdentityDict with its mixin models.py is over its line limit and may not grow; the dict has no other user than system_identity.py, as clusters.py and apt_proxy.py keep theirs. NetOrk/netork#2518 --- napalm_device_types/models.py | 15 --------------- napalm_device_types/system_identity.py | 17 +++++++++++++++-- tests/quality_baseline.json | 2 +- 3 files changed, 16 insertions(+), 18 deletions(-) diff --git a/napalm_device_types/models.py b/napalm_device_types/models.py index 3185226..8355a18 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -1440,18 +1440,3 @@ class ManagementProtocolsDict(TypedDict): snmp: ProtocolStateDict kvm: ProtocolStateDict virtual_media: ProtocolStateDict - - -class SystemIdentityDict(TypedDict): - """A host's SMBIOS identity, what ties it to its BMC, and its system firmware. - - See :mod:`napalm_device_types.system_identity`. - - Each value is empty when unknown or a vendor placeholder.""" - - system_uuid: str # lowercase - product_serial: str - board_serial: str - bios_vendor: str # the system firmware (BIOS or UEFI): its vendor, - bios_version: str # its version, - bios_date: str # its release date, YYYY-MM-DD diff --git a/napalm_device_types/system_identity.py b/napalm_device_types/system_identity.py index 325a551..a32a89c 100644 --- a/napalm_device_types/system_identity.py +++ b/napalm_device_types/system_identity.py @@ -25,11 +25,24 @@ from __future__ import annotations import re from datetime import date -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, TypedDict -from napalm_device_types.models import SystemIdentityDict from napalm_device_types.terminal import strip_terminal_codes + +class SystemIdentityDict(TypedDict): + """A host's SMBIOS identity, what ties it to its BMC, and its system firmware. + + Each value is empty when unknown or a vendor placeholder.""" + + system_uuid: str # lowercase + product_serial: str + board_serial: str + bios_vendor: str # the system firmware (BIOS or UEFI): its vendor, + bios_version: str # its version, + bios_date: str # its release date, YYYY-MM-DD + + _BEGIN = "IDBEGIN" _END = "IDEND" _DMI = "/sys/class/dmi/id" diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 4065f83..06714cf 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -31,7 +31,7 @@ }, "mypy_relaxed": [], "python_file_lines": { - "napalm_device_types/models.py": 1454 + "napalm_device_types/models.py": 1442 }, "untyped_public": [] } -- 2.54.1