lucidscan 0.5.12__py3-none-any.whl

lucidscan/__init__.py

@@ -0,0 +1,12 @@
+"""
+lucidscan package root.
+
+This module currently only exposes version metadata. Core functionality lives in
+subpackages such as `core`, `schema`, and `scanners`.
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.3.0"
+
+

lucidscan/bootstrap/__init__.py

@@ -0,0 +1,26 @@
+"""
+Bootstrap module for lucidscan plugin binary management.
+
+This module handles:
+- Platform detection (OS + architecture)
+- Plugin binary directory management (~/.lucidscan/bin/)
+- Binary validation utilities
+
+Each scanner plugin is responsible for downloading its own binary
+using the utilities provided by this module.
+"""
+
+from lucidscan.bootstrap.platform import get_platform_info, PlatformInfo
+from lucidscan.bootstrap.paths import get_lucidscan_home, LucidscanPaths
+from lucidscan.bootstrap.validation import validate_binary, PluginValidationResult, ToolStatus
+
+__all__ = [
+    "get_platform_info",
+    "PlatformInfo",
+    "get_lucidscan_home",
+    "LucidscanPaths",
+    "validate_binary",
+    "PluginValidationResult",
+    "ToolStatus",
+]
+

lucidscan/bootstrap/paths.py

@@ -0,0 +1,160 @@
+"""Path management for lucidscan plugin binary cache.
+
+Handles the .lucidscan directory structure and path resolution.
+Each scanner plugin manages its own binary under .lucidscan/bin/{tool}/{version}/.
+
+By default, tools are stored in the project root under .lucidscan/.
+The LUCIDSCAN_HOME environment variable can override this for global installations.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar, Optional
+
+# Default directory name
+DEFAULT_HOME_DIR_NAME = ".lucidscan"
+
+# Environment variable to override home directory (for global installations)
+LUCIDSCAN_HOME_ENV = "LUCIDSCAN_HOME"
+
+
+def get_lucidscan_home(project_root: Optional[Path] = None) -> Path:
+    """Get the lucidscan home directory path.
+
+    Resolution order:
+    1. LUCIDSCAN_HOME environment variable (if set) - for global installations
+    2. {project_root}/.lucidscan (if project_root provided)
+    3. {cwd}/.lucidscan (default)
+
+    Args:
+        project_root: Optional project root directory. If not provided,
+                     uses current working directory.
+
+    Returns:
+        Path to the lucidscan home directory.
+    """
+    # Global override takes precedence
+    env_home = os.environ.get(LUCIDSCAN_HOME_ENV)
+    if env_home:
+        return Path(env_home)
+
+    # Use project root or current directory
+    if project_root:
+        return project_root / DEFAULT_HOME_DIR_NAME
+
+    return Path.cwd() / DEFAULT_HOME_DIR_NAME
+
+
+@dataclass
+class LucidscanPaths:
+    """Manages paths within the lucidscan home directory.
+
+    Directory structure (plugin-based):
+        {project}/.lucidscan/
+            bin/
+                trivy/{version}/trivy       - Trivy binary
+                opengrep/{version}/opengrep - OpenGrep binary
+                checkov/{version}/venv/     - Checkov virtualenv
+                ruff/{version}/ruff         - Ruff binary
+            cache/
+                trivy/                      - Trivy vulnerability DB
+            config/                         - Configuration files
+            logs/                           - Debug/diagnostic logs
+    """
+
+    home: Path
+
+    # Subdirectory names
+    _BIN_DIR: ClassVar[str] = "bin"
+    _CACHE_DIR: ClassVar[str] = "cache"
+    _CONFIG_DIR: ClassVar[str] = "config"
+    _LOGS_DIR: ClassVar[str] = "logs"
+
+    @classmethod
+    def default(cls) -> "LucidscanPaths":
+        """Create paths from the default lucidscan home (cwd/.lucidscan)."""
+        return cls(get_lucidscan_home())
+
+    @classmethod
+    def for_project(cls, project_root: Path) -> "LucidscanPaths":
+        """Create paths for a specific project.
+
+        Args:
+            project_root: Project root directory.
+
+        Returns:
+            LucidscanPaths configured for the project.
+        """
+        return cls(get_lucidscan_home(project_root))
+
+    @property
+    def bin_dir(self) -> Path:
+        """Directory containing scanner plugin binaries."""
+        return self.home / self._BIN_DIR
+
+    @property
+    def cache_dir(self) -> Path:
+        """Directory for scanner caches."""
+        return self.home / self._CACHE_DIR
+
+    @property
+    def config_dir(self) -> Path:
+        """Directory for configuration files."""
+        return self.home / self._CONFIG_DIR
+
+    @property
+    def logs_dir(self) -> Path:
+        """Directory for log files."""
+        return self.home / self._LOGS_DIR
+
+    def plugin_bin_dir(self, plugin_name: str, version: str) -> Path:
+        """Get the binary directory for a specific plugin version.
+
+        Args:
+            plugin_name: Name of the plugin (e.g., 'trivy', 'opengrep').
+            version: Version string.
+
+        Returns:
+            Path to the plugin's version-specific binary directory.
+        """
+        return self.bin_dir / plugin_name / version
+
+    def plugin_cache_dir(self, plugin_name: str) -> Path:
+        """Get the cache directory for a specific plugin.
+
+        Args:
+            plugin_name: Name of the plugin.
+
+        Returns:
+            Path to the plugin's cache directory.
+        """
+        return self.cache_dir / plugin_name
+
+    def ensure_directories(self) -> None:
+        """Create all required directories if they don't exist."""
+        directories = [
+            self.home,
+            self.bin_dir,
+            self.cache_dir,
+            self.config_dir,
+            self.logs_dir,
+        ]
+        for directory in directories:
+            directory.mkdir(parents=True, exist_ok=True)
+
+    def is_initialized(self) -> bool:
+        """Check if any scanner plugins have been installed.
+
+        Returns True if the bin directory exists and contains at least
+        one plugin subdirectory.
+        """
+        if not self.bin_dir.exists():
+            return False
+        # Check if any plugin directories exist
+        for plugin_dir in self.bin_dir.iterdir():
+            if plugin_dir.is_dir():
+                return True
+        return False

