kekkai-cli 1.0.0__py3-none-any.whl

kekkai/scanners/__init__.py

@@ -0,0 +1,67 @@
+from .backends import (
+    BackendType,
+    DockerBackend,
+    NativeBackend,
+    ScannerBackend,
+    ToolNotFoundError,
+    ToolVersionError,
+    detect_tool,
+    docker_available,
+)
+from .base import (
+    Finding,
+    ScanContext,
+    Scanner,
+    ScanResult,
+    Severity,
+    dedupe_findings,
+)
+from .falco import FalcoScanner, create_falco_scanner
+from .gitleaks import GitleaksScanner
+from .semgrep import SemgrepScanner
+from .trivy import TrivyScanner
+from .url_policy import UrlPolicy, UrlPolicyError, validate_target_url
+from .zap import ZapScanner, create_zap_scanner
+
+# Core scanners (SAST/SCA) - always available
+SCANNER_REGISTRY: dict[str, type] = {
+    "trivy": TrivyScanner,
+    "semgrep": SemgrepScanner,
+    "gitleaks": GitleaksScanner,
+}
+
+# Optional scanners (DAST/runtime) - require explicit configuration
+# These are NOT in the default registry to prevent accidental use
+OPTIONAL_SCANNERS: dict[str, type] = {
+    "zap": ZapScanner,
+    "falco": FalcoScanner,
+}
+
+__all__ = [
+    "BackendType",
+    "create_falco_scanner",
+    "create_zap_scanner",
+    "dedupe_findings",
+    "detect_tool",
+    "docker_available",
+    "DockerBackend",
+    "FalcoScanner",
+    "Finding",
+    "GitleaksScanner",
+    "NativeBackend",
+    "OPTIONAL_SCANNERS",
+    "ScanContext",
+    "ScannerBackend",
+    "ScanResult",
+    "Scanner",
+    "SCANNER_REGISTRY",
+    "SemgrepScanner",
+    "Severity",
+    "ToolNotFoundError",
+    "ToolVersionError",
+    "TrivyScanner",
+    "UrlPolicy",
+    "UrlPolicyError",
+    "validate_target_url",
+    "ZapScanner",
+]

kekkai/scanners/backends/__init__.py

@@ -0,0 +1,14 @@
+from .base import BackendType, ScannerBackend
+from .docker import DockerBackend, docker_available
+from .native import NativeBackend, ToolNotFoundError, ToolVersionError, detect_tool
+
+__all__ = [
+    "BackendType",
+    "detect_tool",
+    "docker_available",
+    "DockerBackend",
+    "NativeBackend",
+    "ScannerBackend",
+    "ToolNotFoundError",
+    "ToolVersionError",
+]

