pybinaryguard 1.0.0__py3-none-any.whl

pybinaryguard/probes/os_probe.py

@@ -0,0 +1,227 @@
+"""Probe for OS, kernel, and virtualisation environment information."""
+
+from __future__ import annotations
+
+import os
+import platform
+from typing import Any, Dict, Optional
+
+from pybinaryguard.models.enums import ContainerRuntime
+
+from .base import ProbeBase
+
+
+class OsProbe(ProbeBase):
+    """Collects operating-system and runtime-environment metadata.
+
+    - Distro name and version from ``/etc/os-release``.
+    - Kernel version from ``platform.release()``.
+    - Container detection: ``/.dockerenv``, ``/proc/1/cgroup``, env vars.
+    - VM detection: ``/sys/class/dmi/id/`` sysfs entries.
+    """
+
+    name = "os"
+
+    def collect(self) -> Dict[str, Any]:
+        """Return OS, kernel, container, and VM information."""
+        data: Dict[str, Any] = {}
+
+        os_info = self._parse_os_release()
+        data["os_name"] = os_info.get("name", "")
+        data["os_version"] = os_info.get("version_id", os_info.get("version", ""))
+        data["kernel_version"] = self._get_kernel_version()
+
+        container_info = self._detect_container()
+        data["is_container"] = container_info[0]
+        data["container_runtime"] = container_info[1]
+
+        data["is_virtual_machine"] = self._detect_vm()
+
+        return data
+
+    # ------------------------------------------------------------------
+    # OS release
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _parse_os_release() -> Dict[str, str]:
+        """Parse ``/etc/os-release`` (or ``/usr/lib/os-release`` fallback).
+
+        Returns a dictionary with keys lower-cased.  Values are unquoted.
+        """
+        for path in ("/etc/os-release", "/usr/lib/os-release"):
+            try:
+                with open(path, "r") as fh:
+                    return OsProbe._parse_release_file(fh.read())
+            except (FileNotFoundError, PermissionError, OSError):
+                continue
+        return {}
+
+    @staticmethod
+    def _parse_release_file(text: str) -> Dict[str, str]:
+        """Parse key=value pairs from an os-release style file."""
+        result: Dict[str, str] = {}
+        for line in text.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if "=" not in line:
+                continue
+            key, _, value = line.partition("=")
+            key = key.strip().lower()
+            value = value.strip()
+            # Remove surrounding quotes (single or double)
+            if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+                value = value[1:-1]
+            result[key] = value
+        return result
+
+    @staticmethod
+    def _get_kernel_version() -> str:
+        """Return the kernel version string."""
+        try:
+            return platform.release()
+        except Exception:
+            return ""
+
+    # ------------------------------------------------------------------
+    # Container detection
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _detect_container() -> tuple:  # type: ignore[type-arg]
+        """Detect whether we are running inside a container.
+
+        Returns ``(is_container: bool, runtime: ContainerRuntime)``.
+        """
+        # Check /.dockerenv -- Docker creates this file
+        if os.path.exists("/.dockerenv"):
+            return (True, ContainerRuntime.DOCKER)
+
+        # Check for Podman-specific environment variable
+        if os.environ.get("container") == "podman":
+            return (True, ContainerRuntime.PODMAN)
+
+        # Check environment hints
+        if os.environ.get("container") == "lxc":
+            return (True, ContainerRuntime.LXC)
+
+        # Check /run/.containerenv (Podman)
+        if os.path.exists("/run/.containerenv"):
+            return (True, ContainerRuntime.PODMAN)
+
+        # Check /proc/1/cgroup for container signals
+        runtime = OsProbe._detect_container_from_cgroup()
+        if runtime is not None:
+            return (True, runtime)
+
+        # Check /proc/1/environ for container_runtime (requires root)
+        runtime = OsProbe._detect_container_from_mountinfo()
+        if runtime is not None:
+            return (True, runtime)
+
+        return (False, ContainerRuntime.NONE)
+
+    @staticmethod
+    def _detect_container_from_cgroup() -> Optional[ContainerRuntime]:
+        """Inspect ``/proc/1/cgroup`` for container runtime indicators.
+
+        Docker cgroups contain ``/docker/``, containerd uses
+        ``/cri-containerd-``, and LXC uses ``/lxc/``.
+        """
+        try:
+            with open("/proc/1/cgroup", "r") as fh:
+                content = fh.read()
+        except (FileNotFoundError, PermissionError, OSError):
+            return None
+
+        if "/docker/" in content or "/docker-" in content:
+            return ContainerRuntime.DOCKER
+        if "/lxc/" in content:
+            return ContainerRuntime.LXC
+        if "containerd" in content or "/cri-containerd-" in content:
+            return ContainerRuntime.CONTAINERD
+        if "/kubepods" in content:
+            # Kubernetes pods -- usually containerd or Docker underneath
+            return ContainerRuntime.CONTAINERD
+
+        return None
+
+    @staticmethod
+    def _detect_container_from_mountinfo() -> Optional[ContainerRuntime]:
+        """Inspect ``/proc/1/mountinfo`` for overlay filesystems.
+
+        Container runtimes typically mount an overlay root filesystem.
+        """
+        try:
+            with open("/proc/1/mountinfo", "r") as fh:
+                content = fh.read()
+        except (FileNotFoundError, PermissionError, OSError):
+            return None
+
+        if "overlay" in content and ("docker" in content or "containerd" in content):
+            if "docker" in content:
+                return ContainerRuntime.DOCKER
+            return ContainerRuntime.CONTAINERD
+
+        return None
+
+    # ------------------------------------------------------------------
+    # VM detection
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _detect_vm() -> bool:
+        """Detect whether the system is running inside a virtual machine.
+
+        Reads DMI/SMBIOS information from ``/sys/class/dmi/id/`` and
+        checks for known hypervisor product names.
+        """
+        vm_indicators = {
+            "vmware",
+            "virtualbox",
+            "vbox",
+            "kvm",
+            "qemu",
+            "xen",
+            "hyper-v",
+            "microsoft corporation",
+            "parallels",
+            "bochs",
+            "bhyve",
+            "amazon ec2",
+            "google compute engine",
+            "openstack",
+            "nutanix",
+        }
+
+        dmi_files = [
+            "/sys/class/dmi/id/product_name",
+            "/sys/class/dmi/id/sys_vendor",
+            "/sys/class/dmi/id/board_vendor",
+            "/sys/class/dmi/id/bios_vendor",
+            "/sys/class/dmi/id/chassis_vendor",
+        ]
+
+        for dmi_path in dmi_files:
+            try:
+                with open(dmi_path, "r") as fh:
+                    value = fh.read().strip().lower()
+                for indicator in vm_indicators:
+                    if indicator in value:
+                        return True
+            except (FileNotFoundError, PermissionError, OSError):
+                continue
+
+        # Fallback: check /proc/cpuinfo for hypervisor flag
+        try:
+            with open("/proc/cpuinfo", "r") as fh:
+                for line in fh:
+                    if line.strip().lower().startswith("flags"):
+                        if "hypervisor" in line.lower():
+                            return True
+                        break
+        except (FileNotFoundError, PermissionError, OSError):
+            pass
+
+        return False

