kekkai-cli 1.0.0__py3-none-any.whl

kekkai/scanners/container.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import shutil
+import subprocess  # nosec B404
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_TIMEOUT = 600
+
+
+@dataclass(frozen=True)
+class ContainerConfig:
+    image: str
+    image_digest: str | None = None
+    read_only: bool = True
+    network_disabled: bool = True
+    no_new_privileges: bool = True
+    memory_limit: str = "2g"
+    cpu_limit: str = "2"
+
+
+@dataclass(frozen=True)
+class ContainerResult:
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_ms: int
+    timed_out: bool
+
+
+def docker_command() -> str:
+    docker = shutil.which("docker")
+    if not docker:
+        raise RuntimeError("Docker not found; install docker to run scanners")
+    return docker
+
+
+def run_container(
+    config: ContainerConfig,
+    repo_path: Path,
+    output_path: Path,
+    command: list[str],
+    timeout_seconds: int = DEFAULT_TIMEOUT,
+    workdir: str | None = None,
+    output_mount: str | None = None,
+    skip_repo_mount: bool = False,
+    user: str | None = "1000:1000",
+) -> ContainerResult:
+    """Run a command in a Docker container with security controls.
+
+    Args:
+        config: Container configuration (image, security settings)
+        repo_path: Path to repository to mount (read-only)
+        output_path: Path for output files (read-write)
+        command: Command and arguments to run
+        timeout_seconds: Timeout for container execution
+        workdir: Override working directory (default: /repo)
+        output_mount: Override output mount point (default: /output)
+        skip_repo_mount: Skip mounting repo (for DAST scanners)
+        user: User to run as (default: 1000:1000, None for container default)
+    """
+    docker = docker_command()
+    image_ref = f"{config.image}@{config.image_digest}" if config.image_digest else config.image
+
+    args = [
+        docker,
+        "run",
+        "--rm",
+    ]
+
+    if user:
+        args.extend(["--user", user])
+
+    if config.read_only:
+        args.extend(["--read-only", "--tmpfs", "/tmp:rw,noexec,nosuid,size=512m"])  # nosec B108  # noqa: S108
+
+    if config.network_disabled:
+        args.extend(["--network", "none"])
+
+    if config.no_new_privileges:
+        args.append("--security-opt=no-new-privileges")
+
+    if config.memory_limit:
+        args.extend(["--memory", config.memory_limit])
+
+    if config.cpu_limit:
+        args.extend(["--cpus", config.cpu_limit])
+
+    # Mount repository (optional for DAST scanners)
+    if not skip_repo_mount:
+        args.extend(["-v", f"{repo_path.resolve()}:/repo:ro"])
+
+    # Mount output directory
+    mount_point = output_mount or "/output"
+    args.extend(["-v", f"{output_path.resolve()}:{mount_point}:rw"])
+
+    # Set working directory
+    args.extend(["-w", workdir or "/repo"])
+
+    args.append(image_ref)
+    args.extend(command)
+
+    start = time.monotonic()
+    try:
+        proc = subprocess.run(  # noqa: S603  # nosec B603
+            args,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            check=False,
+        )
+        duration_ms = int((time.monotonic() - start) * 1000)
+        return ContainerResult(
+            exit_code=proc.returncode,
+            stdout=proc.stdout,
+            stderr=proc.stderr,
+            duration_ms=duration_ms,
+            timed_out=False,
+        )
+    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 ContainerResult(
+            exit_code=124,
+            stdout=stdout,
+            stderr=stderr,
+            duration_ms=duration_ms,
+            timed_out=True,
+        )
+
+
+def pull_image(image: str, digest: str | None = None) -> bool:
+    docker = docker_command()
+    ref = f"{image}@{digest}" if digest else image
+    proc = subprocess.run(  # noqa: S603  # nosec B603
+        [docker, "pull", ref],
+        capture_output=True,
+        text=True,
+        timeout=300,
+        check=False,
+    )
+    return proc.returncode == 0

