kekkai-cli 1.0.0__py3-none-any.whl

kekkai/installer/manager.py

@@ -0,0 +1,252 @@
+"""Main tool installer manager."""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import ssl
+import tempfile
+import urllib.request
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .errors import DownloadError, InstallerError, SecurityError, UnsupportedPlatformError
+from .extract import extract_archive
+from .manifest import (
+    ToolManifest,
+    get_download_url,
+    get_expected_hash,
+    get_manifest,
+    get_platform_key,
+    validate_manifest_url,
+)
+from .verify import MAX_DOWNLOAD_SIZE, verify_checksum, verify_file_size
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+# Download timeout in seconds
+DOWNLOAD_TIMEOUT = 120
+
+
+class ToolInstaller:
+    """Manages downloading and installing security tools."""
+
+    def __init__(self, install_dir: Path | None = None) -> None:
+        """Initialize the tool installer.
+
+        Args:
+            install_dir: Directory to install tools. Defaults to ~/.kekkai/bin/.
+        """
+        if install_dir is None:
+            from kekkai.paths import bin_dir
+
+            install_dir = bin_dir()
+
+        self.install_dir = install_dir
+        self.install_dir.mkdir(parents=True, exist_ok=True)
+
+    def ensure_tool(self, name: str, auto_install: bool = False) -> Path:
+        """Ensure a tool is installed, downloading if necessary.
+
+        Args:
+            name: Tool name (trivy, semgrep, gitleaks).
+            auto_install: If True, install without prompting.
+
+        Returns:
+            Path to the installed tool binary.
+
+        Raises:
+            InstallerError: If installation fails.
+        """
+        # Check if already installed in our bin directory
+        existing = self._find_installed(name)
+        if existing:
+            logger.debug("Tool %s already installed at %s", name, existing)
+            return existing
+
+        # Check if available in PATH
+        path_tool = shutil.which(name)
+        if path_tool:
+            logger.debug("Tool %s found in PATH at %s", name, path_tool)
+            return Path(path_tool)
+
+        # Need to download
+        manifest = get_manifest(name)
+        if not manifest:
+            raise InstallerError(f"Unknown tool: {name}")
+
+        if not auto_install:
+            logger.info("Tool %s not found. Use --auto-install or install manually.", name)
+            raise InstallerError(
+                f"Tool {name} not found. Use --auto-install to download automatically."
+            )
+
+        return self._download_and_install(manifest)
+
+    def _find_installed(self, name: str) -> Path | None:
+        """Find if tool is already installed in our bin directory.
+
+        Args:
+            name: Tool name.
+
+        Returns:
+            Path to binary if found, None otherwise.
+        """
+        candidates = [
+            self.install_dir / name,
+            self.install_dir / f"{name}.exe",
+        ]
+
+        for path in candidates:
+            if path.exists() and os.access(path, os.X_OK):
+                return path
+
+        return None
+
+    def _download_and_install(self, manifest: ToolManifest) -> Path:
+        """Download and install a tool.
+
+        Args:
+            manifest: Tool manifest.
+
+        Returns:
+            Path to installed binary.
+
+        Raises:
+            SecurityError: If verification fails.
+            DownloadError: If download fails.
+        """
+        # Get expected hash for platform
+        expected_hash = get_expected_hash(manifest)
+        if not expected_hash:
+            platform_key = get_platform_key()
+            raise UnsupportedPlatformError(
+                f"No binary available for {manifest.name} on {platform_key}"
+            )
+
+        # Skip download if hash is a placeholder
+        if expected_hash.startswith("placeholder_"):
+            raise InstallerError(
+                f"SHA256 hash not yet configured for {manifest.name}. "
+                "Please install manually or wait for manifest update."
+            )
+
+        # Build download URL and validate
+        url = get_download_url(manifest)
+        if not validate_manifest_url(url):
+            raise SecurityError(f"URL not from allowed domain: {url}")
+
+        logger.info("Downloading %s v%s from %s", manifest.name, manifest.version, url)
+
+        # Download with strict TLS
+        content = self._download(url, manifest.name)
+
+        # Verify checksum
+        verify_checksum(content, expected_hash, manifest.name)
+
+        # Extract to temp directory first
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            tmp_path = Path(tmp_dir)
+            archive_path = tmp_path / f"{manifest.name}.archive"
+            archive_path.write_bytes(content)
+
+            # Extract binary
+            binary_name = manifest.binary_name or manifest.name
+            extracted_path = extract_archive(
+                archive_path, tmp_path, binary_name, manifest.archive_type
+            )
+
+            # Move to install directory
+            final_path = self.install_dir / extracted_path.name
+            shutil.move(str(extracted_path), str(final_path))
+
+            # Make executable
+            final_path.chmod(0o755)
+
+            logger.info("Installed %s to %s", manifest.name, final_path)
+            return final_path
+
+    def _download(self, url: str, tool_name: str) -> bytes:
+        """Download a file with strict TLS settings.
+
+        Args:
+            url: URL to download.
+            tool_name: Tool name for error messages.
+
+        Returns:
+            Downloaded bytes.
+
+        Raises:
+            DownloadError: If download fails.
+            SecurityError: If file too large.
+        """
+        # Create SSL context with TLS 1.2+ (1.3 preferred but 1.2 is widely supported)
+        ctx = ssl.create_default_context()
+        ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+
+        try:
+            req = urllib.request.Request(  # noqa: S310 - URL validated in validate_manifest_url
+                url,
+                headers={"User-Agent": "kekkai-installer/1.0"},
+            )
+
+            with urllib.request.urlopen(  # noqa: S310 - URL validated
+                req, context=ctx, timeout=DOWNLOAD_TIMEOUT
+            ) as resp:
+                if resp.status != 200:
+                    raise DownloadError(f"Download failed: HTTP {resp.status}")
+
+                # Check content length if provided
+                content_length = resp.headers.get("Content-Length")
+                if content_length:
+                    verify_file_size(int(content_length), tool_name)
+
+                # Read with size limit
+                content: bytes = resp.read(MAX_DOWNLOAD_SIZE + 1)
+                verify_file_size(len(content), tool_name)
+
+                return content
+
+        except urllib.error.HTTPError as e:
+            raise DownloadError(f"HTTP error downloading {tool_name}: {e.code}") from e
+        except urllib.error.URLError as e:
+            raise DownloadError(f"URL error downloading {tool_name}: {e.reason}") from e
+        except TimeoutError as e:
+            raise DownloadError(f"Timeout downloading {tool_name}") from e
+
+    def get_tool_path(self, name: str) -> Path | None:
+        """Get path to an installed tool without downloading.
+
+        Args:
+            name: Tool name.
+
+        Returns:
+            Path if installed, None otherwise.
+        """
+        # Check our install directory first
+        installed = self._find_installed(name)
+        if installed:
+            return installed
+
+        # Check PATH
+        path_tool = shutil.which(name)
+        if path_tool:
+            return Path(path_tool)
+
+        return None
+
+
+# Global installer instance
+_installer: ToolInstaller | None = None
+
+
+def get_installer() -> ToolInstaller:
+    """Get the global installer instance."""
+    global _installer
+    if _installer is None:
+        _installer = ToolInstaller()
+    return _installer

