pybinaryguard 1.0.0__py3-none-any.whl

pybinaryguard/rules/builtin/board_profile_rules.py

@@ -0,0 +1,282 @@
+"""Board profile-aware rules for embedded device intelligence.
+
+These rules leverage board profiles to provide targeted diagnostics for
+specific embedded hardware platforms.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from pybinaryguard.models.enums import Severity
+from pybinaryguard.models.finding import Finding
+from pybinaryguard.models.package import PackageBinaryInfo
+from pybinaryguard.models.system import SystemProfile
+from pybinaryguard.profiles import match_board_profile
+from pybinaryguard.rules.base import Rule
+
+
+class KNOWN_BROKEN_WHEEL(Rule):
+    """Detects packages known to be broken on the detected board."""
+
+    rule_id = "KNOWN_BROKEN_WHEEL"
+    description = "Checks packages against board-specific broken wheel database"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        board_profile = match_board_profile(profile)
+        return board_profile is not None
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        board_profile = match_board_profile(profile)
+        if board_profile is None:
+            return findings
+
+        for package in packages:
+            if not package.has_binaries:
+                continue
+            package_version = package.package_version or None
+            broken = board_profile.is_package_known_broken(
+                package.package_name, package_version
+            )
+            if broken:
+                findings.append(
+                    Finding(
+                        rule_id=self.rule_id,
+                        severity=Severity.CRITICAL,
+                        title=(
+                            f"{package.package_name} is known broken on "
+                            f"{board_profile.display_name}"
+                        ),
+                        explanation=(
+                            f"Package {package.package_name} version "
+                            f"{broken.versions} is incompatible with "
+                            f"{board_profile.display_name}. "
+                            f"Reason: {broken.reason}"
+                        ),
+                        package=package.package_name,
+                        suggestion=broken.recommendation,
+                        confidence=1.0,
+                    )
+                )
+        return findings
+
+
+class BOARD_INCOMPATIBLE_PACKAGE(Rule):
+    """Detects packages fundamentally incompatible with the board."""
+
+    rule_id = "BOARD_INCOMPATIBLE_PACKAGE"
+    description = "Checks for packages that cannot work on detected hardware"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        board_profile = match_board_profile(profile)
+        return board_profile is not None
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        board_profile = match_board_profile(profile)
+        if board_profile is None:
+            return findings
+
+        for package in packages:
+            if board_profile.is_package_incompatible(package.package_name):
+                findings.append(
+                    Finding(
+                        rule_id=self.rule_id,
+                        severity=Severity.CRITICAL,
+                        title=(
+                            f"{package.package_name} is incompatible with "
+                            f"{board_profile.display_name}"
+                        ),
+                        explanation=(
+                            f"Package {package.package_name} requires hardware "
+                            f"features not available on {board_profile.display_name}."
+                        ),
+                        package=package.package_name,
+                        suggestion=(
+                            f"Remove {package.package_name} or use a board "
+                            f"with required hardware features"
+                        ),
+                        confidence=1.0,
+                    )
+                )
+        return findings
+
+
+class BOARD_CUDA_VERSION_MISMATCH(Rule):
+    """Detects CUDA version exceeding board maximum."""
+
+    rule_id = "BOARD_CUDA_VERSION_MISMATCH"
+    description = "Checks if package requires CUDA version beyond board limit"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        board_profile = match_board_profile(profile)
+        return (
+            board_profile is not None
+            and board_profile.max_cuda_version is not None
+        )
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        board_profile = match_board_profile(profile)
+        if board_profile is None or board_profile.max_cuda_version is None:
+            return findings
+
+        for package in packages:
+            if not package.cuda_version:
+                continue
+            try:
+                pkg_major = int(package.cuda_version.split(".")[0])
+                board_max_major = int(
+                    board_profile.max_cuda_version.split(".")[0]
+                )
+                if pkg_major > board_max_major:
+                    findings.append(
+                        Finding(
+                            rule_id=self.rule_id,
+                            severity=Severity.CRITICAL,
+                            title=(
+                                f"{package.package_name} requires CUDA "
+                                f"{package.cuda_version}, but "
+                                f"{board_profile.display_name} max is "
+                                f"{board_profile.max_cuda_version}"
+                            ),
+                            explanation=(
+                                f"Package {package.package_name} requires "
+                                f"CUDA {package.cuda_version}, but "
+                                f"{board_profile.display_name} only supports "
+                                f"up to CUDA {board_profile.max_cuda_version}."
+                            ),
+                            package=package.package_name,
+                            suggestion=(
+                                f"Install a version of {package.package_name} "
+                                f"compatible with CUDA "
+                                f"{board_profile.max_cuda_version}"
+                            ),
+                            confidence=0.95,
+                        )
+                    )
+            except (ValueError, IndexError):
+                pass
+        return findings
+
+
+class BOARD_GLIBC_MISMATCH(Rule):
+    """Detects GLIBC mismatch against board recommendations."""
+
+    rule_id = "BOARD_GLIBC_MISMATCH"
+    description = "Checks if system GLIBC differs from board recommendation"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        board_profile = match_board_profile(profile)
+        return (
+            board_profile is not None
+            and board_profile.recommended_glibc is not None
+            and profile.glibc_version is not None
+        )
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        board_profile = match_board_profile(profile)
+        if board_profile is None or board_profile.recommended_glibc is None:
+            return findings
+
+        system_glibc = profile.glibc_version
+        if system_glibc is None:
+            return findings
+
+        recommended = board_profile.recommended_glibc
+        try:
+            rec_parts = tuple(int(x) for x in recommended.split(".")[:2])
+            if system_glibc != rec_parts:
+                findings.append(
+                    Finding(
+                        rule_id=self.rule_id,
+                        severity=Severity.WARNING,
+                        title=(
+                            f"GLIBC {system_glibc[0]}.{system_glibc[1]} "
+                            f"differs from {board_profile.display_name} "
+                            f"recommended {recommended}"
+                        ),
+                        explanation=(
+                            f"Your system has GLIBC "
+                            f"{system_glibc[0]}.{system_glibc[1]}, but "
+                            f"{board_profile.display_name} is tested with "
+                            f"GLIBC {recommended}."
+                        ),
+                        suggestion=(
+                            f"Consider using "
+                            f"{board_profile.recommended_os or 'recommended OS'} "
+                            f"which provides GLIBC {recommended}"
+                        ),
+                        confidence=0.7,
+                    )
+                )
+        except (ValueError, IndexError):
+            pass
+        return findings
+
+
+class BOARD_PYTHON_VERSION_UNSUPPORTED(Rule):
+    """Detects Python version not validated for the board."""
+
+    rule_id = "BOARD_PYTHON_VERSION_UNSUPPORTED"
+    description = "Checks if Python version is in board's validated list"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        board_profile = match_board_profile(profile)
+        return (
+            board_profile is not None
+            and len(board_profile.python_versions) > 0
+        )
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        board_profile = match_board_profile(profile)
+        if board_profile is None or not board_profile.python_versions:
+            return findings
+
+        py_version = (
+            f"{profile.python_version[0]}.{profile.python_version[1]}"
+        )
+        if py_version not in board_profile.python_versions:
+            findings.append(
+                Finding(
+                    rule_id=self.rule_id,
+                    severity=Severity.WARNING,
+                    title=(
+                        f"Python {py_version} not validated for "
+                        f"{board_profile.display_name}"
+                    ),
+                    explanation=(
+                        f"Python {py_version} has not been validated for "
+                        f"{board_profile.display_name}. Validated: "
+                        f"{', '.join(board_profile.python_versions)}"
+                    ),
+                    suggestion=(
+                        f"Use Python {board_profile.python_versions[0]} "
+                        f"for best compatibility"
+                    ),
+                    confidence=0.6,
+                )
+            )
+        return findings
+
+
+__all__ = [
+    "KNOWN_BROKEN_WHEEL",
+    "BOARD_INCOMPATIBLE_PACKAGE",
+    "BOARD_CUDA_VERSION_MISMATCH",
+    "BOARD_GLIBC_MISMATCH",
+    "BOARD_PYTHON_VERSION_UNSUPPORTED",
+]

pybinaryguard/rules/builtin/container_rules.py

@@ -0,0 +1,170 @@
+"""Container environment compatibility rules.
+
+These rules detect GPU-related misconfiguration when running inside a
+container (Docker, Podman, etc.).  Containers do not automatically get
+access to the host GPU unless explicitly configured.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from pybinaryguard.models.enums import Severity
+from pybinaryguard.models.finding import Finding
+from pybinaryguard.models.package import PackageBinaryInfo
+from pybinaryguard.models.system import SystemProfile
+from pybinaryguard.rules.base import Rule
+from pybinaryguard.rules.builtin.cuda_rules import (
+    _driver_major,
+    _is_cuda_package,
+    _max_cuda_for_driver,
+    _fmt_ver,
+)
+
+
+class ContainerNoGPUMountRule(Rule):
+    """Warns when a GPU package runs inside a container without GPU access.
+
+    Running ``docker run`` without ``--gpus all`` (or the NVIDIA Container
+    Toolkit) means the GPU is invisible to the container.  The package
+    will silently fall back to CPU or raise an error.
+    """
+
+    rule_id = "CONTAINER_NO_GPU_MOUNT"
+    description = (
+        "Warn when GPU packages run inside a container that lacks GPU "
+        "device mounts."
+    )
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        return profile.is_container and not profile.gpu_available
+
+    def evaluate(
+        self,
+        profile: SystemProfile,
+        packages: List[PackageBinaryInfo],
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        for pkg in packages:
+            if not _is_cuda_package(pkg):
+                continue
+            findings.append(
+                Finding(
+                    rule_id=self.rule_id,
+                    severity=Severity.WARNING,
+                    title=(
+                        f"{pkg.package_name} needs a GPU but none is "
+                        f"visible in this container"
+                    ),
+                    explanation=(
+                        f"You are running inside a container "
+                        f"({profile.container_runtime.value}) and package "
+                        f"{pkg.package_name} {pkg.package_version} is a "
+                        f"GPU-enabled build, but no GPU device was "
+                        f"detected inside this container.  This usually "
+                        f"means the container was started without GPU "
+                        f"passthrough."
+                    ),
+                    technical_detail=(
+                        f"Container runtime: "
+                        f"{profile.container_runtime.value}, "
+                        f"GPU visible: False"
+                    ),
+                    suggestion=(
+                        f"Run the container with GPU access:\n"
+                        f"  docker run --gpus all ...   "
+                        f"# Docker with NVIDIA Container Toolkit\n"
+                        f"  podman run --device nvidia.com/gpu=all ...  "
+                        f"# Podman with CDI\n\n"
+                        f"Make sure the NVIDIA Container Toolkit is "
+                        f"installed on the host:\n"
+                        f"  sudo apt install nvidia-container-toolkit  "
+                        f"# Debian/Ubuntu\n"
+                        f"  sudo systemctl restart docker"
+                    ),
+                    package=pkg.package_name,
+                    package_version=pkg.package_version,
+                )
+            )
+        return findings
+
+
+class ContainerDriverMismatchRule(Rule):
+    """Warns when the container's CUDA may exceed the host driver capability.
+
+    Inside a container the CUDA toolkit version can be newer than what
+    the host GPU driver supports.  The container shares the host's
+    kernel-mode driver, so if the driver is too old, CUDA calls will
+    fail.
+    """
+
+    rule_id = "CONTAINER_DRIVER_MISMATCH"
+    description = (
+        "Check that the container's CUDA version does not exceed the "
+        "host driver's capability."
+    )
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        return (
+            profile.is_container
+            and profile.gpu_available
+            and profile.gpu_driver_version is not None
+            and profile.cuda_runtime_version is not None
+        )
+
+    def evaluate(
+        self,
+        profile: SystemProfile,
+        packages: List[PackageBinaryInfo],
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        if (
+            profile.gpu_driver_version is None
+            or profile.cuda_runtime_version is None
+        ):
+            return findings
+
+        drv_major = _driver_major(profile.gpu_driver_version)
+        if drv_major is None:
+            return findings
+
+        max_cuda = _max_cuda_for_driver(drv_major)
+        if max_cuda is None:
+            return findings
+
+        cuda_rt = profile.cuda_runtime_version
+        if cuda_rt <= max_cuda:
+            return findings
+
+        findings.append(
+            Finding(
+                rule_id=self.rule_id,
+                severity=Severity.WARNING,
+                title=(
+                    "Container CUDA version exceeds host driver capability"
+                ),
+                explanation=(
+                    f"This container has CUDA {_fmt_ver(cuda_rt)} "
+                    f"installed, but the host's NVIDIA driver "
+                    f"({profile.gpu_driver_version}) only supports CUDA "
+                    f"up to {_fmt_ver(max_cuda)}.  Because the container "
+                    f"shares the host's kernel-mode GPU driver, CUDA "
+                    f"calls will fail even though the CUDA toolkit is "
+                    f"installed inside the container."
+                ),
+                technical_detail=(
+                    f"Container CUDA: {_fmt_ver(cuda_rt)}, "
+                    f"Host driver: {profile.gpu_driver_version}, "
+                    f"Max CUDA for driver: {_fmt_ver(max_cuda)}"
+                ),
+                suggestion=(
+                    f"Option 1 -- upgrade the GPU driver on the host to "
+                    f"one that supports CUDA {_fmt_ver(cuda_rt)}.\n\n"
+                    f"Option 2 -- use a container image with CUDA <= "
+                    f"{_fmt_ver(max_cuda)}:\n"
+                    f"  docker run --gpus all nvidia/cuda:"
+                    f"{_fmt_ver(max_cuda)}-runtime-ubuntu22.04"
+                ),
+            )
+        )
+        return findings

pybinaryguard/rules/builtin/cpu_rules.py

@@ -0,0 +1,204 @@
+"""CPU instruction-set rules.
+
+These rules detect packages that require advanced CPU instruction sets
+(AVX, AVX2, AVX-512, etc.) which may not be available on the host.  Running
+such a package on an unsupported CPU triggers a ``SIGILL``
+(illegal instruction) signal, causing the process to crash instantly without
+a meaningful Python traceback.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Set
+
+from pybinaryguard.models.enums import Severity
+from pybinaryguard.models.finding import Finding
+from pybinaryguard.models.package import PackageBinaryInfo
+from pybinaryguard.models.system import SystemProfile
+from pybinaryguard.rules.base import Rule
+
+# Mapping of well-known packages to the instruction sets they are known
+# to require.  An empty set means the package *may* use advanced
+# instructions but does not always require them (build-dependent).
+KNOWN_INSTRUCTION_REQUIREMENTS: Dict[str, Set[str]] = {
+    "tensorflow": {"avx"},
+    "tensorflow-cpu": {"avx"},
+    "tensorflow-gpu": {"avx"},
+    "numpy": set(),  # modern numpy may need AVX2 on some builds
+    "faiss-cpu": {"avx2"},
+    "faiss-gpu": {"avx2"},
+    "pytorch": set(),
+    "torch": set(),
+    "scipy": set(),
+    "scikit-learn": set(),
+    "xgboost": set(),
+    "lightgbm": set(),
+    "onnxruntime": {"avx"},
+    "onnxruntime-gpu": {"avx"},
+}
+
+_INSTRUCTION_FRIENDLY_NAMES: Dict[str, str] = {
+    "avx": "AVX (Advanced Vector Extensions)",
+    "avx2": "AVX2 (Advanced Vector Extensions 2)",
+    "avx512": "AVX-512",
+    "sse42": "SSE 4.2",
+    "neon": "ARM NEON",
+}
+
+
+def _system_has_instruction(profile: SystemProfile, instruction: str) -> bool:
+    """Check whether the system supports the given instruction set."""
+    mapping: Dict[str, bool] = {
+        "avx": profile.has_avx,
+        "avx2": profile.has_avx2,
+        "avx512": profile.has_avx512,
+        "sse42": profile.has_sse42,
+        "neon": profile.has_neon,
+    }
+    return mapping.get(instruction, False)
+
+
+class AVX2RequiredRule(Rule):
+    """Detects packages that require AVX2 on a CPU without it.
+
+    AVX2 is commonly used in high-performance numerical libraries to
+    speed up vector and matrix operations.  Older or low-power CPUs
+    (virtual machines on older hosts, Atom processors, etc.) may lack
+    AVX2 support.
+    """
+
+    rule_id = "AVX2_REQUIRED"
+    description = (
+        "Flag packages that require AVX2 when the host CPU lacks it."
+    )
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        """Skip if the system already has AVX2."""
+        return not profile.has_avx2
+
+    def evaluate(
+        self,
+        profile: SystemProfile,
+        packages: List[PackageBinaryInfo],
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        for pkg in packages:
+            pkg_lower = pkg.package_name.lower()
+            requirements = KNOWN_INSTRUCTION_REQUIREMENTS.get(pkg_lower)
+            if requirements is None:
+                continue
+            if "avx2" not in requirements:
+                continue
+            findings.append(
+                Finding(
+                    rule_id=self.rule_id,
+                    severity=Severity.CRITICAL,
+                    title=(
+                        f"{pkg.package_name} requires AVX2 instructions"
+                    ),
+                    explanation=(
+                        f"Package {pkg.package_name} "
+                        f"{pkg.package_version} is known to require "
+                        f"AVX2 (Advanced Vector Extensions 2) CPU "
+                        f"instructions, but your CPU ({profile.cpu_model or 'unknown'}) "
+                        f"does not support AVX2.  When the package tries "
+                        f"to execute an AVX2 instruction your process "
+                        f"will be killed by an 'Illegal instruction' "
+                        f"signal (SIGILL) with no Python traceback."
+                    ),
+                    technical_detail=(
+                        f"CPU model: {profile.cpu_model or 'unknown'}, "
+                        f"has_avx2: False"
+                    ),
+                    suggestion=(
+                        f"Option 1 -- look for a build that does not "
+                        f"require AVX2 (some packages publish 'noavx' "
+                        f"variants).\n\n"
+                        f"Option 2 -- use conda-forge, which often provides "
+                        f"builds for older CPUs:\n"
+                        f"  conda install -c conda-forge "
+                        f"{pkg.package_name}\n\n"
+                        f"Option 3 -- build from source with AVX2 "
+                        f"disabled (if the package supports it)."
+                    ),
+                    package=pkg.package_name,
+                    package_version=pkg.package_version,
+                    confidence=0.9,
+                )
+            )
+        return findings
+
+
+class IllegalInstructionRiskRule(Rule):
+    """General check for packages that may trigger SIGILL.
+
+    Consults the ``KNOWN_INSTRUCTION_REQUIREMENTS`` table to determine
+    whether the host CPU provides all instruction sets a package needs.
+    """
+
+    rule_id = "ILLEGAL_INSTRUCTION_RISK"
+    description = (
+        "Detect packages whose instruction-set requirements may not "
+        "be met by the host CPU."
+    )
+
+    def evaluate(
+        self,
+        profile: SystemProfile,
+        packages: List[PackageBinaryInfo],
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        for pkg in packages:
+            pkg_lower = pkg.package_name.lower()
+            requirements = KNOWN_INSTRUCTION_REQUIREMENTS.get(pkg_lower)
+            if requirements is None:
+                continue
+            missing: List[str] = []
+            for instr in sorted(requirements):
+                if not _system_has_instruction(profile, instr):
+                    missing.append(instr)
+            if not missing:
+                continue
+            friendly = ", ".join(
+                _INSTRUCTION_FRIENDLY_NAMES.get(m, m.upper()) for m in missing
+            )
+            findings.append(
+                Finding(
+                    rule_id=self.rule_id,
+                    severity=Severity.CRITICAL,
+                    title=(
+                        f"{pkg.package_name} may crash with "
+                        f"'Illegal instruction'"
+                    ),
+                    explanation=(
+                        f"Package {pkg.package_name} "
+                        f"{pkg.package_version} is known to require "
+                        f"the following CPU instruction set(s): "
+                        f"{friendly}.  Your CPU "
+                        f"({profile.cpu_model or 'unknown'}) does not "
+                        f"support {'them' if len(missing) > 1 else 'it'}.  "
+                        f"This will cause the process to be killed with "
+                        f"a SIGILL (Illegal instruction) signal the "
+                        f"moment the package tries to use the missing "
+                        f"instruction."
+                    ),
+                    technical_detail=(
+                        f"Missing instructions: {', '.join(missing)}, "
+                        f"CPU model: {profile.cpu_model or 'unknown'}, "
+                        f"CPU flags: {', '.join(sorted(profile.cpu_flags)) if profile.cpu_flags else 'unknown'}"
+                    ),
+                    suggestion=(
+                        f"Option 1 -- install an alternative build that "
+                        f"does not require {friendly}.\n\n"
+                        f"Option 2 -- use conda-forge:\n"
+                        f"  conda install -c conda-forge "
+                        f"{pkg.package_name}\n\n"
+                        f"Option 3 -- run inside a VM or container on "
+                        f"hardware that supports these instructions."
+                    ),
+                    package=pkg.package_name,
+                    package_version=pkg.package_version,
+                    confidence=0.85,
+                )
+            )
+        return findings