pybinaryguard 1.0.0__py3-none-any.whl

pybinaryguard/frameworks/tensorrt.py

@@ -0,0 +1,189 @@
+"""TensorRT framework deep inspection.
+
+Validates TensorRT engine metadata, CUDA compatibility, and
+plugin availability beyond generic binary checks.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional
+
+from pybinaryguard.models.package import PackageBinaryInfo
+from pybinaryguard.models.system import SystemProfile
+
+
+def validate_tensorrt_engine(
+    package: PackageBinaryInfo,
+    profile: SystemProfile
+) -> List[Dict[str, str]]:
+    """Validate TensorRT installation and compatibility.
+
+    Checks:
+    - TensorRT version compatibility with CUDA
+    - Required plugins availability
+    - Compute capability support
+    - cuDNN version requirements
+
+    Args:
+        package: PackageBinaryInfo for tensorrt package
+        profile: System profile
+
+    Returns:
+        List of compatibility issues found
+    """
+    issues: List[Dict[str, str]] = []
+
+    if not package.name.lower().startswith("tensorrt"):
+        return issues
+
+    # Extract TensorRT version from package
+    trt_version = package.version
+    if not trt_version:
+        return issues
+
+    # TensorRT 8.6+ requires CUDA 11.x or 12.x
+    if trt_version.startswith("8.6") or trt_version.startswith("8.5"):
+        if profile.cuda_runtime_version:
+            cuda_major = int(profile.cuda_runtime_version.split(".")[0])
+            if cuda_major < 11:
+                issues.append({
+                    "issue": "tensorrt_cuda_too_old",
+                    "severity": "critical",
+                    "message": (
+                        f"TensorRT {trt_version} requires CUDA 11.x or 12.x, "
+                        f"but system has CUDA {profile.cuda_runtime_version}"
+                    ),
+                    "recommendation": "Upgrade CUDA runtime or use TensorRT 7.x",
+                })
+
+    # Check compute capability requirements
+    if profile.cuda_compute_capability:
+        compute_major = int(profile.cuda_compute_capability.split(".")[0])
+
+        # TensorRT 8.x requires compute capability >= 5.0
+        if trt_version.startswith("8."):
+            if compute_major < 5:
+                issues.append({
+                    "issue": "tensorrt_compute_capability_too_low",
+                    "severity": "critical",
+                    "message": (
+                        f"TensorRT 8.x requires compute capability >= 5.0, "
+                        f"but GPU has {profile.cuda_compute_capability}"
+                    ),
+                    "recommendation": "Upgrade GPU or use TensorRT 7.x",
+                })
+
+    # Check for common TensorRT plugins
+    available_plugins = detect_tensorrt_plugins(package)
+
+    if not available_plugins:
+        issues.append({
+            "issue": "no_tensorrt_plugins",
+            "severity": "info",
+            "message": "No TensorRT plugins detected in installation",
+            "recommendation": "Install tensorrt-plugins package if needed for custom layers",
+        })
+
+    return issues
+
+
+def detect_tensorrt_plugins(package: PackageBinaryInfo) -> List[str]:
+    """Detect available TensorRT plugins from shared objects.
+
+    Args:
+        package: PackageBinaryInfo for tensorrt package
+
+    Returns:
+        List of detected plugin names
+    """
+    plugins = []
+
+    for so in package.shared_objects:
+        if not so.path:
+            continue
+
+        # TensorRT plugins typically named libnvinfer_plugin.so
+        if "plugin" in so.path.lower():
+            plugins.append(so.path)
+
+    return plugins
+
+
+def check_tensorrt_cudnn_compatibility(
+    tensorrt_version: Optional[str],
+    cudnn_version: Optional[str]
+) -> Optional[str]:
+    """Check TensorRT and cuDNN version compatibility.
+
+    Args:
+        tensorrt_version: TensorRT version (e.g., "8.6.1")
+        cudnn_version: cuDNN version (e.g., "8.9.0")
+
+    Returns:
+        Error message if incompatible, None if compatible
+    """
+    if not tensorrt_version or not cudnn_version:
+        return None
+
+    # Compatibility matrix (TensorRT -> cuDNN major version)
+    compatibility_matrix = {
+        "8.6": "8",
+        "8.5": "8",
+        "8.4": "8",
+        "8.2": "8",
+        "8.0": "8",
+        "7.2": "7",
+        "7.1": "7",
+    }
+
+    try:
+        trt_major_minor = ".".join(tensorrt_version.split(".")[:2])
+        cudnn_major = cudnn_version.split(".")[0]
+
+        expected_cudnn_major = compatibility_matrix.get(trt_major_minor)
+        if expected_cudnn_major and cudnn_major != expected_cudnn_major:
+            return (
+                f"TensorRT {trt_major_minor} expects cuDNN {expected_cudnn_major}.x, "
+                f"but found cuDNN {cudnn_version}"
+            )
+    except (ValueError, IndexError):
+        pass
+
+    return None
+
+
+def detect_tensorrt_precision_support(
+    package: PackageBinaryInfo,
+    profile: SystemProfile
+) -> Dict[str, bool]:
+    """Detect supported precision modes (FP32, FP16, INT8).
+
+    Args:
+        package: PackageBinaryInfo for tensorrt package
+        profile: System profile
+
+    Returns:
+        Dictionary with supported precision modes
+    """
+    support = {
+        "fp32": True,  # Always supported
+        "fp16": False,
+        "int8": False,
+    }
+
+    # FP16 requires compute capability >= 5.3
+    if profile.cuda_compute_capability:
+        try:
+            major, minor = profile.cuda_compute_capability.split(".")
+            compute_val = int(major) * 10 + int(minor)
+
+            if compute_val >= 53:  # 5.3
+                support["fp16"] = True
+
+            if compute_val >= 61:  # 6.1
+                support["int8"] = True
+        except (ValueError, IndexError):
+            pass
+
+    return support

pybinaryguard/models/__init__.py

@@ -0,0 +1,19 @@
+"""Core data models for PyBinaryGuard."""
+
+from .enums import Architecture, ContainerRuntime, ScanMode, Severity
+from .finding import Finding, ScanReport
+from .package import PackageBinaryInfo, SharedObjectInfo, WheelTag
+from .system import SystemProfile
+
+__all__ = [
+    "Architecture",
+    "ContainerRuntime",
+    "Finding",
+    "PackageBinaryInfo",
+    "ScanMode",
+    "ScanReport",
+    "Severity",
+    "SharedObjectInfo",
+    "SystemProfile",
+    "WheelTag",
+]

pybinaryguard/models/enums.py

@@ -0,0 +1,102 @@
+"""Core enumerations for PyBinaryGuard."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Severity(Enum):
+    """Severity level for diagnostic findings."""
+
+    CRITICAL = "critical"
+    WARNING = "warning"
+    INFO = "info"
+    PASSED = "passed"
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        order = {Severity.CRITICAL: 0, Severity.WARNING: 1, Severity.INFO: 2, Severity.PASSED: 3}
+        return order[self] < order[other]
+
+    def __le__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self == other or self < other
+
+
+class Architecture(Enum):
+    """CPU architecture identifiers."""
+
+    X86_64 = "x86_64"
+    AARCH64 = "aarch64"
+    ARMV7L = "armv7l"
+    I686 = "i686"
+    PPC64LE = "ppc64le"
+    S390X = "s390x"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_machine(cls, machine: str) -> Architecture:
+        """Convert platform.machine() output to Architecture enum."""
+        mapping = {
+            "x86_64": cls.X86_64,
+            "AMD64": cls.X86_64,
+            "aarch64": cls.AARCH64,
+            "arm64": cls.AARCH64,
+            "armv7l": cls.ARMV7L,
+            "armv6l": cls.ARMV7L,
+            "i686": cls.I686,
+            "i386": cls.I686,
+            "ppc64le": cls.PPC64LE,
+            "s390x": cls.S390X,
+        }
+        return mapping.get(machine, cls.UNKNOWN)
+
+    @property
+    def elf_machine(self) -> int:
+        """Return the ELF e_machine constant for this architecture."""
+        mapping = {
+            Architecture.X86_64: 62,     # EM_X86_64
+            Architecture.AARCH64: 183,   # EM_AARCH64
+            Architecture.ARMV7L: 40,     # EM_ARM
+            Architecture.I686: 3,        # EM_386
+            Architecture.PPC64LE: 21,    # EM_PPC64
+            Architecture.S390X: 22,      # EM_S390
+        }
+        return mapping.get(self, 0)
+
+
+class ContainerRuntime(Enum):
+    """Container runtime types."""
+
+    DOCKER = "docker"
+    PODMAN = "podman"
+    LXC = "lxc"
+    CONTAINERD = "containerd"
+    NONE = "none"
+
+
+class ScanMode(Enum):
+    """Scan depth mode.
+
+    FAST:
+        Metadata-only scan. Reads WHEEL/METADATA files and checks tags
+        against the system profile. Skips ELF binary parsing entirely.
+        Target: < 1 second for 100 packages.
+
+    STANDARD:
+        Default mode. Parses ELF headers for architecture, GLIBC version
+        requirements, and DT_NEEDED libraries. Runs all built-in rules.
+        Target: < 3 seconds for 100 packages (x86).
+
+    DEEP:
+        Full analysis. Everything in STANDARD plus: SHA256 hash verification
+        of all shared objects, recursive DT_NEEDED dependency chain resolution,
+        symbol-level version checking, and predictive import failure simulation.
+        Target: < 10 seconds for 100 packages.
+    """
+
+    FAST = "fast"
+    STANDARD = "standard"
+    DEEP = "deep"