kekkai/scanners/falco.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import json
+import platform
+from pathlib import Path
+from typing import Any
+
+from .backends import (
+    BackendType,
+    ToolNotFoundError,
+    ToolVersionError,
+    detect_tool,
+)
+from .base import Finding, ScanContext, ScanResult, Severity
+
+SCAN_TYPE = "Falco Scan"
+
+
+class FalcoNotAvailableError(RuntimeError):
+    """Raised when Falco is not available or not enabled."""
+
+
+class FalcoScanner:
+    """Falco runtime security scanner adapter.
+
+    EXPERIMENTAL: Linux-only scanner that monitors runtime behavior.
+    Requires explicit opt-in via --enable-falco flag.
+
+    Security notes:
+    - Falco requires kernel access (eBPF or kernel module)
+    - Should only be used in controlled environments
+    - Requires elevated privileges on the host
+
+    Note: Falco only runs in native mode (no Docker container support)
+    as it requires direct kernel access.
+    """
+
+    def __init__(
+        self,
+        enabled: bool = False,
+        rules_file: Path | None = None,
+        timeout_seconds: int = 300,
+        backend: BackendType | None = None,
+    ) -> None:
+        self._enabled = enabled
+        self._rules_file = rules_file
+        self._timeout = timeout_seconds
+        self._backend = backend
+        self._resolved_backend: BackendType | None = None
+
+    @property
+    def name(self) -> str:
+        return "falco"
+
+    @property
+    def scan_type(self) -> str:
+        return SCAN_TYPE
+
+    @property
+    def backend_used(self) -> BackendType | None:
+        """Return the backend used for the last scan."""
+        return self._resolved_backend
+
+    def is_available(self) -> tuple[bool, str]:
+        """Check if Falco is available and can be run.
+
+        Returns:
+            Tuple of (available, reason)
+        """
+        if platform.system() != "Linux":
+            return False, "Falco is Linux-only (experimental)"
+
+        if not self._enabled:
+            return False, "Falco requires explicit --enable-falco flag"
+
+        try:
+            detect_tool("falco", min_version=(0, 35, 0))
+            return True, "Falco available"
+        except ToolNotFoundError:
+            return False, "Falco binary not found in PATH"
+        except ToolVersionError as e:
+            return False, str(e)
+
+    def run(self, ctx: ScanContext) -> ScanResult:
+        """Run Falco scanner.
+
+        Note: Falco is designed for continuous monitoring. This adapter
+        runs Falco in a one-shot mode to analyze existing log files or
+        capture events for a limited duration.
+
+        Falco always runs in native mode (requires kernel access).
+        """
+        self._resolved_backend = BackendType.NATIVE
+
+        available, reason = self.is_available()
+        if not available:
+            return ScanResult(
+                scanner=self.name,
+                success=False,
+                findings=[],
+                error=f"Falco not available: {reason}",
+                duration_ms=0,
+            )
+
+        existing_alerts = self._find_alerts_file(ctx)
+        if existing_alerts:
+            try:
+                findings = self.parse(existing_alerts.read_text())
+                return ScanResult(
+                    scanner=self.name,
+                    success=True,
+                    findings=findings,
+                    raw_output_path=existing_alerts,
+                    duration_ms=0,
+                )
+            except (json.JSONDecodeError, KeyError) as exc:
+                return ScanResult(
+                    scanner=self.name,
+                    success=False,
+                    findings=[],
+                    error=f"Parse error: {exc}",
+                    duration_ms=0,
+                )
+
+        return ScanResult(
+            scanner=self.name,
+            success=True,
+            findings=[],
+            error=None,
+            duration_ms=0,
+        )
+
+    def _find_alerts_file(self, ctx: ScanContext) -> Path | None:
+        """Find existing Falco alerts file."""
+        candidates = [
+            ctx.output_dir / "falco-alerts.json",
+            ctx.repo_path / "falco-alerts.json",
+            Path("/var/log/falco/alerts.json"),
+        ]
+        for path in candidates:
+            if path.exists():
+                return path
+        return None
+
+    def parse(self, raw_output: str) -> list[Finding]:
+        """Parse Falco JSON alerts to Finding objects.
+
+        Falco outputs one JSON object per line (JSONL format).
+        """
+        findings: list[Finding] = []
+
+        for line in raw_output.strip().split("\n"):
+            if not line.strip():
+                continue
+            try:
+                alert = json.loads(line)
+                findings.append(self._parse_alert(alert))
+            except json.JSONDecodeError:
+                continue
+
+        return findings
+
+    def _parse_alert(self, alert: dict[str, Any]) -> Finding:
+        """Parse a single Falco alert to a Finding."""
+        priority = alert.get("priority", "").lower()
+        severity = self._map_priority_to_severity(priority)
+
+        # Extract relevant fields
+        output = alert.get("output", "")
+        rule = alert.get("rule", "Unknown Rule")
+
+        # Get output fields for additional context
+        output_fields = alert.get("output_fields", {})
+        container_id = output_fields.get("container.id", "")
+        container_name = output_fields.get("container.name", "")
+        process = output_fields.get("proc.name", "")
+        cmdline = output_fields.get("proc.cmdline", "")
+
+        description_parts = [output]
+        if process:
+            description_parts.append(f"Process: {process}")
+        if cmdline:
+            description_parts.append(f"Command: {cmdline}")
+        if container_name:
+            description_parts.append(f"Container: {container_name}")
+
+        return Finding(
+            scanner=self.name,
+            title=rule,
+            severity=severity,
+            description="\n".join(description_parts),
+            file_path=container_id or None,
+            rule_id=rule,
+            extra={
+                "priority": priority,
+                "container_id": container_id,
+                "container_name": container_name,
+                "process": process,
+                "time": alert.get("time", ""),
+            },
+        )
+
+    def _map_priority_to_severity(self, priority: str) -> Severity:
+        """Map Falco priority to Severity."""
+        mapping = {
+            "emergency": Severity.CRITICAL,
+            "alert": Severity.CRITICAL,
+            "critical": Severity.CRITICAL,
+            "error": Severity.HIGH,
+            "warning": Severity.MEDIUM,
+            "notice": Severity.LOW,
+            "informational": Severity.INFO,
+            "debug": Severity.INFO,
+        }
+        return mapping.get(priority.lower(), Severity.UNKNOWN)
+
+
+def create_falco_scanner(
+    enabled: bool = False,
+    rules_file: Path | None = None,
+    timeout_seconds: int = 300,
+) -> FalcoScanner:
+    """Factory function to create a Falco scanner.
+
+    Args:
+        enabled: Whether Falco scanning is enabled (requires explicit opt-in)
+        rules_file: Optional custom rules file
+        timeout_seconds: Scan timeout
+
+    Returns:
+        Configured FalcoScanner instance
+    """
+    return FalcoScanner(
+        enabled=enabled,
+        rules_file=rules_file,
+        timeout_seconds=timeout_seconds,
+    )

