diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a776ed..a04d38e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased +- Inventory rows can set `device_class` to `windows` or `windows-server`. Shared build families such as 26100 then offer only the matching edition. A Windows Server vNext build (29621 or later), as documented for the Intune Insider preview, does not invent a CPE. - CI: the setuptools build backend is in the hash-pinned `requirements-ci.txt`, and the project is installed with `--no-build-isolation`, so the build no longer downloads an unhashed setuptools. - Dependabot: weekly Python updates (uv ecosystem) for `pyproject.toml`, `requirements-ci.in` and the hash-pinned `requirements-ci.txt`. `requirements-ci.txt` is now compiled from `requirements-ci.in` so Dependabot can recompile it with hashes. - Demo: fictional Oracle Java SE rows for CVE-2026-114938 (Java4Shell) with a recorded NVD document (status Received, official Oracle CVSS 3.1 8.1, CNA affected versions, no invented CPE ranges or EPSS). The CVE is not in the demo KEV catalog. `from_nvd_cve` now reads NVD `affected` / `affectedData` when present; CPE `configurations` still win when both exist. diff --git a/README.md b/README.md index a12a8d2..7529473 100644 --- a/README.md +++ b/README.md @@ -223,7 +223,8 @@ The local matcher is the source of the affected / not affected / not decided lin - CVE List 5 `versions` blocks (`lessThan`, `lessThanOrEqual`, `status`, `defaultStatus`) when the record has no NVD configuration. Configurations win when both exist - Windows builds `10.0..` and `6.*`. `10.0.22631.3593` is before `10.0.22631.4037`. The marketing name `2022` is not compared with a build - OpenSSH `9.8p1` sorts after `9.8`. OpenSSL `1.1.1w` sorts before `1.1.1x` -- A build such as `10.0.22631.3593` on a row that only says "Windows 11" suggests `windows_11_23h2` and does not auto-use it. Build 26100 is offered as both Windows 11 24H2 and Windows Server 2025 +- A build such as `10.0.22631.3593` on a row that only says "Windows 11" suggests `windows_11_23h2` and does not auto-use it. Build 26100 is offered as both Windows 11 24H2 and Windows Server 2025, unless you set `device_class` to `windows` or `windows-server` (or the product name already says Windows Server) +- Optional inventory field `device_class`: `windows` or `windows-server`. Use it when Intune-managed Windows Server devices should not share CPE candidates with Windows clients. Microsoft Intune can manage eligible Windows Server vNext builds (29621.1000 or later, Desktop Experience) only as a nonproduction Insider preview; see [What's new](https://learn.microsoft.com/en-us/intune/whats-new/) and the [preview guide](https://learn.microsoft.com/en-us/intune/solutions/end-to-end-guides/windows-server-endpoints-get-started). A 29621+ server row does not invent a Windows Server 2028 CPE; pin one after you have checked the dictionary - A negated CPE node, or an AND configuration that also requires a product this row does not name, is not decided The alias table is a starter set (nginx, NGINX Plus, OpenSSL, Apache HTTP Server, Tomcat, OpenSSH, PHP, curl, PostgreSQL, MySQL, MariaDB, and a handful of Windows releases). It is not a CPE dictionary. Pin the CPE after you have looked at the candidates. @@ -269,7 +270,7 @@ python -m pip install -e ".[dev]" python -m pytest ``` -The suite currently has 96 tests. Pytest blocks sockets. CI runs the same suite on Python 3.11, 3.12, and 3.13, then runs the offline demo with `--fail-on kev` (expected to exit 4) and `inventory check` on the example (`.github/workflows/ci.yml`). +The suite has 103 pytest tests. Pytest blocks sockets. CI runs the same suite on Python 3.11, 3.12, and 3.13, then runs the offline demo with `--fail-on kev` (expected to exit 4) and `inventory check` on the example (`.github/workflows/ci.yml`). ## How to contribute diff --git a/examples/inventory.yaml b/examples/inventory.yaml index 6d012c4..61645a5 100644 --- a/examples/inventory.yaml +++ b/examples/inventory.yaml @@ -30,6 +30,7 @@ assets: count: 8 owner: windows exposure: internal + device_class: windows-server - id: file-servers-patched product: Windows Server 2022 vendor: Microsoft @@ -37,6 +38,7 @@ assets: count: 5 owner: windows exposure: internal + device_class: windows-server - id: analyst-laptops product: Windows 11 23H2 vendor: Microsoft @@ -44,6 +46,7 @@ assets: count: 15 owner: it exposure: internal + device_class: windows - id: bastion-ssh product: OpenSSH vendor: OpenBSD @@ -65,6 +68,7 @@ assets: count: 6 owner: windows exposure: internal + device_class: windows-server - id: custom-connector product: Harbor Connector vendor: Example Works diff --git a/src/patchorder/data/demo/inventory.yaml b/src/patchorder/data/demo/inventory.yaml index 6d012c4..61645a5 100644 --- a/src/patchorder/data/demo/inventory.yaml +++ b/src/patchorder/data/demo/inventory.yaml @@ -30,6 +30,7 @@ assets: count: 8 owner: windows exposure: internal + device_class: windows-server - id: file-servers-patched product: Windows Server 2022 vendor: Microsoft @@ -37,6 +38,7 @@ assets: count: 5 owner: windows exposure: internal + device_class: windows-server - id: analyst-laptops product: Windows 11 23H2 vendor: Microsoft @@ -44,6 +46,7 @@ assets: count: 15 owner: it exposure: internal + device_class: windows - id: bastion-ssh product: OpenSSH vendor: OpenBSD @@ -65,6 +68,7 @@ assets: count: 6 owner: windows exposure: internal + device_class: windows-server - id: custom-connector product: Harbor Connector vendor: Example Works diff --git a/src/patchorder/deviceclass.py b/src/patchorder/deviceclass.py new file mode 100644 index 0000000..550aa2e --- /dev/null +++ b/src/patchorder/deviceclass.py @@ -0,0 +1,66 @@ +"""Windows client vs Windows Server as inventory device classes. + +The class is optional. When it is set, CPE resolution can tell editions +apart that share a build family (for example 26100 is both Windows 11 24H2 +and Windows Server 2025). When it is omitted, a product name that already +says "Windows Server" is treated as a server; a bare "Windows" stays +ambiguous. + +Microsoft Intune can manage eligible Windows Server devices only as an +Insider preview (nonproduction, Windows Server vNext build 29621.1000 or +later, Desktop Experience). See: + +- https://learn.microsoft.com/en-us/intune/whats-new/ +- https://learn.microsoft.com/en-us/intune/solutions/end-to-end-guides/windows-server-endpoints-get-started +""" + +from __future__ import annotations + +from patchorder.models import Asset +from patchorder.normalize import tokens + +WINDOWS = "windows" +WINDOWS_SERVER = "windows-server" + +# Minimum build documented for the Intune Windows Server Insider preview. +# The official name is Windows Server vNext; this is not a published NVD CPE. +INTUNE_SERVER_PREVIEW_MIN_BUILD = 29621 + +_CLIENT_MARKERS = frozenset({"10", "11"}) + + +def infer_device_class(asset: Asset) -> str: + if asset.device_class: + return asset.device_class + product_tokens = tokens(asset.product) + if "windows" in product_tokens and "server" in product_tokens: + return WINDOWS_SERVER + if "windows" in product_tokens and (_CLIENT_MARKERS & set(product_tokens)): + return WINDOWS + return "" + + +def filter_build_families( + families: tuple[tuple[str, str], ...], device_class: str +) -> tuple[tuple[str, str], ...]: + if device_class == WINDOWS_SERVER: + return tuple(item for item in families if item[0].startswith("windows_server_")) + if device_class == WINDOWS: + return tuple( + item + for item in families + if item[0].startswith("windows_") and not item[0].startswith("windows_server_") + ) + return families + + +def preview_build_hint(build: int, device_class: str) -> str: + if device_class != WINDOWS_SERVER or build < INTUNE_SERVER_PREVIEW_MIN_BUILD: + return "" + return ( + f"Build {build} is at or above {INTUNE_SERVER_PREVIEW_MIN_BUILD}, the minimum " + "Windows Server vNext build documented for the Intune Windows Server " + "Insider preview (nonproduction only). No NVD CPE for that preview name " + "is in the starter table; pin a CPE after you have checked the dictionary. " + "Do not invent a marketing name such as Windows Server 2028." + ) diff --git a/src/patchorder/inventory.py b/src/patchorder/inventory.py index e228eee..a3f8e8c 100644 --- a/src/patchorder/inventory.py +++ b/src/patchorder/inventory.py @@ -11,6 +11,7 @@ from patchorder.models import Asset, Inventory _EXPOSURES = {"internet": "internet", "internal": "internal"} +_DEVICE_CLASSES = {"windows": "windows", "windows-client": "windows", "windows-server": "windows-server"} _SLUG = re.compile(r"[^a-z0-9]+") @@ -50,6 +51,23 @@ def _slug(vendor: str, product: str, version: str, used: set[str]) -> str: return slug + +def _parse_device_class(value: object, where: str) -> str: + if value is None or value == "": + return "" + if isinstance(value, bool) or not isinstance(value, str): + raise PatchorderError( + f"{where} device_class must be windows, windows-server, or omitted" + ) + key = value.strip().lower() + parsed = _DEVICE_CLASSES.get(key) + if parsed is None: + raise PatchorderError( + f"{where} device_class {value!r} must be windows, windows-server, or omitted" + ) + return parsed + + def load_inventory(path: Path) -> Inventory: try: data = yaml.safe_load(path.read_text(encoding="utf-8")) @@ -95,6 +113,7 @@ def load_inventory(path: Path) -> Inventory: exposure = _EXPOSURES.get(exposure_raw.strip().lower()) if exposure is None: raise PatchorderError(f"{where} exposure must be internet or internal") + device_class = _parse_device_class(raw.get("device_class"), where) asset_id = raw.get("id") if asset_id is None or asset_id == "": asset_id = _slug(vendor, product, version, used) @@ -114,6 +133,7 @@ def load_inventory(path: Path) -> Inventory: count=count, owner=owner.strip(), exposure=exposure, + device_class=device_class, ) ) return Inventory(name=name.strip(), assets=loaded, source=str(path)) diff --git a/src/patchorder/inventorytools.py b/src/patchorder/inventorytools.py index 9469a3b..09a5b0d 100644 --- a/src/patchorder/inventorytools.py +++ b/src/patchorder/inventorytools.py @@ -16,7 +16,7 @@ from patchorder.lockfile import default_lock_path, load_lock from patchorder.versions import version_is_comparable -FIELDS = ("id", "product", "vendor", "version", "count", "owner", "exposure") +FIELDS = ("id", "product", "vendor", "version", "count", "owner", "exposure", "device_class") _HEADER_ALIASES = { "name": "product", "software": "product", "application": "product", "manufacturer": "vendor", "publisher": "vendor", @@ -115,6 +115,8 @@ def csv_to_inventory(text: str, name: str, default_owner: str = "unassigned", de asset["count"] = count asset["owner"] = item.get("owner") or default_owner asset["exposure"] = exposure + if item.get("device_class"): + asset["device_class"] = item["device_class"] assets.append(asset) if not assets: raise PatchorderError("CSV has no data rows") diff --git a/src/patchorder/models.py b/src/patchorder/models.py index c68b1ad..d38144d 100644 --- a/src/patchorder/models.py +++ b/src/patchorder/models.py @@ -14,6 +14,7 @@ class Asset: count: int owner: str exposure: str + device_class: str = "" @dataclass diff --git a/src/patchorder/resolver.py b/src/patchorder/resolver.py index f872244..dcda55c 100644 --- a/src/patchorder/resolver.py +++ b/src/patchorder/resolver.py @@ -6,6 +6,7 @@ from patchorder.aliases import BUILD_FAMILY, alias_candidates from patchorder.cpe import canonical_base +from patchorder.deviceclass import filter_build_families, infer_device_class, preview_build_hint from patchorder.models import Asset, Candidate, LockEntry, Resolution from patchorder.normalize import tokens @@ -38,6 +39,9 @@ def apply_build_hints(asset: Asset, candidates: list[Candidate]) -> list[Candida return candidates return candidates families = BUILD_FAMILY.get(build) + device_class = infer_device_class(asset) + if families: + families = filter_build_families(families, device_class) if not families: return candidates updated: list[Candidate] = [] @@ -155,10 +159,14 @@ def resolve_asset( candidates = apply_build_hints(asset, candidates) candidates = _dedupe(candidates) hint = "" + build = _windows_build(asset) + if build is not None: + hint = preview_build_hint(build, infer_device_class(asset)) if not candidates and _looks_like_windows(asset): - hint = ( + hint = hint or ( "Name the Windows release (for example Windows 11 23H2 or Windows Server 2022) " - "or a build such as 10.0.22631.3593, then pin the CPE." + "or a build such as 10.0.22631.3593, then pin the CPE. " + "Set device_class to windows or windows-server when the product name is ambiguous." ) elif not candidates: hint = "No alias or dictionary hit. Pin a CPE yourself, or run resolve with CPE discovery online." diff --git a/tests/test_device_class.py b/tests/test_device_class.py new file mode 100644 index 0000000..5ed224d --- /dev/null +++ b/tests/test_device_class.py @@ -0,0 +1,118 @@ +from pathlib import Path + +import pytest + +from patchorder.errors import PatchorderError +from patchorder.inventory import load_inventory +from patchorder.models import Asset +from patchorder.resolver import AUTO_USE_CONFIDENCE, resolve_asset + + +def _asset(**kwargs): + base = dict( + id="a", + product="Windows", + vendor="Microsoft", + version="10.0.26100.1000", + count=1, + owner="ops", + exposure="internal", + ) + base.update(kwargs) + return Asset(**base) + + +def test_ambiguous_26100_stays_ambiguous_without_a_class(): + resolution = resolve_asset(_asset()) + cpes = {item.cpe for item in resolution.candidates} + assert "cpe:2.3:o:microsoft:windows_11_24h2" in cpes + assert "cpe:2.3:o:microsoft:windows_server_2025" in cpes + assert resolution.chosen is None + + +def test_device_class_windows_server_keeps_only_the_server_edition(): + resolution = resolve_asset(_asset(device_class="windows-server")) + cpes = {item.cpe for item in resolution.candidates} + assert cpes == {"cpe:2.3:o:microsoft:windows_server_2025"} + assert resolution.chosen is None + assert resolution.candidates[0].confidence < AUTO_USE_CONFIDENCE + assert "Windows Server 2025" in resolution.candidates[0].note + + +def test_device_class_windows_keeps_only_the_client_edition(): + resolution = resolve_asset(_asset(device_class="windows")) + cpes = {item.cpe for item in resolution.candidates} + assert cpes == {"cpe:2.3:o:microsoft:windows_11_24h2"} + assert resolution.chosen is None + + +def test_windows_server_product_name_is_enough_to_drop_the_client_edition(): + resolution = resolve_asset(_asset(product="Windows Server", device_class="")) + cpes = {item.cpe for item in resolution.candidates} + assert "cpe:2.3:o:microsoft:windows_server_2025" in cpes + assert "cpe:2.3:o:microsoft:windows_11_24h2" not in cpes + + +def test_vnext_preview_build_does_not_invent_a_cpe(): + resolution = resolve_asset( + _asset( + product="Windows Server vNext", + version="10.0.29621.1000", + device_class="windows-server", + ) + ) + assert resolution.candidates == [] + assert resolution.chosen is None + assert "29621" in resolution.hint + assert "vNext" in resolution.hint + assert "2028" in resolution.hint + + +def test_inventory_loads_device_class(tmp_path: Path): + path = tmp_path / "inventory.yaml" + path.write_text( + "\n".join( + [ + "schema: patchorder.inventory/v1", + "name: lab", + "assets:", + " - id: srv", + " product: Windows Server 2022", + " vendor: Microsoft", + ' version: "10.0.20348.2400"', + " count: 2", + " owner: windows", + " exposure: internal", + " device_class: windows-server", + "", + ] + ), + encoding="utf-8", + ) + inventory = load_inventory(path) + assert inventory.assets[0].device_class == "windows-server" + + +def test_inventory_rejects_an_unknown_device_class(tmp_path: Path): + path = tmp_path / "inventory.yaml" + path.write_text( + "\n".join( + [ + "schema: patchorder.inventory/v1", + "name: lab", + "assets:", + " - id: srv", + " product: Windows Server 2022", + " vendor: Microsoft", + ' version: "10.0.20348.2400"', + " count: 2", + " owner: windows", + " exposure: internal", + " device_class: laptop", + "", + ] + ), + encoding="utf-8", + ) + with pytest.raises(PatchorderError, match="device_class"): + load_inventory(path)