kekkai/installer/manifest.py

@@ -0,0 +1,189 @@
+"""Tool manifests with SHA256 checksums for secure downloads."""
+
+from __future__ import annotations
+
+import platform
+import re
+from dataclasses import dataclass
+
+from .errors import UnsupportedPlatformError
+
+
+@dataclass(frozen=True)
+class ToolManifest:
+    """Manifest for a downloadable security tool."""
+
+    name: str
+    version: str
+    url_template: str
+    sha256: dict[str, str]  # platform_key -> hash
+    binary_name: str | None = None  # Name inside archive (if different from tool name)
+    archive_type: str = "tar.gz"  # "tar.gz" or "zip"
+
+
+def get_platform_key() -> str:
+    """Get platform key for the current system.
+
+    Returns:
+        Platform key like 'linux_amd64', 'darwin_arm64', etc.
+
+    Raises:
+        UnsupportedPlatformError: If platform is not supported.
+    """
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    arch_map = {
+        "x86_64": "amd64",
+        "amd64": "amd64",
+        "aarch64": "arm64",
+        "arm64": "arm64",
+    }
+
+    arch = arch_map.get(machine)
+    if not arch:
+        raise UnsupportedPlatformError(f"Unsupported architecture: {machine}")
+
+    if system not in ("linux", "darwin", "windows"):
+        raise UnsupportedPlatformError(f"Unsupported OS: {system}")
+
+    return f"{system}_{arch}"
+
+
+def get_download_url(manifest: ToolManifest) -> str:
+    """Build download URL for the current platform.
+
+    Args:
+        manifest: Tool manifest with URL template.
+
+    Returns:
+        Fully resolved download URL.
+    """
+    system = platform.system()
+    machine = platform.machine().lower()
+
+    arch_map = {
+        "x86_64": "64bit",
+        "amd64": "64bit",
+        "aarch64": "ARM64",
+        "arm64": "ARM64",
+    }
+
+    # Tool-specific URL formatting
+    os_name = system
+    if manifest.name == "trivy":
+        os_name = system
+        arch = arch_map.get(machine, "64bit")
+    elif manifest.name == "semgrep":
+        os_name = system.lower()
+        arch = "x86_64" if machine in ("x86_64", "amd64") else "aarch64"
+    elif manifest.name == "gitleaks":
+        os_name = system.lower()
+        arch = "x64" if machine in ("x86_64", "amd64") else "arm64"
+    else:
+        arch = machine
+
+    return manifest.url_template.format(
+        version=manifest.version,
+        os=os_name,
+        arch=arch,
+    )
+
+
+# Hardcoded manifests with official GitHub release URLs
+# SHA256 checksums must be verified against official releases
+TOOL_MANIFESTS: dict[str, ToolManifest] = {
+    "trivy": ToolManifest(
+        name="trivy",
+        version="0.58.1",
+        url_template=(
+            "https://github.com/aquasecurity/trivy/releases/download/"
+            "v{version}/trivy_{version}_{os}-{arch}.tar.gz"
+        ),
+        sha256={
+            "linux_amd64": "01a6a89a6a8af9c830a1e6a762e42883e2ae68583514db81f5f2be3db3fb2ffc",
+            "linux_arm64": "c1a551eedd0a0e0f5024f76c64dea5e7fa7ac41d84b4ff4f1ee18ec0bf11174c",
+            "darwin_amd64": "8bca33df7022dfa76ea7ec03a2a19cfd86e2e6d8de8b94b5e70d9ab95f61c6e6",
+            "darwin_arm64": "a7dae5017cf898e6dce0b3fcefcb3e88b1f8fd78a38a54f1d6c12b8c2bb5d0f4",
+        },
+        binary_name="trivy",
+    ),
+    "semgrep": ToolManifest(
+        name="semgrep",
+        version="1.102.0",
+        url_template=(
+            "https://github.com/semgrep/semgrep/releases/download/"
+            "v{version}/semgrep-v{version}-{os}-{arch}.zip"
+        ),
+        sha256={
+            "linux_amd64": "placeholder_semgrep_linux_amd64",
+            "linux_arm64": "placeholder_semgrep_linux_arm64",
+            "darwin_amd64": "placeholder_semgrep_darwin_amd64",
+            "darwin_arm64": "placeholder_semgrep_darwin_arm64",
+        },
+        archive_type="zip",
+        binary_name="semgrep",
+    ),
+    "gitleaks": ToolManifest(
+        name="gitleaks",
+        version="8.21.2",
+        url_template=(
+            "https://github.com/gitleaks/gitleaks/releases/download/"
+            "v{version}/gitleaks_{version}_{os}_{arch}.tar.gz"
+        ),
+        sha256={
+            "linux_amd64": "placeholder_gitleaks_linux_amd64",
+            "linux_arm64": "placeholder_gitleaks_linux_arm64",
+            "darwin_amd64": "placeholder_gitleaks_darwin_amd64",
+            "darwin_arm64": "placeholder_gitleaks_darwin_arm64",
+        },
+        binary_name="gitleaks",
+    ),
+}
+
+
+def get_manifest(tool_name: str) -> ToolManifest | None:
+    """Get manifest for a tool.
+
+    Args:
+        tool_name: Name of the tool.
+
+    Returns:
+        ToolManifest if found, None otherwise.
+    """
+    return TOOL_MANIFESTS.get(tool_name)
+
+
+def get_expected_hash(manifest: ToolManifest) -> str | None:
+    """Get expected SHA256 hash for the current platform.
+
+    Args:
+        manifest: Tool manifest.
+
+    Returns:
+        Expected hash or None if platform not supported.
+    """
+    try:
+        platform_key = get_platform_key()
+        return manifest.sha256.get(platform_key)
+    except UnsupportedPlatformError:
+        return None
+
+
+def validate_manifest_url(url: str) -> bool:
+    """Validate that URL is from an allowed domain.
+
+    Only official GitHub releases are allowed.
+
+    Args:
+        url: URL to validate.
+
+    Returns:
+        True if URL is from allowed domain.
+    """
+    allowed_patterns = [
+        r"^https://github\.com/aquasecurity/trivy/releases/download/",
+        r"^https://github\.com/semgrep/semgrep/releases/download/",
+        r"^https://github\.com/gitleaks/gitleaks/releases/download/",
+    ]
+    return any(re.match(pattern, url) for pattern in allowed_patterns)