pybinaryguard/probes/python_probe.py

@@ -0,0 +1,135 @@
+"""Probe for Python interpreter information."""
+
+from __future__ import annotations
+
+import sys
+import sysconfig
+from typing import Any, Dict, Tuple
+
+from .base import ProbeBase
+
+
+class PythonProbe(ProbeBase):
+    """Collects information about the running Python interpreter.
+
+    Gathered fields:
+    - ``python_version``: 3-tuple of (major, minor, micro)
+    - ``python_abi_tag``: e.g. ``"cp312-cp312-linux_x86_64"``
+    - ``python_implementation``: e.g. ``"cpython"``, ``"pypy"``
+    - ``python_executable``: absolute path to the interpreter
+    - ``stable_abi_supported``: whether the stable ABI (abi3) is supported
+    - ``python_debug_build``: whether this is a debug build
+    """
+
+    name = "python"
+
+    def collect(self) -> Dict[str, Any]:
+        """Collect Python interpreter details using only stdlib modules."""
+        data: Dict[str, Any] = {}
+
+        data["python_version"] = self._get_version()
+        data["python_abi_tag"] = self._get_abi_tag()
+        data["python_implementation"] = self._get_implementation()
+        data["python_executable"] = self._get_executable()
+        data["stable_abi_supported"] = self._check_stable_abi()
+        data["python_debug_build"] = self._check_debug_build()
+
+        return data
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _get_version() -> Tuple[int, int, int]:
+        """Return the Python version as a (major, minor, micro) tuple."""
+        try:
+            return (sys.version_info.major, sys.version_info.minor, sys.version_info.micro)
+        except Exception:
+            return (0, 0, 0)
+
+    @staticmethod
+    def _get_abi_tag() -> str:
+        """Build the ABI tag from sysconfig variables.
+
+        Falls back to a constructed tag from ``sys.implementation`` when
+        sysconfig does not provide ``SOABI``.
+        """
+        try:
+            soabi = sysconfig.get_config_var("SOABI")
+            if soabi:
+                return str(soabi)
+
+            # Fallback: build from implementation info
+            impl = sys.implementation.name[0:2]  # "cp" for cpython
+            ver = f"{sys.version_info.major}{sys.version_info.minor}"
+            tag = f"{impl}{ver}"
+
+            # Append debug/unicode suffixes for older Python builds
+            abiflags = sysconfig.get_config_var("abiflags") or ""
+            if abiflags:
+                tag += abiflags
+
+            return tag
+        except Exception:
+            return ""
+
+    @staticmethod
+    def _get_implementation() -> str:
+        """Return a normalised implementation name (lowercase)."""
+        try:
+            return sys.implementation.name.lower()
+        except Exception:
+            return "cpython"
+
+    @staticmethod
+    def _get_executable() -> str:
+        """Return the absolute path to the Python executable."""
+        try:
+            return sys.executable or ""
+        except Exception:
+            return ""
+
+    @staticmethod
+    def _check_stable_abi() -> bool:
+        """Determine whether the stable ABI (abi3) is supported.
+
+        The stable ABI was introduced in CPython 3.2.  For other
+        implementations it is generally not available.
+        """
+        try:
+            if sys.implementation.name.lower() != "cpython":
+                return False
+            return sys.version_info >= (3, 2)
+        except Exception:
+            return False
+
+    @staticmethod
+    def _check_debug_build() -> bool:
+        """Detect whether the interpreter was compiled in debug mode.
+
+        Checks multiple indicators:
+        1. ``sys.flags.debug``
+        2. ``Py_DEBUG`` sysconfig variable
+        3. ``abiflags`` containing ``"d"``
+        4. Pointer size heuristic (debug builds often have larger objects)
+           -- this is a weak signal and is used only as a last resort.
+        """
+        try:
+            # Primary: interpreter flag
+            if sys.flags.debug:
+                return True
+
+            # Secondary: sysconfig variable
+            py_debug = sysconfig.get_config_var("Py_DEBUG")
+            if py_debug and int(py_debug):
+                return True
+
+            # Tertiary: abiflags
+            abiflags = sysconfig.get_config_var("abiflags") or ""
+            if "d" in abiflags:
+                return True
+
+            return False
+        except Exception:
+            return False