lucidscan/bootstrap/platform.py

@@ -0,0 +1,111 @@
+"""Platform detection for lucidscan scanner plugins.
+
+Detects OS and architecture to determine which scanner binaries to download.
+"""
+
+from __future__ import annotations
+
+import platform
+from dataclasses import dataclass
+from typing import Optional
+
+# Supported operating systems (lowercase)
+SUPPORTED_OS = frozenset({"darwin", "linux", "windows"})
+
+# Supported architectures (normalized)
+SUPPORTED_ARCH = frozenset({"amd64", "arm64"})
+
+# Architecture normalization map
+_ARCH_MAP = {
+    "x86_64": "amd64",
+    "amd64": "amd64",
+    "arm64": "arm64",
+    "aarch64": "arm64",
+}
+
+
+def normalize_arch(machine: str) -> Optional[str]:
+    """Normalize architecture string to standard form.
+
+    Args:
+        machine: Raw architecture string from platform.machine()
+
+    Returns:
+        Normalized architecture string or None if unknown.
+    """
+    return _ARCH_MAP.get(machine.lower())
+
+
+def detect_os() -> str:
+    """Detect the current operating system.
+
+    Returns:
+        Lowercase OS name (darwin, linux, windows).
+
+    Raises:
+        ValueError: If the OS is not supported.
+    """
+    system = platform.system().lower()
+    if system not in SUPPORTED_OS:
+        raise ValueError(
+            f"Unsupported operating system: {platform.system()}. "
+            f"Supported: {', '.join(sorted(SUPPORTED_OS))}"
+        )
+    return system
+
+
+def detect_arch() -> str:
+    """Detect the current CPU architecture.
+
+    Returns:
+        Normalized architecture string (amd64 or arm64).
+
+    Raises:
+        ValueError: If the architecture is not supported.
+    """
+    machine = platform.machine()
+    normalized = normalize_arch(machine)
+    if normalized is None:
+        raise ValueError(
+            f"Unsupported architecture: {machine}. "
+            f"Supported: {', '.join(sorted(SUPPORTED_ARCH))}"
+        )
+    return normalized
+
+
+@dataclass(frozen=True)
+class PlatformInfo:
+    """Information about the current platform.
+
+    Attributes:
+        os: Operating system (darwin, linux, windows).
+        arch: CPU architecture (amd64, arm64).
+    """
+
+    os: str
+    arch: str
+
+    @property
+    def bundle_name(self) -> str:
+        """Return the bundle name suffix for this platform.
+
+        Example: "darwin-arm64", "linux-amd64"
+        """
+        return f"{self.os}-{self.arch}"
+
+    def is_supported(self) -> bool:
+        """Check if this platform is supported."""
+        return self.os in SUPPORTED_OS and self.arch in SUPPORTED_ARCH
+
+
+def get_platform_info() -> PlatformInfo:
+    """Detect and return current platform information.
+
+    Returns:
+        PlatformInfo with detected OS and architecture.
+
+    Raises:
+        ValueError: If the platform is not supported.
+    """
+    return PlatformInfo(os=detect_os(), arch=detect_arch())
+