pybinaryguard/models/finding.py

@@ -0,0 +1,109 @@
+"""Finding and report data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional, List, Dict
+
+from .enums import Severity
+
+
+@dataclass
+class Finding:
+    """A single diagnostic result from the compatibility check."""
+
+    rule_id: str
+    severity: Severity
+    title: str
+    explanation: str
+    technical_detail: str = ""
+    suggestion: str = ""
+    package: Optional[str] = None
+    package_version: Optional[str] = None
+    confidence: float = 1.0
+    related_error: Optional[str] = None
+
+    def as_dict(self) -> Dict[str, object]:
+        """Convert to a JSON-serializable dict."""
+        result: Dict[str, object] = {
+            "rule_id": self.rule_id,
+            "severity": self.severity.value,
+            "title": self.title,
+            "explanation": self.explanation,
+        }
+        if self.technical_detail:
+            result["technical_detail"] = self.technical_detail
+        if self.suggestion:
+            result["suggestion"] = self.suggestion
+        if self.package:
+            result["package"] = self.package
+        if self.package_version:
+            result["package_version"] = self.package_version
+        if self.confidence < 1.0:
+            result["confidence"] = self.confidence
+        if self.related_error:
+            result["related_error"] = self.related_error
+        return result
+
+
+@dataclass
+class ScanReport:
+    """Complete scan report containing all findings and metadata."""
+
+    findings: List[Finding] = field(default_factory=list)
+    packages_scanned: int = 0
+    total_packages: int = 0
+    scan_duration_ms: float = 0.0
+    detected_board: Optional[str] = None  # Display name of detected embedded board
+    score_breakdown: Optional[object] = None  # ScoreBreakdown from scoring.engine
+
+    @property
+    def critical_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.CRITICAL)
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.WARNING)
+
+    @property
+    def info_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.INFO)
+
+    @property
+    def passed_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.PASSED)
+
+    @property
+    def health_score(self) -> int:
+        """Return the v2 weighted health score if available, else v1 linear."""
+        if self.score_breakdown is not None:
+            return round(self.score_breakdown.overall_score)
+        score = 100 - (self.critical_count * 25) - (self.warning_count * 5) - (self.info_count * 1)
+        return max(0, min(100, score))
+
+    @property
+    def health_label(self) -> str:
+        if self.score_breakdown is not None:
+            return self.score_breakdown.overall_label
+        score = self.health_score
+        if score >= 90:
+            return "Excellent"
+        elif score >= 70:
+            return "Good"
+        elif score >= 50:
+            return "Needs Attention"
+        else:
+            return "Critical"
+
+    def summary_dict(self) -> Dict[str, object]:
+        result: Dict[str, object] = {
+            "total_packages": self.total_packages,
+            "packages_scanned": self.packages_scanned,
+            "critical": self.critical_count,
+            "warning": self.warning_count,
+            "info": self.info_count,
+            "passed": self.passed_count,
+        }
+        if self.detected_board:
+            result["detected_board"] = self.detected_board
+        return result

pybinaryguard/models/package.py

@@ -0,0 +1,121 @@
+"""Package binary information data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional, Tuple, List, Set
+
+from .enums import Architecture
+
+
+@dataclass
+class SharedObjectInfo:
+    """Information extracted from a single .so file."""
+
+    path: str
+    filename: str
+    architecture: Architecture = Architecture.UNKNOWN
+    elf_class: int = 0  # 32 or 64
+    endianness: str = "little"
+    dt_needed: List[str] = field(default_factory=list)
+    dt_soname: Optional[str] = None
+    dt_rpath: Optional[str] = None
+    dt_runpath: Optional[str] = None
+    required_glibc: Optional[Tuple[int, int]] = None
+    required_glibcxx: Optional[str] = None
+    gnu_version_requirements: List[str] = field(default_factory=list)
+    has_python_symbols: bool = False
+    build_id: Optional[str] = None
+    file_size: int = 0
+    sha256: Optional[str] = None  # Populated in DEEP scan mode
+
+
+@dataclass
+class WheelTag:
+    """A parsed wheel compatibility tag."""
+
+    interpreter: str  # e.g., "cp312"
+    abi: str          # e.g., "cp312"
+    platform: str     # e.g., "manylinux_2_17_x86_64"
+
+
+@dataclass
+class PackageBinaryInfo:
+    """Complete binary analysis of an installed Python package."""
+
+    package_name: str
+    package_version: str
+    install_path: str
+
+    # Wheel metadata
+    wheel_tags: List[WheelTag] = field(default_factory=list)
+    is_pure_python: bool = True
+
+    # Binary analysis
+    shared_objects: List[SharedObjectInfo] = field(default_factory=list)
+    required_glibc: Optional[Tuple[int, int]] = None
+    required_glibcxx: Optional[str] = None
+    target_architecture: Optional[Architecture] = None
+    required_libraries: Set[str] = field(default_factory=set)
+    missing_libraries: Set[str] = field(default_factory=set)
+
+    # Framework-specific
+    cuda_build_version: Optional[Tuple[int, int]] = None
+    numpy_api_version: Optional[int] = None
+
+    @property
+    def name(self) -> str:
+        """Alias for package_name (used by snapshot module)."""
+        return self.package_name
+
+    @property
+    def version(self) -> Optional[str]:
+        """Alias for package_version (used by snapshot module)."""
+        return self.package_version
+
+    @property
+    def cuda_version(self) -> Optional[str]:
+        """CUDA version string extracted from cuda_build_version tuple."""
+        if self.cuda_build_version:
+            return f"{self.cuda_build_version[0]}.{self.cuda_build_version[1]}"
+        return None
+
+    @property
+    def has_binaries(self) -> bool:
+        """Whether this package contains any compiled extensions."""
+        return len(self.shared_objects) > 0
+
+    @property
+    def so_count(self) -> int:
+        """Number of shared object files in this package."""
+        return len(self.shared_objects)
+
+    @property
+    def manylinux_tag(self) -> Optional[str]:
+        """Extract the manylinux tag from wheel tags, if any."""
+        for tag in self.wheel_tags:
+            if "manylinux" in tag.platform:
+                return tag.platform
+        return None
+
+    @property
+    def manylinux_glibc(self) -> Optional[Tuple[int, int]]:
+        """Extract the GLIBC version claimed by the manylinux tag."""
+        tag = self.manylinux_tag
+        if not tag:
+            return None
+        # Parse manylinux_2_17_x86_64 or manylinux2014_x86_64
+        import re
+        match = re.search(r"manylinux_(\d+)_(\d+)", tag)
+        if match:
+            return (int(match.group(1)), int(match.group(2)))
+        # Legacy tags
+        legacy_map = {
+            "manylinux1": (2, 5),
+            "manylinux2010": (2, 12),
+            "manylinux2014": (2, 17),
+        }
+        for prefix, version in legacy_map.items():
+            if tag.startswith(prefix):
+                return version
+        return None

