os-normalizer 0.3.2__py3-none-any.whl

os_normalizer/os_normalizer.py

@@ -0,0 +1,313 @@
+from datetime import UTC, datetime
+from typing import Any, Iterable
+from dataclasses import replace, fields
+import copy
+
+from os_normalizer.helpers import extract_arch_from_text, precision_from_parts, update_confidence
+from os_normalizer.cpe import build_cpe23
+from os_normalizer.models import OSData
+from os_normalizer.parsers.bsd import parse_bsd
+from os_normalizer.parsers.linux import parse_linux
+from os_normalizer.parsers.macos import parse_macos
+from os_normalizer.parsers.mobile import parse_mobile
+from os_normalizer.parsers.network import parse_network
+from os_normalizer.parsers.windows import parse_windows
+
+PRECISION_ORDER = {
+    "build": 6,
+    "patch": 5,
+    "minor": 4,
+    "major": 3,
+    "product": 2,
+    "family": 1,
+    "unknown": 0,
+}
+
+
+# ============================================================
+# Family detection (orchestrator logic)
+# ============================================================
+def detect_family(text: str, data: dict[str, Any]) -> tuple[str | None, float, dict[str, Any]]:
+    t = text.lower()
+    ev = {}
+    # Obvious network signals first
+    if any(
+        x in t
+        for x in [
+            "cisco",
+            "nx-os",
+            "ios xe",
+            "ios-xe",
+            "junos",
+            "fortios",
+            "fortigate",
+            "huawei",
+            "vrp",
+            "netgear",
+            "firmware v",
+        ]
+    ):
+        # Special handling for 'ios' - if it's just 'ios' without 'cisco', treat as mobile, not network
+        if "ios " in t and "cisco" not in t:
+            ev["hit"] = "ios"
+            return "ios", 0.6, ev
+
+        ev["hit"] = "network-os"
+        return "network-os", 0.7, ev
+    # Linux
+    if "linux" in t or any(k in data for k in ("ID", "ID_LIKE", "PRETTY_NAME", "VERSION_ID", "VERSION_CODENAME")):
+        ev["hit"] = "linux"
+        return "linux", 0.6, ev
+    # Windows
+    if "windows" in t or "nt " in t or t.startswith("win") or data.get("os", "").lower() == "windows":
+        ev["hit"] = "windows"
+        return "windows", 0.6, ev
+    # Apple
+    if "macos" in t or "os x" in t or "darwin" in t:
+        ev["hit"] = "macos"
+        return "macos", 0.6, ev
+    if "ios" in t or "ipados" in t:
+        ev["hit"] = "ios"
+        return "ios", 0.6, ev
+    # Android
+    if "android" in t:
+        ev["hit"] = "android"
+        return "android", 0.6, ev
+    # BSD
+    if "freebsd" in t or "openbsd" in t or "netbsd" in t:
+        ev["hit"] = "bsd"
+        return "bsd", 0.6, ev
+    return None, 0.0, ev
+
+
+def normalize_os(text: str, data: dict | None = None) -> OSData:
+    text = text.strip()
+    data = data or {}
+    t = text.lower()
+
+    p = OSData()
+
+    # Family detection
+    fam, base_conf, ev = detect_family(t, data)
+    p.family = fam
+    p.confidence = max(p.confidence, base_conf)
+    p.evidence.update(ev)
+
+    if fam == "network-os":
+        p = parse_network(text, data, p)
+    elif fam == "windows":
+        p = parse_windows(text, data, p)
+    elif fam == "macos":
+        p = parse_macos(text, data, p)
+    elif fam == "linux":
+        p = parse_linux(text, data, p)
+    elif fam in ("android", "ios"):
+        p = parse_mobile(text, data, p)
+    elif fam == "bsd":
+        p = parse_bsd(text, data, p)
+    else:
+        p.precision = "unknown"
+
+    # Fallback arch from text if not already set elsewhere
+    if not p.arch:
+        p.arch = extract_arch_from_text(text)
+
+    # Populate canonical os_key as CPE 2.3
+    try:
+        p.os_key = build_cpe23(p)
+    except Exception:
+        # Be resilient: leave unset on any unexpected error
+        p.os_key = None
+
+    return p
+
+
+def choose_best_fact(candidates: list[OSData]) -> OSData:
+    if not candidates:
+        raise ValueError("No candidates")
+    return sorted(
+        candidates,
+        key=lambda c: (PRECISION_ORDER.get(c.precision, 0), c.confidence),
+        reverse=True,
+    )[0]
+
+
+# ============================================================
+# Merge/update APIs
+# ============================================================
+
+
+def _score(p: OSData) -> tuple[int, float]:
+    return (PRECISION_ORDER.get(p.precision, 0), p.confidence)
+
+
+def _union_unique(values: Iterable[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for v in values:
+        if v not in seen:
+            seen.add(v)
+            out.append(v)
+    return out
+
+
+def merge_os(a: OSData, b: OSData, policy: str = "auto") -> OSData:
+    """Merge two OSData objects into a new one.
+
+    Default policy 'auto' keeps the base object with higher (precision, confidence)
+    and fills missing details from the other. Conflicts are recorded under
+    evidence['conflicts'] and evidence['alt'].
+    """
+    base, other = (a, b) if _score(a) >= _score(b) else (b, a)
+    r = replace(base)
+
+    # Ensure evidence containers exist
+    r.evidence = dict(r.evidence or {})
+    conflicts = dict(r.evidence.get("conflicts", {}))
+    alts = dict(r.evidence.get("alt", {}))
+
+    def fill(field: str) -> None:
+        av = getattr(r, field)
+        bv = getattr(other, field)
+        if av is None and bv is not None:
+            setattr(r, field, bv)
+        elif bv is not None and av is not None and av != bv:
+            # Conflict: keep current, store alternative
+            alts[field] = bv
+            conflicts[field] = [av, bv]
+
+    # Identity & descriptive fields
+    for f in (
+        "family",
+        "vendor",
+        "product",
+        "edition",
+        "codename",
+        "channel",
+        "distro",
+        "pretty_name",
+        "kernel_name",
+        "kernel_version",
+        "arch",
+        "hw_model",
+        "build_id",
+    ):
+        fill(f)
+
+    # kernel_version: prefer longer/more specific token when both present
+    if base.kernel_version and other.kernel_version and len(other.kernel_version) > len(base.kernel_version):
+        r.kernel_version = other.kernel_version
+
+    # like_distros union
+    if other.like_distros:
+        r.like_distros = _union_unique([*(r.like_distros or []), *other.like_distros])
+
+    # Version components: fill missing; record conflicts if both present and differ
+    def choose_versions(x: OSData, y: OSData) -> tuple[str | None, int | None, int | None, int | None]:
+        build = x.version_build or y.version_build
+        maj = x.version_major if x.version_major is not None else y.version_major
+        minr = x.version_minor if x.version_minor is not None else y.version_minor
+        pat = x.version_patch if x.version_patch is not None else y.version_patch
+        for name, xa, ya in (
+            ("version_build", x.version_build, y.version_build),
+            ("version_major", x.version_major, y.version_major),
+            ("version_minor", x.version_minor, y.version_minor),
+            ("version_patch", x.version_patch, y.version_patch),
+        ):
+            if xa is not None and ya is not None and xa != ya:
+                conflicts[name] = [xa, ya]
+        return build, maj, minr, pat
+
+    vb, vmaj, vmin, vpat = choose_versions(base, other)
+    r.version_build, r.version_major, r.version_minor, r.version_patch = vb, vmaj, vmin, vpat
+
+    # Merge evidence (shallow)
+    if other.evidence:
+        r.evidence.update(other.evidence)
+
+    # Precision & confidence: recompute based on version parts
+    new_prec = precision_from_parts(r.version_major, r.version_minor, r.version_patch, r.version_build)
+    if new_prec == "product" and not r.product:
+        new_prec = "family" if r.family else "unknown"
+    r.precision = new_prec
+    r.confidence = max(a.confidence, b.confidence)
+    update_confidence(r, r.precision)
+
+    # Attach conflicts/alternates
+    if conflicts:
+        r.evidence["conflicts"] = conflicts
+    if alts:
+        r.evidence["alt"] = alts
+
+    # Refresh CPE key
+    try:
+        r.os_key = build_cpe23(r)
+    except Exception:
+        r.os_key = None
+
+    return r
+
+
+def update_os(
+    existing: OSData, text: str | None = None, data: dict | None = None, policy: str = "auto", inplace: bool = False
+) -> OSData:
+    """Parse new input, merge into existing OSData, and return the result.
+
+    Set inplace=True to mutate the existing instance.
+    """
+    incoming = normalize_os(text or "", data or {}) if (text or data) else OSData()
+    merged = merge_os(existing, incoming, policy=policy)
+    if inplace:
+        # Generic copy of dataclass fields with shallow copy for common containers
+        for f in fields(OSData):
+            val = getattr(merged, f.name)
+            if isinstance(val, (dict, list, set)):
+                val = copy.copy(val)
+            setattr(existing, f.name, val)
+        return existing
+    return merged
+
+
+if __name__ == "__main__":
+    now = datetime.now(tz=UTC)
+    samples = [
+        {
+            "text": "Windows NT 10.0 build 22631 Enterprise x64",
+        },
+        {
+            "text": "Darwin 24.0.0; macOS Sequoia arm64",
+        },
+        {
+            "text": "Linux host 5.15.0-122-generic x86_64",
+            "data": {
+                "os_release": 'NAME="Ubuntu"\nID=ubuntu\nVERSION_ID="22.04.4"\nVERSION_CODENAME=jammy\nPRETTY_NAME="Ubuntu 22.04.4 LTS"',
+            },
+        },
+        {
+            "text": "Cisco IOS XE Software, Version 17.9.4a (Amsterdam) C9300-24T, universalk9, c9300-universalk9.17.09.04a.SPA.bin",
+        },
+        {
+            "text": "FortiGate-100F v7.2.7 build1600 (GA) FGT_7.2.7-build1600",
+        },
+        {
+            "text": "Cisco Nexus Operating System (NX-OS) Software nxos.9.3.5.bin N9K-C93180YC-FX",
+        },
+        {
+            "text": "Junos: 20.4R3-S3 jinstall-ex-4300-20.4R3-S3.tgz EX4300-48T",
+        },
+        {
+            "text": "Huawei VRP V800R012C00SPC500 S5720-28X-SI-AC",
+        },
+        {
+            "text": "NETGEAR Firmware V1.0.9.88_10.2.88 R7000",
+        },
+        {
+            "text": "Darwin Mac-Studio.local 24.6.0 Darwin Kernel Version 24.6.0: Mon Jul 14 11:30:40 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T6041 arm64",
+        },
+    ]
+
+    for s in samples:
+        parsed = normalize_os(text=s.get("text"), data=s.get("data"))
+        print("----", s.get("text"))
+        print(parsed)
+        print()

os_normalizer/parsers/__init__.py

@@ -0,0 +1,16 @@
+from .windows import parse_windows
+from .macos import parse_macos
+from .linux import parse_linux
+from .mobile import parse_mobile
+from .bsd import parse_bsd
+from .network import parse_network
+
+__all__ = [
+    "parse_windows",
+    "parse_macos",
+    "parse_linux",
+    "parse_mobile",
+    "parse_bsd",
+    "parse_network",
+]
+

os_normalizer/parsers/bsd.py

@@ -0,0 +1,69 @@
+"""BSD specific parsing logic (refactored, variant + channel handling)."""
+
+import re
+from typing import Any
+
+from os_normalizer.helpers import (
+    parse_semver_like,
+    precision_from_parts,
+    update_confidence,
+)
+from os_normalizer.models import OSData
+
+FREEBSD_RE = re.compile(r"\bfreebsd\b", re.IGNORECASE)
+OPENBSD_RE = re.compile(r"\bopenbsd\b", re.IGNORECASE)
+NETBSD_RE = re.compile(r"\bnetbsd\b", re.IGNORECASE)
+
+VARIANT_VERSION_RE = re.compile(
+    r"\b(?:freebsd|openbsd|netbsd)\b\s+(\d+)(?:\.(\d+))?(?:\.(\d+))?",
+    re.IGNORECASE,
+)
+BSD_CHANNEL_RE = re.compile(
+    r"(?:[-_\s])(RELEASE|STABLE|CURRENT|RC\d*|BETA\d*|RC|BETA)\b",
+    re.IGNORECASE,
+)
+
+
+def parse_bsd(text: str, data: dict[str, Any], p: OSData) -> OSData:
+    """Populate an OSData instance with BSD-specific details.
+
+    Detects FreeBSD, OpenBSD, or NetBSD and extracts version numbers.
+    """
+    tl = text.lower()
+
+    # Explicitly set product/vendor/kernel by scanning tokens
+    if FREEBSD_RE.search(tl):
+        name = "FreeBSD"
+    elif OPENBSD_RE.search(tl):
+        name = "OpenBSD"
+    elif NETBSD_RE.search(tl):
+        name = "NetBSD"
+    else:
+        name = "BSD"
+
+    p.product = name
+    p.vendor = name
+    p.kernel_name = name.lower()
+
+    # Prefer variant-anchored version pattern; fall back to generic semver
+    x, y, z = _extract_version(text)
+    p.version_major, p.version_minor, p.version_patch = x, y, z
+    p.precision = precision_from_parts(x, y, z, None) if x else "product"
+
+    # Channel from explicit markers/suffixes
+    ch = BSD_CHANNEL_RE.search(text)
+    if ch:
+        p.channel = ch.group(1).upper()
+
+    update_confidence(p, p.precision)
+    return p
+
+
+def _extract_version(text: str) -> tuple[int | None, int | None, int | None]:
+    m = VARIANT_VERSION_RE.search(text)
+    if m:
+        major = int(m.group(1))
+        minor = int(m.group(2)) if m.group(2) else None
+        patch = int(m.group(3)) if m.group(3) else None
+        return major, minor, patch
+    return parse_semver_like(text)

os_normalizer/parsers/linux.py

@@ -0,0 +1,121 @@
+"""Linux specific parsing logic (refactored)."""
+
+import re
+from typing import Any, Optional
+
+from os_normalizer.helpers import parse_os_release, update_confidence
+from os_normalizer.models import OSData
+
+# Regex patterns used only by the Linux parser
+KERNEL_RE = re.compile(
+    r"\b(kernel|uname)\b.*?\b(\d+\.\d+(?:\.\d+)?(?:-\S+)?)",
+    re.IGNORECASE,
+)
+LINUX_VER_FALLBACK_RE = re.compile(
+    r"\bLinux\b[^\n]*?\b(\d+\.\d+(?:\.\d+)?(?:-[A-Za-z0-9._-]+)?)\b",
+    re.IGNORECASE,
+)
+
+
+def parse_linux(text: str, data: dict[str, Any], p: OSData) -> OSData:
+    """Populate an OSData instance with Linux‑specific details."""
+    p.kernel_name = "linux"
+
+    osrel = _coerce_os_release(data.get("os_release")) if isinstance(data, dict) else None
+
+    # 1) Kernel version extraction
+    p.kernel_version = _extract_kernel_version(text)
+
+    # 2) Apply os-release information when present
+    if osrel:
+        _apply_os_release(osrel, p)
+    else:
+        p.product = p.product or "Linux"
+        p.precision = "family"
+
+    update_confidence(p, p.precision)
+    return p
+
+
+def _coerce_os_release(obj: Any) -> Optional[dict[str, Any]]:
+    if isinstance(obj, str):
+        return parse_os_release(obj)
+    if isinstance(obj, dict):
+        return {k.upper(): v for k, v in obj.items()}
+    return None
+
+
+def _extract_kernel_version(text: str) -> Optional[str]:
+    m = KERNEL_RE.search(text)
+    if m:
+        return m.group(2)
+    m2 = LINUX_VER_FALLBACK_RE.search(text)
+    if m2:
+        return m2.group(1)
+    return None
+
+
+def _apply_os_release(osrel: dict[str, Any], p: OSData) -> None:
+    distro_id = osrel.get("ID")
+    if distro_id:
+        p.distro = str(distro_id).lower()
+
+    like = osrel.get("ID_LIKE")
+    if like:
+        p.like_distros = [s.lower() for s in like] if isinstance(like, list) else [str(like).lower()]
+
+    p.pretty_name = osrel.get("PRETTY_NAME") or osrel.get("NAME")
+
+    _apply_version_id(osrel.get("VERSION_ID"), p)
+
+    vcode = osrel.get("VERSION_CODENAME")
+    if vcode:
+        p.codename = str(vcode).title()
+
+    if p.pretty_name and "LTS" in str(p.pretty_name).upper():
+        p.channel = "LTS"
+
+    p.vendor = _vendor_for_distro(p.distro) if p.distro else p.vendor
+
+    name = osrel.get("NAME")
+    p.product = (name if name else (p.distro or "Linux")).replace('"', "") if isinstance(name, str) else (p.distro or "Linux")
+
+    # Precision from version parts
+    if p.version_patch is not None:
+        p.precision = "patch"
+    elif p.version_minor is not None:
+        p.precision = "minor"
+    elif p.version_major is not None:
+        p.precision = "major"
+    else:
+        p.precision = "family"
+
+
+def _apply_version_id(vid: Any, p: OSData) -> None:
+    if not vid:
+        return
+    parts = re.split(r"[.]+", str(vid))
+    if len(parts) >= 1 and parts[0].isdigit():
+        p.version_major = int(parts[0])
+    if len(parts) >= 2 and parts[1].isdigit():
+        p.version_minor = int(parts[1])
+    if len(parts) >= 3 and parts[2].isdigit():
+        p.version_patch = int(parts[2])
+
+
+def _vendor_for_distro(distro: Optional[str]) -> Optional[str]:
+    vendor_by_distro = {
+        "ubuntu": "Canonical",
+        "debian": "Debian",
+        "rhel": "Red Hat",
+        "rocky": "Rocky",
+        "almalinux": "AlmaLinux",
+        "centos": "Red Hat",
+        "amzn": "Amazon",
+        "amazon": "Amazon",
+        "sles": "SUSE",
+        "opensuse": "SUSE",
+        "arch": "Arch",
+        "fedora": "Fedora Project",
+    }
+    return vendor_by_distro.get(distro) if distro else None

os_normalizer/parsers/macos.py

@@ -0,0 +1,111 @@
+"""macOS specific parsing logic (refactored)."""
+
+import re
+from typing import Any
+
+from os_normalizer.constants import MACOS_ALIASES, MACOS_DARWIN_MAP
+from os_normalizer.helpers import update_confidence
+from os_normalizer.models import OSData
+
+# Regex patterns used only by the macOS parser
+DARWIN_RE = re.compile(
+    r"\bdarwin\b[^\d\n]*?(\d+)(?:\.(\d+))?(?:\.(\d+))?\b",
+    re.IGNORECASE,
+)
+MACOS_VER_FALLBACK_RE = re.compile(r"\bmacos\s?(\d+)(?:\.(\d+))?", re.IGNORECASE)
+
+# Local precision order for simple comparisons
+_PRECISION_ORDER = {"family": 0, "product": 1, "major": 2, "minor": 3, "patch": 4, "build": 5}
+
+
+def parse_macos(text: str, data: dict[str, Any], p: OSData) -> OSData:
+    """Populate an OSData instance with macOS-specific details."""
+    t = text
+    tl = t.lower()
+
+    # Base identity
+    p.product = p.product or "macOS"
+    p.vendor = p.vendor or "Apple"
+
+    # 1) Alias-based version hints (e.g., "Sequoia" -> macOS 15)
+    _apply_alias_hint(tl, p)
+
+    # 2) Darwin kernel mapping to macOS version/codename
+    _apply_darwin_mapping(t, p)
+
+    # 3) Fallback: parse "macOS <ver>" from text
+    _apply_version_fallback(t, p)
+
+    # 4) Fallback: detect codename from text if still missing
+    _apply_codename_fallback(tl, p)
+
+    # Confidence boost based on precision
+    update_confidence(p, p.precision)
+    return p
+
+
+def _apply_alias_hint(tl: str, p: OSData) -> None:
+    for alias, normalized in MACOS_ALIASES.items():
+        if alias in tl:
+            parts = normalized.split()
+            if len(parts) == 2 and parts[1].isdigit():
+                p.version_major = int(parts[1])
+                p.precision = _max_precision(p.precision, "major")
+
+
+def _apply_darwin_mapping(t: str, p: OSData) -> None:
+    m = DARWIN_RE.search(t)
+    if not m:
+        return
+    dmaj = int(m.group(1))
+    p.kernel_name = "darwin"
+    p.kernel_version = ".".join([g for g in m.groups() if g])
+
+    if dmaj in MACOS_DARWIN_MAP:
+        prod, ver, code = MACOS_DARWIN_MAP[dmaj]
+        p.product = prod
+        if ver.isdigit():
+            p.version_major = int(ver)
+            p.precision = _max_precision(p.precision, "major")
+        else:
+            x, y, *_ = ver.split(".")
+            p.version_major = int(x)
+            p.version_minor = int(y)
+            p.precision = _max_precision(p.precision, "minor")
+        p.codename = code
+
+
+def _apply_version_fallback(t: str, p: OSData) -> None:
+    if p.version_major:
+        return
+    mm = MACOS_VER_FALLBACK_RE.search(t)
+    if not mm:
+        return
+    p.version_major = int(mm.group(1))
+    if mm.group(2):
+        p.version_minor = int(mm.group(2))
+        p.precision = _max_precision(p.precision, "minor")
+    else:
+        p.precision = _max_precision(p.precision, "major")
+
+
+def _apply_codename_fallback(tl: str, p: OSData) -> None:
+    if p.codename:
+        return
+    for dmaj, (_, ver, code) in MACOS_DARWIN_MAP.items():
+        if code.lower() in tl:
+            p.codename = code
+            # Provide at least major version from the map
+            if isinstance(ver, str) and ver.isdigit():
+                p.version_major = int(ver)
+                p.precision = _max_precision(p.precision, "major")
+            elif isinstance(ver, str) and "." in ver:
+                x, *_ = ver.split(".")
+                if x.isdigit():
+                    p.version_major = int(x)
+                    p.precision = _max_precision(p.precision, "major")
+            break
+
+
+def _max_precision(current: str, new_label: str) -> str:
+    return new_label if _PRECISION_ORDER.get(new_label, 0) > _PRECISION_ORDER.get(current, 0) else current

os_normalizer/parsers/mobile.py

@@ -0,0 +1,37 @@
+"""Mobile device specific parsing logic."""
+
+from typing import Any
+
+from os_normalizer.helpers import (
+    parse_semver_like,
+    precision_from_parts,
+    update_confidence,
+)
+from os_normalizer.models import OSData
+
+
+def parse_mobile(text: str, data: dict[str, Any], p: OSData) -> OSData:
+    """Populate an OSData instance with mobile device-specific details."""
+    t = text.lower()
+
+    # Detect if it's iOS or Android
+    if "ios" in t or "ipados" in t:
+        p.product = "iOS/iPadOS"
+        p.vendor = "Apple"
+    elif "android" in t:
+        p.product = "Android"
+        p.vendor = "Google"
+    else:
+        # Default for unknown mobile OS
+        p.product = "Mobile OS"
+        p.vendor = None
+
+    # Extract version info using semver-like parsing
+    x, y, z = parse_semver_like(t)
+    p.version_major, p.version_minor, p.version_patch = x, y, z
+    p.precision = precision_from_parts(x, y, z, None) if x else "product"
+
+    # Boost confidence based on precision
+    update_confidence(p, p.precision)
+
+    return p