Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<build>.<ubr>` 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.
Expand Down Expand Up @@ -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

Expand Down
4 changes: 4 additions & 0 deletions examples/inventory.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -30,20 +30,23 @@ assets:
count: 8
owner: windows
exposure: internal
device_class: windows-server
- id: file-servers-patched
product: Windows Server 2022
vendor: Microsoft
version: "10.0.20348.2655"
count: 5
owner: windows
exposure: internal
device_class: windows-server
- id: analyst-laptops
product: Windows 11 23H2
vendor: Microsoft
version: "10.0.22631.3593"
count: 15
owner: it
exposure: internal
device_class: windows
- id: bastion-ssh
product: OpenSSH
vendor: OpenBSD
Expand All @@ -65,6 +68,7 @@ assets:
count: 6
owner: windows
exposure: internal
device_class: windows-server
- id: custom-connector
product: Harbor Connector
vendor: Example Works
Expand Down
4 changes: 4 additions & 0 deletions src/patchorder/data/demo/inventory.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -30,20 +30,23 @@ assets:
count: 8
owner: windows
exposure: internal
device_class: windows-server
- id: file-servers-patched
product: Windows Server 2022
vendor: Microsoft
version: "10.0.20348.2655"
count: 5
owner: windows
exposure: internal
device_class: windows-server
- id: analyst-laptops
product: Windows 11 23H2
vendor: Microsoft
version: "10.0.22631.3593"
count: 15
owner: it
exposure: internal
device_class: windows
- id: bastion-ssh
product: OpenSSH
vendor: OpenBSD
Expand All @@ -65,6 +68,7 @@ assets:
count: 6
owner: windows
exposure: internal
device_class: windows-server
- id: custom-connector
product: Harbor Connector
vendor: Example Works
Expand Down
66 changes: 66 additions & 0 deletions src/patchorder/deviceclass.py
Original file line number Diff line number Diff line change
@@ -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."
)
20 changes: 20 additions & 0 deletions src/patchorder/inventory.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]+")


Expand Down Expand Up @@ -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"))
Expand Down Expand Up @@ -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)
Expand All @@ -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))
4 changes: 3 additions & 1 deletion src/patchorder/inventorytools.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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")
Expand Down
1 change: 1 addition & 0 deletions src/patchorder/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ class Asset:
count: int
owner: str
exposure: str
device_class: str = ""


@dataclass
Expand Down
12 changes: 10 additions & 2 deletions src/patchorder/resolver.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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] = []
Expand Down Expand Up @@ -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."
Expand Down
118 changes: 118 additions & 0 deletions tests/test_device_class.py
Original file line number Diff line number Diff line change
@@ -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)
Loading