pybinaryguard 1.0.0__py3-none-any.whl

pybinaryguard/rules/builtin/python_abi_rules.py

@@ -0,0 +1,259 @@
+"""Python ABI and version compatibility rules.
+
+These rules detect mismatches between the Python interpreter running on the
+host and the Python ABI / version that installed binary packages were built
+for.  Such mismatches typically result in ``ImportError`` or segfaults at
+import time.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Tuple
+
+from pybinaryguard.models.enums import Severity
+from pybinaryguard.models.finding import Finding
+from pybinaryguard.models.package import PackageBinaryInfo, WheelTag
+from pybinaryguard.models.system import SystemProfile
+from pybinaryguard.rules.base import Rule
+
+
+def _extract_interpreter_version(tag: str) -> Optional[Tuple[int, int]]:
+    """Extract (major, minor) from an interpreter tag like ``'cp312'``.
+
+    Returns ``None`` if the tag cannot be parsed.
+    """
+    match = re.match(r"^(?:cp|pp|ip|jy)(\d)(\d+)$", tag)
+    if match:
+        return (int(match.group(1)), int(match.group(2)))
+    return None
+
+
+def _system_interpreter_tag(profile: SystemProfile) -> str:
+    """Derive the expected CPython interpreter tag from the system profile.
+
+    For CPython 3.12 this is ``'cp312'``.
+    """
+    major, minor = profile.python_version[0], profile.python_version[1]
+    return f"cp{major}{minor}"
+
+
+class PythonABIMismatchRule(Rule):
+    """Detects packages built for a different CPython ABI tag.
+
+    A CPython extension module is compiled against a specific C API and
+    ABI, identified by a tag like ``cp312``.  Loading an extension built
+    for ``cp310`` into a ``cp312`` interpreter may segfault or raise an
+    ``ImportError`` because the internal struct layouts differ.
+    """
+
+    rule_id = "PYTHON_ABI_MISMATCH"
+    description = (
+        "Check that each package's wheel ABI tag matches the running "
+        "Python interpreter's ABI."
+    )
+
+    def evaluate(
+        self,
+        profile: SystemProfile,
+        packages: List[PackageBinaryInfo],
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        if not profile.python_abi_tag:
+            return findings
+
+        sys_abi = profile.python_abi_tag  # e.g. "cp312"
+
+        for pkg in packages:
+            if pkg.is_pure_python or not pkg.wheel_tags:
+                continue
+            for tag in pkg.wheel_tags:
+                # Skip universal tags that work on any interpreter.
+                if tag.abi in ("none", "abi3"):
+                    continue
+                if tag.abi != sys_abi:
+                    findings.append(
+                        Finding(
+                            rule_id=self.rule_id,
+                            severity=Severity.CRITICAL,
+                            title=(
+                                f"{pkg.package_name} was built for a "
+                                f"different Python ABI"
+                            ),
+                            explanation=(
+                                f"Package {pkg.package_name} "
+                                f"{pkg.package_version} was compiled for "
+                                f"the '{tag.abi}' ABI but your Python "
+                                f"interpreter uses '{sys_abi}'.  Compiled "
+                                f"extensions are not interchangeable between "
+                                f"Python ABI versions because internal data "
+                                f"structures change.  Importing this package "
+                                f"will raise an ImportError or cause a "
+                                f"segmentation fault."
+                            ),
+                            technical_detail=(
+                                f"Wheel ABI tag: {tag.abi}, "
+                                f"System ABI tag: {sys_abi}"
+                            ),
+                            suggestion=(
+                                f"Reinstall the package so pip fetches the "
+                                f"correct wheel for your interpreter:\n"
+                                f"  pip install --force-reinstall "
+                                f"{pkg.package_name}=={pkg.package_version}"
+                            ),
+                            package=pkg.package_name,
+                            package_version=pkg.package_version,
+                        )
+                    )
+                    # One finding per package is enough.
+                    break
+        return findings
+
+
+class PythonVersionMismatchRule(Rule):
+    """Detects packages whose interpreter tag targets a different Python.
+
+    Even without a strict ABI mismatch, a wheel tagged ``cp310`` that is
+    loaded into Python 3.12 is suspect.  This rule checks the interpreter
+    field of wheel tags against the running Python version.
+    """
+
+    rule_id = "PYTHON_VERSION_MISMATCH"
+    description = (
+        "Check that each package's wheel interpreter tag matches the "
+        "running Python version."
+    )
+
+    def evaluate(
+        self,
+        profile: SystemProfile,
+        packages: List[PackageBinaryInfo],
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        sys_tag = _system_interpreter_tag(profile)
+        sys_ver = (profile.python_version[0], profile.python_version[1])
+
+        for pkg in packages:
+            if pkg.is_pure_python or not pkg.wheel_tags:
+                continue
+            for tag in pkg.wheel_tags:
+                # Universal / stable-ABI wheels work everywhere.
+                if tag.interpreter in ("py3", "py2.py3"):
+                    continue
+                if tag.abi == "abi3":
+                    continue
+                wheel_ver = _extract_interpreter_version(tag.interpreter)
+                if wheel_ver is None:
+                    continue
+                if wheel_ver != sys_ver:
+                    findings.append(
+                        Finding(
+                            rule_id=self.rule_id,
+                            severity=Severity.CRITICAL,
+                            title=(
+                                f"{pkg.package_name} targets Python "
+                                f"{wheel_ver[0]}.{wheel_ver[1]}"
+                            ),
+                            explanation=(
+                                f"Package {pkg.package_name} "
+                                f"{pkg.package_version} was built for "
+                                f"Python {wheel_ver[0]}.{wheel_ver[1]} "
+                                f"(tag '{tag.interpreter}') but you are "
+                                f"running Python {sys_ver[0]}.{sys_ver[1]}.  "
+                                f"CPython compiled extensions are version-"
+                                f"specific and cannot be shared across "
+                                f"different Python minor versions."
+                            ),
+                            technical_detail=(
+                                f"Wheel interpreter tag: {tag.interpreter}, "
+                                f"System Python: {sys_tag}"
+                            ),
+                            suggestion=(
+                                f"Reinstall with the correct Python version:\n"
+                                f"  pip install --force-reinstall "
+                                f"{pkg.package_name}=={pkg.package_version}\n\n"
+                                f"If you need a specific Python version, "
+                                f"create a virtual environment:\n"
+                                f"  python{wheel_ver[0]}.{wheel_ver[1]} -m "
+                                f"venv .venv && source .venv/bin/activate"
+                            ),
+                            package=pkg.package_name,
+                            package_version=pkg.package_version,
+                        )
+                    )
+                    break
+        return findings
+
+
+class DebugReleaseMixRule(Rule):
+    """Detects mixing debug and release Python builds.
+
+    CPython can be compiled with ``--with-pydebug``, which changes the
+    sizes of internal objects (adding ref-count fields, etc.).  Loading a
+    release-mode extension into a debug interpreter -- or vice versa --
+    will corrupt memory and is likely to segfault.
+    """
+
+    rule_id = "DEBUG_RELEASE_MIX"
+    description = (
+        "Warn when the Python build type (debug/release) does not match "
+        "the installed extensions."
+    )
+
+    def evaluate(
+        self,
+        profile: SystemProfile,
+        packages: List[PackageBinaryInfo],
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+        if not profile.python_debug_build:
+            # Release builds are the common case; extensions are almost
+            # always built in release mode so there is nothing to flag.
+            return findings
+
+        for pkg in packages:
+            if pkg.is_pure_python or not pkg.wheel_tags:
+                continue
+            for tag in pkg.wheel_tags:
+                # A debug-built Python uses an ABI tag ending with 'd'
+                # (e.g. "cp312d").  If the wheel's abi tag does NOT end
+                # with 'd', it is a release wheel.
+                if tag.abi in ("none", "abi3"):
+                    continue
+                if not tag.abi.endswith("d"):
+                    findings.append(
+                        Finding(
+                            rule_id=self.rule_id,
+                            severity=Severity.WARNING,
+                            title=(
+                                f"{pkg.package_name} is a release build "
+                                f"on a debug interpreter"
+                            ),
+                            explanation=(
+                                f"Your Python interpreter was compiled "
+                                f"with --with-pydebug (debug build), but "
+                                f"{pkg.package_name} {pkg.package_version} "
+                                f"is a release-mode extension (ABI tag "
+                                f"'{tag.abi}').  Debug and release builds "
+                                f"use different internal struct layouts, so "
+                                f"mixing them can cause crashes or "
+                                f"memory corruption."
+                            ),
+                            technical_detail=(
+                                f"System: debug build, "
+                                f"Wheel ABI: {tag.abi} (release)"
+                            ),
+                            suggestion=(
+                                f"Either rebuild the package from source "
+                                f"under your debug Python:\n"
+                                f"  pip install --no-binary :all: "
+                                f"{pkg.package_name}\n\n"
+                                f"Or switch to a release build of Python for "
+                                f"production workloads."
+                            ),
+                            package=pkg.package_name,
+                            package_version=pkg.package_version,
+                        )
+                    )
+                    break
+        return findings

pybinaryguard/rules/builtin/source_build_rules.py

@@ -0,0 +1,150 @@
+"""Source build detection rules.
+
+Detects packages built from source (sdist) rather than prebuilt wheels,
+and validates compiler compatibility. This addresses the blind spot that
+neither pip nor Poetry catches — build-time ABI issues.
+"""
+
+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.rules.base import Rule
+
+
+class SourceBuildDetectionRule(Rule):
+    """Detect packages that were compiled from source on this machine.
+
+    Packages built from sdist may have been compiled with a different
+    compiler version or flags than expected, leading to ABI issues.
+    """
+
+    rule_id = "SOURCE_BUILD_DETECTED"
+    description = "Detect packages built from source distribution"
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+
+        for pkg in packages:
+            if pkg.is_pure_python:
+                continue
+            if not pkg.has_binaries:
+                continue
+
+            # If package has .so files but NO wheel tags, it was built from source
+            if not pkg.wheel_tags:
+                findings.append(Finding(
+                    rule_id=self.rule_id,
+                    severity=Severity.INFO,
+                    title=f"{pkg.package_name} was built from source",
+                    explanation=(
+                        f"{pkg.package_name}=={pkg.package_version} has compiled "
+                        f"extensions but no wheel tags, indicating it was installed "
+                        f"from an sdist (source distribution) rather than a prebuilt "
+                        f"wheel. Source builds may have ABI issues if the compiler "
+                        f"or flags differ from what the package authors tested."
+                    ),
+                    package=pkg.package_name,
+                    package_version=pkg.package_version,
+                    suggestion=(
+                        f"Consider installing a prebuilt wheel: "
+                        f"pip install --only-binary :all: {pkg.package_name}"
+                    ),
+                    confidence=0.8,
+                ))
+
+        return findings
+
+
+class SourceBuildNoCompilerRule(Rule):
+    """Warn if source-built packages exist but no C compiler is available.
+
+    If a package was built from source but gcc/clang are not currently
+    present, rebuilds or updates will fail.
+    """
+
+    rule_id = "SOURCE_BUILD_NO_COMPILER"
+    description = "Source-built packages with no compiler available"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        return not profile.has_build_tools
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+
+        source_built = [
+            pkg for pkg in packages
+            if not pkg.is_pure_python and pkg.has_binaries and not pkg.wheel_tags
+        ]
+
+        if source_built:
+            names = ", ".join(p.package_name for p in source_built[:5])
+            remaining = len(source_built) - 5
+            suffix = f" (+{remaining} more)" if remaining > 0 else ""
+
+            findings.append(Finding(
+                rule_id=self.rule_id,
+                severity=Severity.WARNING,
+                title="Source-built packages but no C compiler found",
+                explanation=(
+                    f"Found {len(source_built)} package(s) built from source "
+                    f"({names}{suffix}) but no C/C++ compiler (gcc, g++, clang) "
+                    f"is available on this system. Upgrading or reinstalling these "
+                    f"packages will fail without a compiler."
+                ),
+                suggestion=(
+                    "Install build tools: apt install build-essential "
+                    "(Debian/Ubuntu) or yum groupinstall 'Development Tools' (RHEL)"
+                ),
+                confidence=0.9,
+            ))
+
+        return findings
+
+
+class MissingPythonHeadersRule(Rule):
+    """Warn if Python dev headers are missing for source builds."""
+
+    rule_id = "SOURCE_BUILD_NO_PYTHON_HEADERS"
+    description = "Python development headers missing for source builds"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        return not profile.has_python_dev_headers and profile.has_build_tools
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+
+        source_built = [
+            pkg for pkg in packages
+            if not pkg.is_pure_python and pkg.has_binaries and not pkg.wheel_tags
+        ]
+
+        if source_built:
+            py_ver = ".".join(str(v) for v in profile.python_version[:2])
+            findings.append(Finding(
+                rule_id=self.rule_id,
+                severity=Severity.WARNING,
+                title="Python development headers not found",
+                explanation=(
+                    f"Found {len(source_built)} source-built package(s) but "
+                    f"Python.h was not found. Building C extensions requires "
+                    f"Python development headers."
+                ),
+                suggestion=(
+                    f"Install Python headers: apt install python{py_ver}-dev "
+                    f"(Debian/Ubuntu) or yum install python3-devel (RHEL)"
+                ),
+                confidence=0.85,
+            ))
+
+        return findings

pybinaryguard/rules/builtin/venv_rules.py

@@ -0,0 +1,159 @@
+"""Virtual environment misconfiguration rules.
+
+Detects common venv issues that cause packages to misbehave:
+system/venv package mixing, pip user-site leaks, stale environments.
+"""
+
+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.rules.base import Rule
+
+
+class SystemPythonWarningRule(Rule):
+    """Warn when running on system Python without a virtual environment."""
+
+    rule_id = "VENV_SYSTEM_PYTHON"
+    description = "Detect use of system Python without isolation"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        return profile.is_system_python
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+
+        # Only warn if there are a significant number of packages
+        if len(packages) > 10:
+            findings.append(Finding(
+                rule_id=self.rule_id,
+                severity=Severity.INFO,
+                title="Running on system Python without a virtual environment",
+                explanation=(
+                    f"Found {len(packages)} packages installed on system Python. "
+                    f"Installing packages system-wide can cause conflicts with "
+                    f"OS-managed packages and may break system tools. This is "
+                    f"especially risky on Debian/Ubuntu where Python is externally "
+                    f"managed (PEP 668)."
+                ),
+                suggestion=(
+                    "Create a virtual environment: python3 -m venv .venv && "
+                    "source .venv/bin/activate"
+                ),
+                confidence=0.7,
+            ))
+
+        return findings
+
+
+class MixedEnvironmentRule(Rule):
+    """Detect packages from multiple environments leaking into sys.path."""
+
+    rule_id = "VENV_MIXED_ENVIRONMENT"
+    description = "Detect mixed package sources on sys.path"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        return profile.mixed_env_risk
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        return [Finding(
+            rule_id=self.rule_id,
+            severity=Severity.WARNING,
+            title="Mixed package environments detected",
+            explanation=(
+                "Packages from multiple environment roots are on sys.path. "
+                "This happens when system packages leak into a virtual environment "
+                "or when multiple venvs overlap. Mixed environments cause "
+                "unpredictable import behavior and version conflicts."
+            ),
+            suggestion=(
+                "Create a clean virtual environment: python3 -m venv --clear .venv"
+            ),
+            confidence=0.85,
+        )]
+
+
+class UserSiteLeakRule(Rule):
+    """Detect pip user-site packages leaking into a virtual environment."""
+
+    rule_id = "VENV_USER_SITE_LEAK"
+    description = "Detect user-site packages leaking into venv"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        return profile.is_virtual_env and profile.pip_user_site_enabled
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        return [Finding(
+            rule_id=self.rule_id,
+            severity=Severity.WARNING,
+            title="User site-packages leaking into virtual environment",
+            explanation=(
+                f"Running in a {profile.venv_type} environment but pip user "
+                f"site-packages directory is on sys.path. Packages installed "
+                f"with 'pip install --user' outside the venv will shadow "
+                f"venv-installed packages, causing version confusion."
+            ),
+            suggestion=(
+                "Set PYTHONNOUSERSITE=1 or create venv with: "
+                "python3 -m venv --system-site-packages=off .venv"
+            ),
+            confidence=0.9,
+        )]
+
+
+class CondaPipMixingRule(Rule):
+    """Detect pip-installed packages in a conda environment."""
+
+    rule_id = "VENV_CONDA_PIP_MIXING"
+    description = "Detect pip packages in conda environment"
+
+    def is_applicable(self, profile: SystemProfile) -> bool:
+        return profile.venv_type == "conda"
+
+    def evaluate(
+        self, profile: SystemProfile, packages: List[PackageBinaryInfo]
+    ) -> List[Finding]:
+        findings: List[Finding] = []
+
+        # In conda envs, packages without wheel tags that have binaries
+        # were likely pip-installed (conda packages have different metadata)
+        pip_binary_pkgs = [
+            pkg for pkg in packages
+            if pkg.has_binaries and pkg.wheel_tags
+        ]
+
+        if len(pip_binary_pkgs) > 5:
+            names = ", ".join(p.package_name for p in pip_binary_pkgs[:5])
+            remaining = len(pip_binary_pkgs) - 5
+            suffix = f" (+{remaining} more)" if remaining > 0 else ""
+
+            findings.append(Finding(
+                rule_id=self.rule_id,
+                severity=Severity.INFO,
+                title=f"Pip-installed binary packages in conda environment",
+                explanation=(
+                    f"Found {len(pip_binary_pkgs)} pip-installed package(s) with "
+                    f"compiled extensions in a conda environment ({names}{suffix}). "
+                    f"Mixing pip and conda can cause library conflicts when both "
+                    f"provide different versions of shared libraries (e.g., libstdc++, "
+                    f"MKL, OpenSSL)."
+                ),
+                suggestion=(
+                    "Prefer conda install for packages with C extensions: "
+                    "conda install <package>. Use pip only for packages not "
+                    "available via conda."
+                ),
+                confidence=0.7,
+            ))
+
+        return findings

pybinaryguard/rules/engine.py

@@ -0,0 +1,123 @@
+"""Rule engine -- orchestrates evaluation of all registered rules."""
+
+from __future__ import annotations
+
+from typing import List, Set
+
+from pybinaryguard.models.system import SystemProfile
+from pybinaryguard.models.package import PackageBinaryInfo
+from pybinaryguard.models.finding import Finding
+from pybinaryguard.rules.base import Rule
+
+
+class RuleEngine:
+    """Evaluates registered rules against a system profile and package list.
+
+    The engine holds a list of :class:`Rule` instances, runs each applicable
+    rule, collects findings, and returns them sorted by severity (critical
+    first).
+
+    Example::
+
+        engine = RuleEngine.with_builtin_rules()
+        findings = engine.evaluate(profile, packages)
+    """
+
+    def __init__(self, ignored_rules: Set[str] | None = None) -> None:
+        self._rules: List[Rule] = []
+        self._ignored_rules: Set[str] = ignored_rules or set()
+
+    # -- Registration -------------------------------------------------------
+
+    def register(self, rule: Rule) -> None:
+        """Add a rule to the engine.
+
+        Args:
+            rule: An instance of a :class:`Rule` subclass.
+
+        Raises:
+            TypeError: If *rule* is not a :class:`Rule` instance.
+        """
+        if not isinstance(rule, Rule):
+            raise TypeError(
+                f"Expected a Rule instance, got {type(rule).__name__}"
+            )
+        self._rules.append(rule)
+
+    @property
+    def rules(self) -> List[Rule]:
+        """All currently registered rules."""
+        return list(self._rules)
+
+    @property
+    def ignored_rules(self) -> Set[str]:
+        """Rule IDs that will be skipped during evaluation."""
+        return set(self._ignored_rules)
+
+    @ignored_rules.setter
+    def ignored_rules(self, value: Set[str]) -> None:
+        self._ignored_rules = set(value)
+
+    # -- Evaluation ---------------------------------------------------------
+
+    def evaluate(
+        self,
+        profile: SystemProfile,
+        packages: List[PackageBinaryInfo],
+    ) -> List[Finding]:
+        """Run all applicable rules and return sorted findings.
+
+        Rules whose ``rule_id`` is in :attr:`ignored_rules` are skipped.
+        Rules whose :meth:`~Rule.is_applicable` returns ``False`` for
+        *profile* are also skipped.
+
+        Args:
+            profile: The current system profile.
+            packages: List of packages with binary analysis data.
+
+        Returns:
+            Findings sorted by severity (CRITICAL first, then WARNING,
+            INFO, PASSED).
+        """
+        findings: List[Finding] = []
+        for rule in self._rules:
+            if rule.rule_id in self._ignored_rules:
+                continue
+            if not rule.is_applicable(profile):
+                continue
+            try:
+                rule_findings = rule.evaluate(profile, packages)
+                findings.extend(rule_findings)
+            except Exception:
+                # Individual rule failures must not crash the whole scan.
+                # In production this would be logged; for now we silently
+                # skip the broken rule.
+                pass
+        findings.sort(key=lambda f: f.severity)
+        return findings
+
+    # -- Factory ------------------------------------------------------------
+
+    @classmethod
+    def with_builtin_rules(
+        cls,
+        ignored_rules: Set[str] | None = None,
+    ) -> "RuleEngine":
+        """Create an engine pre-loaded with all built-in rules.
+
+        Args:
+            ignored_rules: Optional set of rule IDs to skip.
+
+        Returns:
+            A fully-configured :class:`RuleEngine`.
+        """
+        engine = cls(ignored_rules=ignored_rules)
+        engine.load_builtin_rules()
+        return engine
+
+    def load_builtin_rules(self) -> None:
+        """Instantiate and register all built-in rules."""
+        from pybinaryguard.rules.builtin import get_all_builtin_rules
+
+        for rule in get_all_builtin_rules():
+            self.register(rule)