pybinaryguard 1.0.0__py3-none-any.whl

pybinaryguard/plugins/loader.py

@@ -0,0 +1,190 @@
+"""Plugin discovery and loading via ``importlib.metadata`` entry points.
+
+Plugins declare themselves through the ``pybinaryguard.plugins`` entry-point
+group in their ``pyproject.toml`` (or ``setup.cfg`` / ``setup.py``).  Each
+entry point must resolve to a module that exposes a ``register(registry)``
+function.
+
+Example ``pyproject.toml`` snippet::
+
+    [project.entry-points."pybinaryguard.plugins"]
+    my_plugin = "my_package.pybinaryguard_plugin"
+
+The module ``my_package.pybinaryguard_plugin`` must define::
+
+    def register(registry: HookRegistry) -> None:
+        ...
+
+This module also discovers the built-in contrib plugins that ship with
+PyBinaryGuard itself (Jetson, OpenCV, TensorRT, GStreamer).
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import sys
+from typing import List
+
+from pybinaryguard.plugins.hooks import HookRegistry
+
+logger = logging.getLogger(__name__)
+
+ENTRY_POINT_GROUP = "pybinaryguard.plugins"
+
+# Built-in contrib plugin module paths, loaded after external entry points.
+_BUILTIN_CONTRIB_MODULES: List[str] = [
+    "pybinaryguard.plugins.contrib.jetson",
+    "pybinaryguard.plugins.contrib.opencv",
+    "pybinaryguard.plugins.contrib.tensorrt",
+    "pybinaryguard.plugins.contrib.gstreamer",
+]
+
+
+def _load_entry_point_plugins(registry: HookRegistry) -> None:
+    """Discover and load external plugins via ``importlib.metadata`` entry points.
+
+    Handles both the Python 3.9 API (``entry_points()`` returns a dict)
+    and the Python 3.10+ API (``entry_points(group=...)``).
+    """
+    try:
+        from importlib.metadata import entry_points
+    except ImportError:
+        # Fallback for very old environments that lack importlib.metadata
+        # (should not happen on 3.9+ but guard defensively).
+        logger.debug("importlib.metadata not available; skipping entry-point discovery")
+        return
+
+    eps: list = []
+    try:
+        # Python 3.12+ and 3.10+ style: keyword argument filtering
+        selected = entry_points(group=ENTRY_POINT_GROUP)
+        # On 3.10-3.11 this returns a SelectableGroups or list
+        if isinstance(selected, dict):
+            # 3.9 fallback: entry_points() returns a dict of lists
+            eps = list(selected.get(ENTRY_POINT_GROUP, []))
+        else:
+            eps = list(selected)
+    except TypeError:
+        # Python 3.9: entry_points() does not accept keyword arguments.
+        all_eps = entry_points()
+        if isinstance(all_eps, dict):
+            eps = list(all_eps.get(ENTRY_POINT_GROUP, []))
+        else:
+            # Should not reach here, but handle gracefully
+            eps = []
+
+    for ep in eps:
+        try:
+            plugin_module = ep.load()
+            register_fn = getattr(plugin_module, "register", None)
+            if register_fn is None:
+                logger.warning(
+                    "Plugin entry point %r resolved to %r but it has no "
+                    "'register' function; skipping",
+                    ep.name,
+                    plugin_module,
+                )
+                continue
+            if not callable(register_fn):
+                logger.warning(
+                    "Plugin %r has a 'register' attribute but it is not "
+                    "callable; skipping",
+                    ep.name,
+                )
+                continue
+            register_fn(registry)
+            logger.info("Loaded external plugin: %s", ep.name)
+        except Exception:
+            logger.warning(
+                "Failed to load plugin entry point %r; skipping",
+                ep.name,
+                exc_info=True,
+            )
+
+
+def _load_builtin_contrib_plugins(registry: HookRegistry) -> None:
+    """Load the contrib plugins that ship with PyBinaryGuard.
+
+    Each contrib module is imported and its ``register(registry)`` function
+    is called.  Errors in individual contrib plugins are logged and do not
+    prevent the rest from loading.
+    """
+    for module_path in _BUILTIN_CONTRIB_MODULES:
+        try:
+            mod = importlib.import_module(module_path)
+        except ImportError:
+            logger.debug(
+                "Could not import contrib plugin %s; skipping",
+                module_path,
+            )
+            continue
+
+        register_fn = getattr(mod, "register", None)
+        if register_fn is None:
+            logger.debug(
+                "Contrib module %s has no 'register' function; skipping",
+                module_path,
+            )
+            continue
+
+        if not callable(register_fn):
+            logger.debug(
+                "Contrib module %s 'register' attribute is not callable; skipping",
+                module_path,
+            )
+            continue
+
+        try:
+            register_fn(registry)
+            logger.debug("Loaded contrib plugin: %s", module_path)
+        except Exception:
+            logger.warning(
+                "Contrib plugin %s raised an error during registration; skipping",
+                module_path,
+                exc_info=True,
+            )
+
+
+def discover_plugins(
+    *,
+    load_contrib: bool = True,
+    load_external: bool = True,
+) -> HookRegistry:
+    """Discover and load all available plugins.
+
+    This is the main entry point for the plugin subsystem.  It creates a
+    fresh :class:`HookRegistry`, populates it from external entry points
+    and built-in contrib plugins, and returns it.
+
+    Args:
+        load_contrib: Whether to load the built-in contrib plugins that
+            ship with PyBinaryGuard (Jetson, OpenCV, TensorRT, GStreamer).
+            Defaults to ``True``.
+        load_external: Whether to discover and load externally-installed
+            plugins via ``importlib.metadata`` entry points.  Defaults
+            to ``True``.
+
+    Returns:
+        A :class:`HookRegistry` populated with all successfully loaded
+        plugin extensions.
+    """
+    registry = HookRegistry()
+
+    if load_external:
+        _load_entry_point_plugins(registry)
+
+    if load_contrib:
+        _load_builtin_contrib_plugins(registry)
+
+    total = registry.summary()
+    registered = sum(total.values())
+    if registered:
+        logger.info(
+            "Plugin discovery complete: %s",
+            ", ".join(f"{k}={v}" for k, v in total.items() if v),
+        )
+    else:
+        logger.debug("Plugin discovery complete: no extensions registered")
+
+    return registry

pybinaryguard/predictor/__init__.py

@@ -0,0 +1,23 @@
+"""Predictive failure engine for runtime simulation.
+
+This module predicts ImportErrors and runtime failures before they occur
+by simulating dynamic linker resolution and symbol dependencies.
+"""
+
+from __future__ import annotations
+
+from .resolver import SymbolResolver, resolve_symbol
+from .dependency_graph import DependencyGraph, build_dependency_graph
+from .linker_simulator import LinkerSimulator, simulate_import
+from .predictor import predict_import_failures, PredictedFailure
+
+__all__ = [
+    "SymbolResolver",
+    "resolve_symbol",
+    "DependencyGraph",
+    "build_dependency_graph",
+    "LinkerSimulator",
+    "simulate_import",
+    "predict_import_failures",
+    "PredictedFailure",
+]

pybinaryguard/predictor/dependency_graph.py

@@ -0,0 +1,226 @@
+"""Dependency graph builder for shared library dependencies.
+
+Builds a graph of DT_NEEDED dependencies to visualize and analyze
+library dependency chains.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+from pybinaryguard.analyzers.elf_analyzer import MinimalELFParser
+
+
+@dataclass
+class DependencyNode:
+    """A node in the dependency graph representing a library."""
+
+    name: str  # Library name (e.g., "libc.so.6")
+    path: Optional[str] = None  # Full path if found
+    dependencies: List[str] = field(default_factory=list)  # DT_NEEDED entries
+    unresolved: bool = False  # Whether this library was found
+    circular: bool = False  # Whether this is part of a circular dependency
+
+
+class DependencyGraph:
+    """Dependency graph for analyzing shared library dependencies."""
+
+    def __init__(self, library_paths: Optional[List[str]] = None):
+        """Initialize the dependency graph builder.
+
+        Args:
+            library_paths: Directories to search for libraries
+        """
+        if library_paths is None:
+            library_paths = [
+                "/lib",
+                "/lib64",
+                "/usr/lib",
+                "/usr/lib64",
+            ]
+
+        self.library_paths = [Path(p) for p in library_paths if Path(p).exists()]
+        self.nodes: Dict[str, DependencyNode] = {}
+        self._visited: Set[str] = set()
+
+    def build_from_binary(self, binary_path: str) -> DependencyNode:
+        """Build dependency graph starting from a binary.
+
+        Args:
+            binary_path: Path to the ELF binary
+
+        Returns:
+            Root DependencyNode for the binary
+        """
+        self.nodes.clear()
+        self._visited.clear()
+
+        root_name = Path(binary_path).name
+        root_node = DependencyNode(name=root_name, path=binary_path)
+        self.nodes[root_name] = root_node
+
+        # Build the graph recursively
+        self._build_recursive(binary_path, root_node)
+
+        return root_node
+
+    def _build_recursive(self, lib_path: str, node: DependencyNode) -> None:
+        """Recursively build dependency graph.
+
+        Args:
+            lib_path: Path to current library
+            node: DependencyNode for current library
+        """
+        # Avoid infinite recursion
+        if lib_path in self._visited:
+            node.circular = True
+            return
+
+        self._visited.add(lib_path)
+
+        try:
+            # Parse ELF to get DT_NEEDED
+            parser = MinimalELFParser(lib_path)
+            needed = parser.get_needed()
+
+            node.dependencies = needed
+
+            # Process each dependency
+            for dep_name in needed:
+                # Check if we already have this node
+                if dep_name in self.nodes:
+                    # Mark as circular if we're revisiting
+                    if dep_name in self._visited:
+                        self.nodes[dep_name].circular = True
+                    continue
+
+                # Create new node
+                dep_node = DependencyNode(name=dep_name)
+
+                # Try to find the library
+                dep_path = self._find_library(dep_name)
+                if dep_path:
+                    dep_node.path = dep_path
+                    self.nodes[dep_name] = dep_node
+                    # Recurse
+                    self._build_recursive(dep_path, dep_node)
+                else:
+                    # Unresolved dependency
+                    dep_node.unresolved = True
+                    self.nodes[dep_name] = dep_node
+
+        except Exception:
+            # If we can't parse, mark dependencies as unknown
+            node.unresolved = True
+
+    def _find_library(self, lib_name: str) -> Optional[str]:
+        """Find a library in the search paths.
+
+        Args:
+            lib_name: Library name
+
+        Returns:
+            Full path or None
+        """
+        for search_path in self.library_paths:
+            lib_path = search_path / lib_name
+            if lib_path.exists():
+                return str(lib_path)
+
+        return None
+
+    def get_unresolved_dependencies(self) -> List[str]:
+        """Get list of unresolved dependencies.
+
+        Returns:
+            List of library names that couldn't be found
+        """
+        return [
+            node.name
+            for node in self.nodes.values()
+            if node.unresolved
+        ]
+
+    def get_dependency_chain(self, target_lib: str) -> Optional[List[str]]:
+        """Get the dependency chain to a specific library.
+
+        Args:
+            target_lib: Target library name
+
+        Returns:
+            List of library names in the chain, or None if not found
+        """
+        # BFS to find shortest path
+        from collections import deque
+
+        if not self.nodes:
+            return None
+
+        # Start from root (first node)
+        root_name = next(iter(self.nodes.keys()))
+
+        queue = deque([(root_name, [root_name])])
+        visited = {root_name}
+
+        while queue:
+            current, path = queue.popleft()
+
+            if current == target_lib:
+                return path
+
+            node = self.nodes.get(current)
+            if node:
+                for dep in node.dependencies:
+                    if dep not in visited:
+                        visited.add(dep)
+                        queue.append((dep, path + [dep]))
+
+        return None
+
+    def has_circular_dependencies(self) -> bool:
+        """Check if the graph has circular dependencies.
+
+        Returns:
+            True if circular dependencies exist
+        """
+        return any(node.circular for node in self.nodes.values())
+
+    def to_dict(self) -> Dict[str, object]:
+        """Convert graph to dictionary representation.
+
+        Returns:
+            Dictionary with graph structure
+        """
+        return {
+            "nodes": {
+                name: {
+                    "path": node.path,
+                    "dependencies": node.dependencies,
+                    "unresolved": node.unresolved,
+                    "circular": node.circular,
+                }
+                for name, node in self.nodes.items()
+            },
+            "unresolved_count": len(self.get_unresolved_dependencies()),
+            "has_circular": self.has_circular_dependencies(),
+        }
+
+
+def build_dependency_graph(
+    binary_path: str,
+    library_paths: Optional[List[str]] = None
+) -> DependencyGraph:
+    """Convenience function to build a dependency graph.
+
+    Args:
+        binary_path: Path to the ELF binary
+        library_paths: Optional library search paths
+
+    Returns:
+        DependencyGraph instance
+    """
+    graph = DependencyGraph(library_paths)
+    graph.build_from_binary(binary_path)
+    return graph