pybinaryguard/models/system.py

@@ -0,0 +1,118 @@
+"""System profile data model — the fingerprint of your machine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional, Tuple, List, FrozenSet, Dict
+
+from .enums import Architecture, ContainerRuntime
+
+
+@dataclass(frozen=True)
+class SystemProfile:
+    """Complete profile of the current system's binary compatibility surface."""
+
+    # Python
+    python_version: Tuple[int, int, int] = (0, 0, 0)
+    python_abi_tag: str = ""
+    python_implementation: str = "cpython"
+    python_executable: str = ""
+    stable_abi_supported: bool = False
+    python_debug_build: bool = False
+
+    # System
+    os_name: str = ""
+    os_version: str = ""
+    kernel_version: str = ""
+    architecture: Architecture = Architecture.UNKNOWN
+    glibc_version: Optional[Tuple[int, int]] = None
+    musl_version: Optional[Tuple[int, int]] = None
+
+    # CPU
+    cpu_model: str = ""
+    cpu_flags: FrozenSet[str] = field(default_factory=frozenset)
+    has_avx: bool = False
+    has_avx2: bool = False
+    has_avx512: bool = False
+    has_sse42: bool = False
+    has_neon: bool = False
+    cpu_cores: int = 0
+
+    # GPU
+    gpu_available: bool = False
+    gpu_driver_version: Optional[str] = None
+    cuda_runtime_version: Optional[Tuple[int, int]] = None
+    cuda_toolkit_version: Optional[Tuple[int, int]] = None
+    gpu_compute_capability: Optional[Tuple[int, int]] = None
+    gpu_name: Optional[str] = None
+    gpu_memory_mb: Optional[int] = None
+    cudnn_version: Optional[Tuple[int, int, int]] = None
+
+    # Environment
+    is_container: bool = False
+    container_runtime: ContainerRuntime = ContainerRuntime.NONE
+    is_virtual_machine: bool = False
+    is_embedded_board: bool = False
+    board_name: Optional[str] = None
+    jetpack_version: Optional[str] = None
+
+    # Build toolchain
+    toolchain_versions: Dict[str, str] = field(default_factory=dict)
+    default_cc: str = ""
+    default_cxx: str = ""
+    has_build_tools: bool = False
+    has_python_dev_headers: bool = False
+
+    # Virtual environment
+    venv_type: str = "system"
+    is_system_python: bool = True
+    is_virtual_env: bool = False
+    base_prefix: str = ""
+    prefix: str = ""
+    conda_env_name: str = ""
+    conda_prefix: str = ""
+    pip_user_site_enabled: bool = False
+    mixed_env_risk: bool = False
+
+    # Library paths
+    ld_library_path: Tuple[str, ...] = ()
+    ldconfig_cache: Dict[str, str] = field(default_factory=dict)
+    site_packages_paths: Tuple[str, ...] = ()
+
+    def summary(self) -> Dict[str, str]:
+        """Return a human-readable summary dict for display."""
+        info: Dict[str, str] = {}
+        if self.python_version != (0, 0, 0):
+            py_ver = ".".join(str(v) for v in self.python_version)
+            info["Python"] = f"{py_ver} ({self.python_abi_tag}) @ {self.python_executable}"
+        if self.os_name:
+            info["OS"] = f"{self.os_name} {self.os_version} (kernel {self.kernel_version})"
+        if self.architecture != Architecture.UNKNOWN:
+            info["Architecture"] = self.architecture.value
+        if self.glibc_version:
+            info["GLIBC"] = f"{self.glibc_version[0]}.{self.glibc_version[1]}"
+        elif self.musl_version:
+            info["musl"] = f"{self.musl_version[0]}.{self.musl_version[1]}"
+        if self.cuda_runtime_version:
+            info["CUDA Runtime"] = f"{self.cuda_runtime_version[0]}.{self.cuda_runtime_version[1]}"
+        if self.gpu_driver_version:
+            info["GPU Driver"] = self.gpu_driver_version
+        if self.gpu_name:
+            cc = ""
+            if self.gpu_compute_capability:
+                cc = f" (compute {self.gpu_compute_capability[0]}.{self.gpu_compute_capability[1]})"
+            info["GPU"] = f"{self.gpu_name}{cc}"
+        if self.is_embedded_board and self.board_name:
+            info["Board"] = self.board_name
+            if self.jetpack_version:
+                info["JetPack"] = self.jetpack_version
+        if self.is_container:
+            info["Container"] = self.container_runtime.value
+        if self.venv_type != "system":
+            info["Environment"] = self.venv_type
+        if self.toolchain_versions:
+            cc = self.toolchain_versions.get("gcc") or self.toolchain_versions.get("clang")
+            if cc:
+                compiler = "gcc" if "gcc" in self.toolchain_versions else "clang"
+                info["Compiler"] = f"{compiler} {cc}"
+        return info

pybinaryguard/plugins/__init__.py

@@ -0,0 +1,19 @@
+"""Plugin subsystem for PyBinaryGuard.
+
+The plugin system allows third-party packages (and built-in contrib
+modules) to extend PyBinaryGuard with additional probes, rules, board
+detectors, framework checkers, reporters, and lifecycle hooks.
+
+Public API
+----------
+.. autoclass:: HookRegistry
+.. autofunction:: discover_plugins
+"""
+
+from pybinaryguard.plugins.hooks import HookRegistry
+from pybinaryguard.plugins.loader import discover_plugins
+
+__all__ = [
+    "HookRegistry",
+    "discover_plugins",
+]

pybinaryguard/plugins/contrib/__init__.py

@@ -0,0 +1,7 @@
+"""Built-in contrib plugins for PyBinaryGuard.
+
+Each module in this package provides extensions for a specific platform
+or framework.  Contrib plugins are loaded automatically by
+:func:`~pybinaryguard.plugins.loader.discover_plugins` and activate
+only when the relevant hardware or software is detected on the system.
+"""