kekkai/installer/verify.py

@@ -0,0 +1,86 @@
+"""Cryptographic verification for downloaded binaries."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from pathlib import Path
+
+from .errors import SecurityError
+
+logger = logging.getLogger(__name__)
+
+# Maximum file size for downloads (100MB)
+MAX_DOWNLOAD_SIZE = 100 * 1024 * 1024
+
+
+def compute_sha256(data: bytes) -> str:
+    """Compute SHA256 hash of data.
+
+    Args:
+        data: Bytes to hash.
+
+    Returns:
+        Hex-encoded SHA256 hash.
+    """
+    return hashlib.sha256(data).hexdigest()
+
+
+def compute_sha256_file(file_path: Path) -> str:
+    """Compute SHA256 hash of a file.
+
+    Args:
+        file_path: Path to file.
+
+    Returns:
+        Hex-encoded SHA256 hash.
+    """
+    sha256 = hashlib.sha256()
+    with open(file_path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256.update(chunk)
+    return sha256.hexdigest()
+
+
+def verify_checksum(data: bytes, expected_hash: str, tool_name: str) -> None:
+    """Verify SHA256 checksum of downloaded data.
+
+    Args:
+        data: Downloaded bytes.
+        expected_hash: Expected SHA256 hash (hex-encoded).
+        tool_name: Name of tool (for error messages).
+
+    Raises:
+        SecurityError: If checksum doesn't match.
+    """
+    actual_hash = compute_sha256(data)
+
+    if actual_hash != expected_hash:
+        logger.error(
+            "Checksum mismatch for %s: expected %s..., got %s...",
+            tool_name,
+            expected_hash[:16],
+            actual_hash[:16],
+        )
+        raise SecurityError(
+            f"Checksum mismatch for {tool_name}: "
+            f"expected {expected_hash[:16]}..., got {actual_hash[:16]}..."
+        )
+
+    logger.info("Checksum verified for %s: %s", tool_name, actual_hash[:16])
+
+
+def verify_file_size(size: int, tool_name: str) -> None:
+    """Verify file size is within limits.
+
+    Args:
+        size: File size in bytes.
+        tool_name: Name of tool (for error messages).
+
+    Raises:
+        SecurityError: If file exceeds size limit.
+    """
+    if size > MAX_DOWNLOAD_SIZE:
+        raise SecurityError(
+            f"Download size {size} exceeds maximum {MAX_DOWNLOAD_SIZE} for {tool_name}"
+        )

kekkai/manifest.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .runner import StepResult
+
+
+@dataclass(frozen=True)
+class ScannerManifestEntry:
+    """Manifest entry for a scanner execution."""
+
+    name: str
+    backend: str
+    success: bool
+    finding_count: int
+    duration_ms: int
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class RunManifest:
+    schema_version: int
+    run_id: str
+    repo_path: str
+    run_dir: str
+    started_at: str
+    finished_at: str
+    status: str
+    steps: list[dict[str, object]]
+    scanners: list[dict[str, object]] | None = None
+
+
+def build_manifest(
+    *,
+    run_id: str,
+    repo_path: Path,
+    run_dir: Path,
+    started_at: str,
+    finished_at: str,
+    steps: Iterable[StepResult],
+    scanners: Iterable[ScannerManifestEntry] | None = None,
+) -> RunManifest:
+    step_entries = [
+        {
+            "name": step.name,
+            "args": step.args,
+            "exit_code": step.exit_code,
+            "duration_ms": step.duration_ms,
+            "stdout": step.stdout,
+            "stderr": step.stderr,
+            "timed_out": step.timed_out,
+        }
+        for step in steps
+    ]
+    scanner_entries = None
+    if scanners is not None:
+        scanner_entries = [asdict(s) for s in scanners]
+
+    status = "success" if all(step["exit_code"] == 0 for step in step_entries) else "failed"
+    return RunManifest(
+        schema_version=2,
+        run_id=run_id,
+        repo_path=str(repo_path),
+        run_dir=str(run_dir),
+        started_at=started_at,
+        finished_at=finished_at,
+        status=status,
+        steps=step_entries,
+        scanners=scanner_entries,
+    )
+
+
+def write_manifest(path: Path, manifest: RunManifest) -> None:
+    path.write_text(json.dumps(asdict(manifest), indent=2, sort_keys=True))