lucidscan/bootstrap/validation.py

@@ -0,0 +1,76 @@
+"""Tool validation for lucidscan bootstrap.
+
+Validates that scanner plugin tools are present and executable.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List
+
+from lucidscan.core.logging import get_logger
+
+LOGGER = get_logger(__name__)
+
+
+class ToolStatus(str, Enum):
+    """Status of a tool binary."""
+
+    PRESENT = "present"
+    MISSING = "missing"
+    NOT_EXECUTABLE = "not_executable"
+
+
+@dataclass
+class PluginValidationResult:
+    """Result of validating scanner plugin tools.
+
+    Stores validation status for each discovered plugin by name.
+    """
+
+    statuses: Dict[str, ToolStatus] = field(default_factory=dict)
+
+    def all_valid(self) -> bool:
+        """Check if all validated plugins are present and executable."""
+        if not self.statuses:
+            return True
+        return all(status == ToolStatus.PRESENT for status in self.statuses.values())
+
+    def missing_plugins(self) -> List[str]:
+        """Return list of plugins that are missing or not executable."""
+        return [
+            name
+            for name, status in self.statuses.items()
+            if status != ToolStatus.PRESENT
+        ]
+
+    def get_status(self, plugin_name: str) -> ToolStatus:
+        """Get status for a specific plugin."""
+        return self.statuses.get(plugin_name, ToolStatus.MISSING)
+
+    def to_dict(self) -> Dict[str, str]:
+        """Convert to dictionary for JSON serialization."""
+        return {name: status.value for name, status in self.statuses.items()}
+
+
+def validate_binary(path: Path) -> ToolStatus:
+    """Validate a single binary file.
+
+    Args:
+        path: Path to the binary file.
+
+    Returns:
+        ToolStatus indicating whether the binary is present and executable.
+    """
+    if not path.exists():
+        return ToolStatus.MISSING
+
+    # Check if executable
+    if not os.access(path, os.X_OK):
+        return ToolStatus.NOT_EXECUTABLE
+
+    return ToolStatus.PRESENT
+

lucidscan/bootstrap/versions.py

@@ -0,0 +1,119 @@
+"""Centralized tool version management.
+
+Reads tool versions from pyproject.toml [tool.lucidscan.tools] section.
+This is the single source of truth for all lucidscan-managed tool versions.
+"""
+
+from __future__ import annotations
+
+import sys
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# Import tomllib (Python 3.11+) or tomli (Python 3.10)
+try:
+    if sys.version_info >= (3, 11):
+        import tomllib
+
+        _tomllib: Any = tomllib
+    else:
+        import tomli
+
+        _tomllib = tomli
+except ImportError:
+    _tomllib = None  # Will use fallback versions
+
+
+# Hardcoded fallback versions (kept in sync with pyproject.toml)
+# These are used if pyproject.toml cannot be read at runtime
+_FALLBACK_VERSIONS: Dict[str, str] = {
+    # Security scanners
+    "trivy": "0.68.2",
+    "opengrep": "1.15.0",
+    "checkov": "3.2.497",
+    # Linters
+    "ruff": "0.14.11",
+    "biome": "2.3.11",
+    "checkstyle": "13.0.0",
+    # Type checkers
+    "pyright": "1.1.408",
+}
+
+
+@lru_cache(maxsize=1)
+def _load_pyproject_versions() -> Dict[str, str]:
+    """Load tool versions from lucidscan's pyproject.toml.
+
+    Returns:
+        Dictionary mapping tool names to versions.
+    """
+    if _tomllib is None:
+        return _FALLBACK_VERSIONS.copy()
+
+    # Find pyproject.toml relative to this module
+    # Structure: src/lucidscan/bootstrap/versions.py -> ../../../pyproject.toml
+    pyproject_path = Path(__file__).parent.parent.parent.parent / "pyproject.toml"
+
+    if not pyproject_path.exists():
+        # Installed package - pyproject.toml not available
+        return _FALLBACK_VERSIONS.copy()
+
+    try:
+        with open(pyproject_path, "rb") as f:
+            data = _tomllib.load(f)
+
+        versions = {}
+
+        # Read from [tool.lucidscan.tools] section (new unified section)
+        tools_section = data.get("tool", {}).get("lucidscan", {}).get("tools", {})
+        versions.update(tools_section)
+
+        # Also read from legacy [tool.lucidscan.scanners] section for backwards compat
+        scanners_section = data.get("tool", {}).get("lucidscan", {}).get("scanners", {})
+        for tool, version in scanners_section.items():
+            if tool not in versions:
+                versions[tool] = version
+
+        # Fill in any missing tools from fallbacks
+        for tool, version in _FALLBACK_VERSIONS.items():
+            if tool not in versions:
+                versions[tool] = version
+
+        return versions
+
+    except Exception:
+        return _FALLBACK_VERSIONS.copy()
+
+
+def get_tool_version(tool_name: str, default: Optional[str] = None) -> str:
+    """Get the version for a specific tool.
+
+    Args:
+        tool_name: Name of the tool (e.g., 'trivy', 'ruff').
+        default: Optional default version if tool not found.
+
+    Returns:
+        Version string for the tool.
+
+    Raises:
+        KeyError: If tool not found and no default provided.
+    """
+    versions = _load_pyproject_versions()
+
+    if tool_name in versions:
+        return versions[tool_name]
+
+    if default is not None:
+        return default
+
+    raise KeyError(f"Unknown tool: {tool_name}. Available: {list(versions.keys())}")
+
+
+def get_all_versions() -> Dict[str, str]:
+    """Get all tool versions.
+
+    Returns:
+        Dictionary mapping tool names to versions.
+    """
+    return _load_pyproject_versions().copy()

lucidscan/cli/__init__.py

@@ -0,0 +1,50 @@
+"""LucidScan CLI package.
+
+This package provides the command-line interface for lucidscan.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+from lucidscan.cli.runner import CLIRunner, get_version
+from lucidscan.cli.arguments import build_parser
+from lucidscan.cli.exit_codes import (
+    EXIT_SUCCESS,
+    EXIT_ISSUES_FOUND,
+    EXIT_SCANNER_ERROR,
+    EXIT_INVALID_USAGE,
+    EXIT_BOOTSTRAP_FAILURE,
+)
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    """CLI entrypoint.
+
+    Returns an exit code suitable for use as a console script.
+
+    Args:
+        argv: Command-line arguments (defaults to sys.argv).
+
+    Returns:
+        Exit code.
+    """
+    runner = CLIRunner()
+    return runner.run(argv)
+
+
+__all__ = [
+    "main",
+    "build_parser",
+    "get_version",
+    "CLIRunner",
+    "EXIT_SUCCESS",
+    "EXIT_ISSUES_FOUND",
+    "EXIT_SCANNER_ERROR",
+    "EXIT_INVALID_USAGE",
+    "EXIT_BOOTSTRAP_FAILURE",
+]
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

lucidscan/cli/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for running lucidscan.cli as a module."""
+
+from __future__ import annotations
+
+from lucidscan.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())