pybinaryguard/probes/toolchain_probe.py

@@ -0,0 +1,89 @@
+"""Build toolchain probe — detects compilers and build tools on the system."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from typing import Any, Dict, Optional, Tuple
+
+from .base import ProbeBase
+
+
+class ToolchainProbe(ProbeBase):
+    """Detect available build toolchain (gcc, g++, cmake, make, rustc, etc.).
+
+    This is critical for detecting packages built from source (sdist)
+    and validating that the compiler used is compatible with system binaries.
+    """
+
+    name = "toolchain"
+
+    def collect(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = {}
+
+        gcc = self._detect_tool("gcc", r"(\d+\.\d+\.\d+)")
+        gpp = self._detect_tool("g++", r"(\d+\.\d+\.\d+)")
+        clang = self._detect_tool("clang", r"(\d+\.\d+\.\d+)")
+        cmake = self._detect_tool("cmake", r"(\d+\.\d+\.\d+)")
+        make = self._detect_tool("make", r"(\d+\.\d+)")
+        rustc = self._detect_tool("rustc", r"(\d+\.\d+\.\d+)")
+
+        toolchain: Dict[str, Optional[str]] = {
+            "gcc": gcc,
+            "gpp": gpp,
+            "clang": clang,
+            "cmake": cmake,
+            "make": make,
+            "rustc": rustc,
+        }
+
+        data["toolchain_versions"] = {
+            k: v for k, v in toolchain.items() if v is not None
+        }
+
+        # Detect the default C compiler
+        cc = os.environ.get("CC", "")
+        cxx = os.environ.get("CXX", "")
+        data["default_cc"] = cc if cc else ("gcc" if gcc else "clang" if clang else "")
+        data["default_cxx"] = cxx if cxx else ("g++" if gpp else "clang++" if clang else "")
+
+        # Check if build-essential / dev headers are available
+        data["has_build_tools"] = gcc is not None or clang is not None
+        data["has_python_dev_headers"] = self._has_python_headers()
+
+        return data
+
+    @staticmethod
+    def _detect_tool(tool: str, version_pattern: str) -> Optional[str]:
+        """Run ``tool --version`` and extract version string."""
+        path = shutil.which(tool)
+        if not path:
+            return None
+        try:
+            result = subprocess.run(
+                [path, "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            output = result.stdout + result.stderr
+            match = re.search(version_pattern, output)
+            if match:
+                return match.group(1)
+            return "unknown"
+        except (subprocess.TimeoutExpired, OSError):
+            return None
+
+    @staticmethod
+    def _has_python_headers() -> bool:
+        """Check if Python development headers are installed."""
+        try:
+            import sysconfig
+            include_dir = sysconfig.get_path("include")
+            if include_dir and os.path.isfile(os.path.join(include_dir, "Python.h")):
+                return True
+        except Exception:
+            pass
+        return False

pybinaryguard/probes/venv_probe.py

@@ -0,0 +1,111 @@
+"""Virtual environment probe — detects venv type and configuration."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, Dict
+
+
+from .base import ProbeBase
+
+
+class VenvProbe(ProbeBase):
+    """Detect virtual environment type and configuration.
+
+    Identifies whether running in venv, conda, virtualenv, poetry, pdm,
+    pipenv, or system Python. Also detects common misconfigurations.
+    """
+
+    name = "venv"
+
+    def collect(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = {}
+
+        venv_type = self._detect_venv_type()
+        data["venv_type"] = venv_type
+        data["is_system_python"] = venv_type == "system"
+        data["is_virtual_env"] = venv_type != "system"
+
+        # Base prefix vs prefix (tells us if we're in a venv)
+        data["base_prefix"] = getattr(sys, "base_prefix", sys.prefix)
+        data["prefix"] = sys.prefix
+
+        # Detect conda-specific info
+        if venv_type == "conda":
+            data["conda_env_name"] = os.environ.get("CONDA_DEFAULT_ENV", "")
+            data["conda_prefix"] = os.environ.get("CONDA_PREFIX", "")
+
+        # Check for common misconfigurations
+        data["pip_user_site_enabled"] = self._pip_user_site_active()
+        data["mixed_env_risk"] = self._detect_mixed_env()
+
+        return data
+
+    @staticmethod
+    def _detect_venv_type() -> str:
+        """Identify the virtual environment manager in use."""
+        # Conda
+        if os.environ.get("CONDA_DEFAULT_ENV") or os.environ.get("CONDA_PREFIX"):
+            return "conda"
+
+        # Poetry
+        if os.environ.get("POETRY_ACTIVE") == "1":
+            return "poetry"
+
+        # Pipenv
+        if os.environ.get("PIPENV_ACTIVE") == "1":
+            return "pipenv"
+
+        # PDM
+        if os.environ.get("PDM_IN_VENV"):
+            return "pdm"
+
+        # Standard venv / virtualenv
+        real_prefix = getattr(sys, "real_prefix", None)  # virtualenv sets this
+        base_prefix = getattr(sys, "base_prefix", sys.prefix)
+
+        if real_prefix is not None:
+            return "virtualenv"
+
+        if base_prefix != sys.prefix:
+            # Check for pyvenv.cfg to distinguish venv from virtualenv
+            cfg = os.path.join(sys.prefix, "pyvenv.cfg")
+            if os.path.isfile(cfg):
+                return "venv"
+            return "virtualenv"
+
+        return "system"
+
+    @staticmethod
+    def _pip_user_site_active() -> bool:
+        """Check if pip user-site installs are leaking into the env."""
+        try:
+            import site
+            user_site = getattr(site, "getusersitepackages", lambda: None)()
+            if user_site and os.path.isdir(user_site):
+                # Check if user site is in sys.path
+                return user_site in sys.path
+        except Exception:
+            pass
+        return False
+
+    @staticmethod
+    def _detect_mixed_env() -> bool:
+        """Detect if packages from multiple environments are on sys.path.
+
+        This happens when system packages leak into a venv or vice versa.
+        """
+        site_packages_dirs = [
+            p for p in sys.path if "site-packages" in p or "dist-packages" in p
+        ]
+        # If there are multiple distinct site-packages roots, it's mixed
+        prefixes = set()
+        for sp in site_packages_dirs:
+            # Get the env root (two levels up from site-packages)
+            parts = sp.split(os.sep)
+            for i, part in enumerate(parts):
+                if part in ("site-packages", "dist-packages") and i >= 2:
+                    prefixes.add(os.sep.join(parts[:i - 1]))
+                    break
+        return len(prefixes) > 1

pybinaryguard/profiles/__init__.py

@@ -0,0 +1,12 @@
+"""Board profile system for embedded device intelligence."""
+
+from __future__ import annotations
+
+from .engine import BoardProfile, ProfileEngine, load_profile, match_board_profile
+
+__all__ = [
+    "BoardProfile",
+    "ProfileEngine",
+    "load_profile",
+    "match_board_profile",
+]