kekkai/scanners/gitleaks.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .backends import (
+    BackendType,
+    NativeBackend,
+    ToolNotFoundError,
+    ToolVersionError,
+    detect_tool,
+    docker_available,
+)
+from .base import Finding, ScanContext, ScanResult, Severity
+from .container import ContainerConfig, run_container
+
+GITLEAKS_IMAGE = "zricethezav/gitleaks"
+GITLEAKS_DIGEST = "sha256:691af3c7c5a48b16f187ce3446d5f194838f91238f27270ed36eef6359a574d9"
+SCAN_TYPE = "Gitleaks Scan"
+
+
+class GitleaksScanner:
+    def __init__(
+        self,
+        image: str = GITLEAKS_IMAGE,
+        digest: str | None = GITLEAKS_DIGEST,
+        timeout_seconds: int = 300,
+        backend: BackendType | None = None,
+    ) -> None:
+        self._image = image
+        self._digest = digest
+        self._timeout = timeout_seconds
+        self._backend = backend
+        self._resolved_backend: BackendType | None = None
+
+    @property
+    def name(self) -> str:
+        return "gitleaks"
+
+    @property
+    def scan_type(self) -> str:
+        return SCAN_TYPE
+
+    @property
+    def backend_used(self) -> BackendType | None:
+        """Return the backend used for the last scan."""
+        return self._resolved_backend
+
+    def _select_backend(self) -> BackendType:
+        """Select backend: explicit choice, or auto-detect (Docker preferred)."""
+        if self._backend is not None:
+            return self._backend
+
+        available, _ = docker_available()
+        if available:
+            return BackendType.DOCKER
+
+        try:
+            detect_tool("gitleaks")
+            return BackendType.NATIVE
+        except (ToolNotFoundError, ToolVersionError):
+            return BackendType.DOCKER
+
+    def run(self, ctx: ScanContext) -> ScanResult:
+        backend = self._select_backend()
+        self._resolved_backend = backend
+
+        if backend == BackendType.NATIVE:
+            return self._run_native(ctx)
+        return self._run_docker(ctx)
+
+    def _run_docker(self, ctx: ScanContext) -> ScanResult:
+        """Run Gitleaks in Docker container."""
+        output_file = ctx.output_dir / "gitleaks-results.json"
+        config = ContainerConfig(
+            image=self._image,
+            image_digest=self._digest,
+            read_only=True,
+            network_disabled=True,
+            no_new_privileges=True,
+        )
+
+        command = [
+            "detect",
+            "--source",
+            "/repo",
+            "--report-format",
+            "json",
+            "--report-path",
+            "/output/gitleaks-results.json",
+            "--exit-code",
+            "0",
+        ]
+
+        result = run_container(
+            config=config,
+            repo_path=ctx.repo_path,
+            output_path=ctx.output_dir,
+            command=command,
+            timeout_seconds=self._timeout,
+        )
+
+        return self._process_result(
+            result.timed_out, result.exit_code, result.duration_ms, result.stderr, output_file
+        )
+
+    def _run_native(self, ctx: ScanContext) -> ScanResult:
+        """Run Gitleaks natively."""
+        try:
+            tool_info = detect_tool("gitleaks")
+        except (ToolNotFoundError, ToolVersionError) as e:
+            return ScanResult(
+                scanner=self.name,
+                success=False,
+                findings=[],
+                error=str(e),
+                duration_ms=0,
+            )
+
+        output_file = ctx.output_dir / "gitleaks-results.json"
+        backend = NativeBackend()
+
+        args = [
+            "detect",
+            "--source",
+            str(ctx.repo_path),
+            "--report-format",
+            "json",
+            "--report-path",
+            str(output_file),
+            "--exit-code",
+            "0",
+        ]
+
+        result = backend.execute(
+            tool=tool_info.path,
+            args=args,
+            repo_path=ctx.repo_path,
+            output_path=ctx.output_dir,
+            timeout_seconds=self._timeout,
+            network_required=False,
+        )
+
+        return self._process_result(
+            result.timed_out, result.exit_code, result.duration_ms, result.stderr, output_file
+        )
+
+    def _process_result(
+        self, timed_out: bool, exit_code: int, duration_ms: int, stderr: str, output_file: Path
+    ) -> ScanResult:
+        """Process scan result from either backend."""
+        if timed_out:
+            return ScanResult(
+                scanner=self.name,
+                success=False,
+                findings=[],
+                error="Scan timed out",
+                duration_ms=duration_ms,
+            )
+
+        if not output_file.exists():
+            if exit_code == 0:
+                return ScanResult(
+                    scanner=self.name,
+                    success=True,
+                    findings=[],
+                    duration_ms=duration_ms,
+                )
+            return ScanResult(
+                scanner=self.name,
+                success=False,
+                findings=[],
+                error=stderr or "Scan failed",
+                duration_ms=duration_ms,
+            )
+
+        try:
+            content = output_file.read_text().strip()
+            if not content:
+                return ScanResult(
+                    scanner=self.name,
+                    success=True,
+                    findings=[],
+                    raw_output_path=output_file,
+                    duration_ms=duration_ms,
+                )
+            findings = self.parse(content)
+        except (json.JSONDecodeError, KeyError) as exc:
+            return ScanResult(
+                scanner=self.name,
+                success=False,
+                findings=[],
+                raw_output_path=output_file,
+                error=f"Parse error: {exc}",
+                duration_ms=duration_ms,
+            )
+
+        return ScanResult(
+            scanner=self.name,
+            success=True,
+            findings=findings,
+            raw_output_path=output_file,
+            duration_ms=duration_ms,
+        )
+
+    def parse(self, raw_output: str) -> list[Finding]:
+        data = json.loads(raw_output)
+        findings: list[Finding] = []
+
+        if not isinstance(data, list):
+            return findings
+
+        for leak in data:
+            findings.append(self._parse_leak(leak))
+
+        return findings
+
+    def _parse_leak(self, leak: dict[str, Any]) -> Finding:
+        # Redact the actual secret from description
+        match = leak.get("Match", "")
+        redacted_match = match[:10] + "..." if len(match) > 10 else "[REDACTED]"
+
+        return Finding(
+            scanner=self.name,
+            title=f"Secret detected: {leak.get('RuleID', 'unknown')}",
+            severity=Severity.HIGH,  # Secrets are always high severity
+            description=f"Potential secret found: {redacted_match}",
+            file_path=leak.get("File"),
+            line=leak.get("StartLine"),
+            rule_id=leak.get("RuleID"),
+            extra={
+                "commit": leak.get("Commit", ""),
+                "author": leak.get("Author", ""),
+                "entropy": str(leak.get("Entropy", "")),
+            },
+        )