pybinaryguard/predictor/linker_simulator.py

@@ -0,0 +1,161 @@
+"""Dynamic linker simulation for predicting runtime failures.
+
+Simulates the behavior of ld.so to predict symbol resolution failures
+before they occur at runtime.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from pybinaryguard.predictor.dependency_graph import DependencyGraph
+from pybinaryguard.predictor.resolver import SymbolResolver
+
+
+@dataclass
+class LinkageResult:
+    """Result of simulated dynamic linking."""
+
+    success: bool
+    missing_symbols: List[str]
+    missing_libraries: List[str]
+    symbol_sources: Dict[str, Optional[str]]  # symbol -> providing library
+    error_message: Optional[str] = None
+
+
+class LinkerSimulator:
+    """Simulates dynamic linker behavior to predict failures."""
+
+    def __init__(self, library_paths: Optional[List[str]] = None):
+        """Initialize the linker simulator.
+
+        Args:
+            library_paths: Directories to search for libraries
+        """
+        self.resolver = SymbolResolver(library_paths)
+        self.library_paths = library_paths
+
+    def simulate_load(self, binary_path: str) -> LinkageResult:
+        """Simulate loading a binary and resolving all symbols.
+
+        Args:
+            binary_path: Path to the ELF binary
+
+        Returns:
+            LinkageResult with success status and details
+        """
+        # Build dependency graph
+        dep_graph = DependencyGraph(self.library_paths)
+        root_node = dep_graph.build_from_binary(binary_path)
+
+        # Check for missing libraries
+        missing_libs = dep_graph.get_unresolved_dependencies()
+
+        if missing_libs:
+            return LinkageResult(
+                success=False,
+                missing_symbols=[],
+                missing_libraries=missing_libs,
+                symbol_sources={},
+                error_message=f"Missing libraries: {', '.join(missing_libs)}"
+            )
+
+        # Try to resolve symbols
+        needed_libs = root_node.dependencies
+        symbol_resolution = self.resolver.resolve_undefined_symbols(
+            binary_path,
+            needed_libs
+        )
+
+        # Find unresolved symbols
+        missing_symbols = [
+            sym for sym, provider in symbol_resolution.items()
+            if provider is None
+        ]
+
+        if missing_symbols:
+            # Format error message similar to actual ImportError
+            first_missing = missing_symbols[0]
+            error_msg = (
+                f"ImportError: {binary_path}: "
+                f"undefined symbol: {first_missing}"
+            )
+
+            return LinkageResult(
+                success=False,
+                missing_symbols=missing_symbols,
+                missing_libraries=[],
+                symbol_sources=symbol_resolution,
+                error_message=error_msg
+            )
+
+        # Check for circular dependencies
+        if dep_graph.has_circular_dependencies():
+            return LinkageResult(
+                success=True,  # Still successful, but warn
+                missing_symbols=[],
+                missing_libraries=[],
+                symbol_sources=symbol_resolution,
+                error_message="Warning: Circular dependencies detected"
+            )
+
+        return LinkageResult(
+            success=True,
+            missing_symbols=[],
+            missing_libraries=[],
+            symbol_sources=symbol_resolution,
+        )
+
+    def predict_import_error(
+        self,
+        module_path: str,
+        extension_name: str
+    ) -> Optional[str]:
+        """Predict ImportError for a Python extension module.
+
+        Args:
+            module_path: Path to the extension module (.so file)
+            extension_name: Name of the extension (for error message)
+
+        Returns:
+            Predicted error message, or None if import should succeed
+        """
+        result = self.simulate_load(module_path)
+
+        if not result.success:
+            if result.missing_libraries:
+                # Format like actual ImportError
+                missing = result.missing_libraries[0]
+                return (
+                    f"ImportError: {extension_name}: "
+                    f"cannot open shared object file: {missing}: "
+                    f"No such file or directory"
+                )
+
+            if result.missing_symbols:
+                # Format like actual ImportError
+                missing = result.missing_symbols[0]
+                return (
+                    f"ImportError: {module_path}: "
+                    f"undefined symbol: {missing}"
+                )
+
+        return None
+
+
+def simulate_import(
+    binary_path: str,
+    library_paths: Optional[List[str]] = None
+) -> LinkageResult:
+    """Convenience function to simulate importing a binary.
+
+    Args:
+        binary_path: Path to the ELF binary
+        library_paths: Optional library search paths
+
+    Returns:
+        LinkageResult with simulation results
+    """
+    simulator = LinkerSimulator(library_paths)
+    return simulator.simulate_load(binary_path)