kekkai/scanners/backends/base.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+
+class BackendType(str, Enum):
+    DOCKER = "docker"
+    NATIVE = "native"
+
+
+@dataclass(frozen=True)
+class ExecutionResult:
+    """Result of executing a scanner command."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_ms: int
+    timed_out: bool
+    backend: BackendType
+
+
+class ScannerBackend(ABC):
+    """Abstract base class for scanner execution backends."""
+
+    @property
+    @abstractmethod
+    def backend_type(self) -> BackendType:
+        """Return the backend type."""
+        ...
+
+    @abstractmethod
+    def is_available(self) -> tuple[bool, str]:
+        """Check if this backend is available.
+
+        Returns:
+            Tuple of (available, reason)
+        """
+        ...
+
+    @abstractmethod
+    def execute(
+        self,
+        tool: str,
+        args: list[str],
+        repo_path: Path,
+        output_path: Path,
+        timeout_seconds: int = 600,
+        env: dict[str, str] | None = None,
+        network_required: bool = False,
+    ) -> ExecutionResult:
+        """Execute a scanner tool.
+
+        Args:
+            tool: Tool name or image reference
+            args: Command arguments
+            repo_path: Path to repository to scan
+            output_path: Path for output files
+            timeout_seconds: Execution timeout
+            env: Environment variables to pass
+            network_required: Whether network access is needed
+
+        Returns:
+            ExecutionResult with output and status
+        """
+        ...

kekkai/scanners/backends/docker.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import shutil
+import subprocess  # nosec B404
+import time
+from pathlib import Path
+
+from .base import BackendType, ExecutionResult, ScannerBackend
+
+_docker_available_cache: tuple[bool, str] | None = None
+
+
+def docker_available(force_check: bool = False) -> tuple[bool, str]:
+    """Check if Docker is available and running.
+
+    Args:
+        force_check: Bypass cache and re-check
+
+    Returns:
+        Tuple of (available, reason)
+    """
+    global _docker_available_cache
+
+    if _docker_available_cache is not None and not force_check:
+        return _docker_available_cache
+
+    docker_path = shutil.which("docker")
+    if not docker_path:
+        _docker_available_cache = (False, "Docker not found in PATH")
+        return _docker_available_cache
+
+    try:
+        result = subprocess.run(  # noqa: S603  # nosec B603
+            [docker_path, "info"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+        if result.returncode == 0:
+            _docker_available_cache = (True, "Docker available")
+            return _docker_available_cache
+        _docker_available_cache = (False, f"Docker not running: {result.stderr.strip()}")
+        return _docker_available_cache
+    except subprocess.TimeoutExpired:
+        _docker_available_cache = (False, "Docker info timed out")
+        return _docker_available_cache
+    except OSError as e:
+        _docker_available_cache = (False, f"Docker error: {e}")
+        return _docker_available_cache
+
+
+class DockerBackend(ScannerBackend):
+    """Docker-based scanner execution backend."""
+
+    def __init__(
+        self,
+        read_only: bool = True,
+        no_new_privileges: bool = True,
+        memory_limit: str = "2g",
+        cpu_limit: str = "2",
+    ) -> None:
+        self._read_only = read_only
+        self._no_new_privileges = no_new_privileges
+        self._memory_limit = memory_limit
+        self._cpu_limit = cpu_limit
+
+    @property
+    def backend_type(self) -> BackendType:
+        return BackendType.DOCKER
+
+    def is_available(self) -> tuple[bool, str]:
+        return docker_available()
+
+    def execute(
+        self,
+        tool: str,
+        args: list[str],
+        repo_path: Path,
+        output_path: Path,
+        timeout_seconds: int = 600,
+        env: dict[str, str] | None = None,
+        network_required: bool = False,
+        skip_repo_mount: bool = False,
+        workdir: str | None = None,
+        output_mount: str | None = None,
+        user: str | None = "1000:1000",
+    ) -> ExecutionResult:
+        """Execute scanner in Docker container.
+
+        Args:
+            tool: Docker image reference (e.g., "aquasec/trivy:latest")
+            args: Command arguments to run in container
+            repo_path: Path to repository (mounted read-only at /repo)
+            output_path: Path for output (mounted read-write at /output)
+            timeout_seconds: Execution timeout
+            env: Environment variables
+            network_required: Whether to allow network access
+            skip_repo_mount: Skip mounting repo (for DAST scanners)
+            workdir: Override working directory
+            output_mount: Override output mount point
+            user: User to run as (default: 1000:1000)
+        """
+        docker_path = shutil.which("docker")
+        if not docker_path:
+            return ExecutionResult(
+                exit_code=127,
+                stdout="",
+                stderr="Docker not found",
+                duration_ms=0,
+                timed_out=False,
+                backend=self.backend_type,
+            )
+
+        cmd = [docker_path, "run", "--rm"]
+
+        if user:
+            cmd.extend(["--user", user])
+
+        if self._read_only:
+            cmd.extend(["--read-only", "--tmpfs", "/tmp:rw,noexec,nosuid,size=512m"])  # nosec B108  # noqa: S108
+
+        if not network_required:
+            cmd.extend(["--network", "none"])
+
+        if self._no_new_privileges:
+            cmd.append("--security-opt=no-new-privileges")
+
+        if self._memory_limit:
+            cmd.extend(["--memory", self._memory_limit])
+
+        if self._cpu_limit:
+            cmd.extend(["--cpus", self._cpu_limit])
+
+        if not skip_repo_mount:
+            cmd.extend(["-v", f"{repo_path.resolve()}:/repo:ro"])
+
+        mount_point = output_mount or "/output"
+        cmd.extend(["-v", f"{output_path.resolve()}:{mount_point}:rw"])
+        cmd.extend(["-w", workdir or "/repo"])
+
+        if env:
+            for key, value in env.items():
+                cmd.extend(["-e", f"{key}={value}"])
+
+        cmd.append(tool)
+        cmd.extend(args)
+
+        start = time.monotonic()
+        try:
+            proc = subprocess.run(  # noqa: S603  # nosec B603
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout_seconds,
+                check=False,
+            )
+            duration_ms = int((time.monotonic() - start) * 1000)
+            return ExecutionResult(
+                exit_code=proc.returncode,
+                stdout=proc.stdout,
+                stderr=proc.stderr,
+                duration_ms=duration_ms,
+                timed_out=False,
+                backend=self.backend_type,
+            )
+        except subprocess.TimeoutExpired as exc:
+            duration_ms = int((time.monotonic() - start) * 1000)
+            stdout = exc.stdout.decode() if isinstance(exc.stdout, bytes) else (exc.stdout or "")
+            stderr = exc.stderr.decode() if isinstance(exc.stderr, bytes) else (exc.stderr or "")
+            return ExecutionResult(
+                exit_code=124,
+                stdout=stdout,
+                stderr=stderr,
+                duration_ms=duration_ms,
+                timed_out=True,
+                backend=self.backend_type,
+            )

kekkai/scanners/backends/native.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess  # nosec B404
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .base import BackendType, ExecutionResult, ScannerBackend
+
+if TYPE_CHECKING:
+    pass
+
+
+class ToolNotFoundError(RuntimeError):
+    """Raised when a required tool is not found in PATH."""
+
+
+class ToolVersionError(RuntimeError):
+    """Raised when tool version doesn't meet requirements."""
+
+
+@dataclass(frozen=True)
+class ToolInfo:
+    """Information about a detected tool."""
+
+    name: str
+    path: str
+    version: str
+    version_tuple: tuple[int, ...]
+
+
+# Minimum versions required for native execution
+MIN_VERSIONS: dict[str, tuple[int, ...]] = {
+    "trivy": (0, 40, 0),
+    "semgrep": (1, 50, 0),
+    "gitleaks": (8, 18, 0),
+    "zap-cli": (0, 10, 0),
+    "falco": (0, 35, 0),
+}
+
+# Version extraction patterns
+VERSION_PATTERNS: dict[str, re.Pattern[str]] = {
+    "trivy": re.compile(r"Version:\s*(\d+\.\d+\.\d+)"),
+    "semgrep": re.compile(r"(\d+\.\d+\.\d+)"),
+    "gitleaks": re.compile(r"v?(\d+\.\d+\.\d+)"),
+    "zap-cli": re.compile(r"(\d+\.\d+\.\d+)"),
+    "falco": re.compile(r"(\d+\.\d+\.\d+)"),
+}
+
+
+def _parse_version(version_str: str) -> tuple[int, ...]:
+    """Parse version string to tuple of integers."""
+    parts = version_str.split(".")
+    result: list[int] = []
+    for part in parts:
+        try:
+            result.append(int(part))
+        except ValueError:
+            break
+    return tuple(result) if result else (0,)
+
+
+def detect_tool(
+    name: str,
+    min_version: tuple[int, ...] | None = None,
+    version_args: list[str] | None = None,
+) -> ToolInfo:
+    """Detect a tool in PATH and validate its version.
+
+    Args:
+        name: Tool name to search for
+        min_version: Minimum required version tuple (e.g., (0, 40, 0))
+        version_args: Arguments to get version (default: ["--version"])
+
+    Returns:
+        ToolInfo with path and version details
+
+    Raises:
+        ToolNotFoundError: If tool not found in PATH
+        ToolVersionError: If version doesn't meet minimum requirement
+    """
+    tool_path = shutil.which(name)
+
+    # Also check ~/.kekkai/bin/ for installed tools
+    if not tool_path:
+        from kekkai.paths import bin_dir
+
+        kekkai_bin = bin_dir() / name
+        if kekkai_bin.exists() and os.access(kekkai_bin, os.X_OK):
+            tool_path = str(kekkai_bin)
+
+    if not tool_path:
+        raise ToolNotFoundError(f"{name} not found in PATH")
+
+    tool_path = os.path.realpath(tool_path)
+    if not os.path.isfile(tool_path):
+        raise ToolNotFoundError(f"{name} path is not a file: {tool_path}")
+    if not os.access(tool_path, os.X_OK):
+        raise ToolNotFoundError(f"{name} is not executable: {tool_path}")
+
+    version_cmd = version_args or ["--version"]
+    try:
+        result = subprocess.run(  # noqa: S603  # nosec B603
+            [tool_path, *version_cmd],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+        version_output = result.stdout + result.stderr
+    except (subprocess.TimeoutExpired, OSError) as e:
+        raise ToolVersionError(f"Failed to get {name} version: {e}") from e
+
+    pattern = VERSION_PATTERNS.get(name, re.compile(r"(\d+\.\d+\.\d+)"))
+    match = pattern.search(version_output)
+    if not match:
+        raise ToolVersionError(f"Could not parse {name} version from: {version_output[:200]}")
+
+    version_str = match.group(1)
+    version_tuple = _parse_version(version_str)
+
+    min_ver = min_version or MIN_VERSIONS.get(name)
+    if min_ver and version_tuple < min_ver:
+        min_ver_str = ".".join(str(v) for v in min_ver)
+        raise ToolVersionError(f"{name} version {version_str} is below minimum {min_ver_str}")
+
+    return ToolInfo(
+        name=name,
+        path=tool_path,
+        version=version_str,
+        version_tuple=version_tuple,
+    )
+
+
+class NativeBackend(ScannerBackend):
+    """Native binary scanner execution backend."""
+
+    def __init__(self, env_allowlist: list[str] | None = None) -> None:
+        self._env_allowlist = env_allowlist or [
+            "PATH",
+            "HOME",
+            "USER",
+            "LANG",
+            "LC_ALL",
+            "TMPDIR",
+            "XDG_CONFIG_HOME",
+            "XDG_CACHE_HOME",
+        ]
+
+    @property
+    def backend_type(self) -> BackendType:
+        return BackendType.NATIVE
+
+    def is_available(self) -> tuple[bool, str]:
+        return (True, "Native execution always available")
+
+    def execute(
+        self,
+        tool: str,
+        args: list[str],
+        repo_path: Path,
+        output_path: Path,
+        timeout_seconds: int = 600,
+        env: dict[str, str] | None = None,
+        network_required: bool = False,
+    ) -> ExecutionResult:
+        """Execute scanner tool natively.
+
+        Args:
+            tool: Tool name (will be resolved via PATH)
+            args: Command arguments (must be list, no shell expansion)
+            repo_path: Path to repository to scan
+            output_path: Path for output files
+            timeout_seconds: Execution timeout
+            env: Additional environment variables
+            network_required: Ignored for native execution (always has network)
+        """
+        if not isinstance(args, list):
+            return ExecutionResult(
+                exit_code=1,
+                stdout="",
+                stderr="Arguments must be a list (no shell expansion)",
+                duration_ms=0,
+                timed_out=False,
+                backend=self.backend_type,
+            )
+
+        tool_path = shutil.which(tool)
+        if not tool_path:
+            return ExecutionResult(
+                exit_code=127,
+                stdout="",
+                stderr=f"Tool not found: {tool}",
+                duration_ms=0,
+                timed_out=False,
+                backend=self.backend_type,
+            )
+
+        safe_env = {key: os.environ[key] for key in self._env_allowlist if key in os.environ}
+        if env:
+            safe_env.update(env)
+
+        cmd = [tool_path, *args]
+
+        start = time.monotonic()
+        try:
+            proc = subprocess.run(  # noqa: S603  # nosec B603
+                cmd,
+                cwd=str(repo_path),
+                env=safe_env,
+                capture_output=True,
+                text=True,
+                timeout=timeout_seconds,
+                check=False,
+            )
+            duration_ms = int((time.monotonic() - start) * 1000)
+            return ExecutionResult(
+                exit_code=proc.returncode,
+                stdout=proc.stdout,
+                stderr=proc.stderr,
+                duration_ms=duration_ms,
+                timed_out=False,
+                backend=self.backend_type,
+            )
+        except subprocess.TimeoutExpired as exc:
+            duration_ms = int((time.monotonic() - start) * 1000)
+            stdout = exc.stdout.decode() if isinstance(exc.stdout, bytes) else (exc.stdout or "")
+            stderr = exc.stderr.decode() if isinstance(exc.stderr, bytes) else (exc.stderr or "")
+            return ExecutionResult(
+                exit_code=124,
+                stdout=stdout,
+                stderr=stderr,
+                duration_ms=duration_ms,
+                timed_out=True,
+                backend=self.backend_type,
+            )

kekkai/scanners/base.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_string(cls, value: str) -> Severity:
+        normalized = value.lower().strip()
+        mapping = {
+            "critical": cls.CRITICAL,
+            "high": cls.HIGH,
+            "medium": cls.MEDIUM,
+            "moderate": cls.MEDIUM,
+            "low": cls.LOW,
+            "info": cls.INFO,
+            "informational": cls.INFO,
+            "warning": cls.LOW,
+        }
+        return mapping.get(normalized, cls.UNKNOWN)
+
+
+@dataclass(frozen=True)
+class Finding:
+    scanner: str
+    title: str
+    severity: Severity
+    description: str
+    file_path: str | None = None
+    line: int | None = None
+    rule_id: str | None = None
+    cwe: str | None = None
+    cve: str | None = None
+    package_name: str | None = None
+    package_version: str | None = None
+    fixed_version: str | None = None
+    extra: dict[str, str] = field(default_factory=dict)
+
+    def dedupe_hash(self) -> str:
+        parts = [
+            self.scanner,
+            self.title,
+            self.file_path or "",
+            str(self.line or ""),
+            self.rule_id or "",
+            self.cve or "",
+            self.package_name or "",
+            self.package_version or "",
+        ]
+        content = "|".join(parts)
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class ScanContext:
+    repo_path: Path
+    output_dir: Path
+    run_id: str
+    commit_sha: str | None = None
+    timeout_seconds: int = 600
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    scanner: str
+    success: bool
+    findings: list[Finding]
+    raw_output_path: Path | None = None
+    error: str | None = None
+    duration_ms: int = 0
+
+
+@runtime_checkable
+class Scanner(Protocol):
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def scan_type(self) -> str:
+        """DefectDojo scan type for import."""
+        ...
+
+    def run(self, ctx: ScanContext) -> ScanResult: ...
+
+    def parse(self, raw_output: str) -> list[Finding]: ...
+
+
+def dedupe_findings(findings: Sequence[Finding]) -> list[Finding]:
+    seen: set[str] = set()
+    result: list[Finding] = []
+    for f in findings:
+        h = f.dedupe_hash()
+        if h not in seen:
+            seen.add(h)
+            result.append(f)
+    return result