kekkai-cli 1.0.0__py3-none-any.whl

kekkai/scanners/semgrep.py

@@ -0,0 +1,227 @@
+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
+
+SEMGREP_IMAGE = "returntocorp/semgrep"
+SEMGREP_DIGEST = "sha256:a5a71b85df0c65c58f13e94c0d0ce7d8e7c8d123456789abcdef0123456789ab"
+SCAN_TYPE = "Semgrep JSON Report"
+
+
+class SemgrepScanner:
+    def __init__(
+        self,
+        image: str = SEMGREP_IMAGE,
+        digest: str | None = SEMGREP_DIGEST,
+        timeout_seconds: int = 600,
+        config: str = "auto",
+        backend: BackendType | None = None,
+    ) -> None:
+        self._image = image
+        self._digest = digest
+        self._timeout = timeout_seconds
+        self._config = config
+        self._backend = backend
+        self._resolved_backend: BackendType | None = None
+
+    @property
+    def name(self) -> str:
+        return "semgrep"
+
+    @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("semgrep")
+            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 Semgrep in Docker container."""
+        output_file = ctx.output_dir / "semgrep-results.json"
+        config = ContainerConfig(
+            image=self._image,
+            image_digest=self._digest,
+            read_only=True,
+            network_disabled=False,
+            no_new_privileges=True,
+        )
+
+        command = [
+            "semgrep",
+            "scan",
+            "--config",
+            self._config,
+            "--json",
+            "--output",
+            "/output/semgrep-results.json",
+            "/repo",
+        ]
+
+        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.duration_ms, result.stderr, output_file
+        )
+
+    def _run_native(self, ctx: ScanContext) -> ScanResult:
+        """Run Semgrep natively."""
+        try:
+            tool_info = detect_tool("semgrep")
+        except (ToolNotFoundError, ToolVersionError) as e:
+            return ScanResult(
+                scanner=self.name,
+                success=False,
+                findings=[],
+                error=str(e),
+                duration_ms=0,
+            )
+
+        output_file = ctx.output_dir / "semgrep-results.json"
+        backend = NativeBackend()
+
+        args = [
+            "scan",
+            "--config",
+            self._config,
+            "--json",
+            "--output",
+            str(output_file),
+            str(ctx.repo_path),
+        ]
+
+        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=True,
+        )
+
+        return self._process_result(
+            result.timed_out, result.duration_ms, result.stderr, output_file
+        )
+
+    def _process_result(
+        self, timed_out: bool, 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():
+            return ScanResult(
+                scanner=self.name,
+                success=False,
+                findings=[],
+                error=stderr or "No output file produced",
+                duration_ms=duration_ms,
+            )
+
+        try:
+            findings = self.parse(output_file.read_text())
+        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] = []
+
+        for result in data.get("results", []):
+            findings.append(self._parse_result(result))
+
+        return findings
+
+    def _parse_result(self, result: dict[str, Any]) -> Finding:
+        extra_data = result.get("extra", {})
+        metadata = extra_data.get("metadata", {})
+
+        severity_str = extra_data.get("severity", "warning")
+        if severity_str == "ERROR":
+            severity = Severity.HIGH
+        elif severity_str == "WARNING":
+            severity = Severity.MEDIUM
+        else:
+            severity = Severity.from_string(severity_str)
+
+        cwe_list = metadata.get("cwe", [])
+        cwe = cwe_list[0] if cwe_list else None
+
+        return Finding(
+            scanner=self.name,
+            title=metadata.get("message") or result.get("check_id", "Semgrep finding"),
+            severity=severity,
+            description=extra_data.get("message", ""),
+            file_path=result.get("path"),
+            line=result.get("start", {}).get("line"),
+            rule_id=result.get("check_id"),
+            cwe=cwe,
+            extra={
+                "fingerprint": extra_data.get("fingerprint", ""),
+                "fix": extra_data.get("fix", ""),
+            },
+        )

kekkai/scanners/trivy.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import json
+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
+
+TRIVY_IMAGE = "aquasec/trivy"
+TRIVY_DIGEST = "sha256:e9d62d670b10c9f78bb7c61d5c1f6e0bb32fc8bd0f6e1a7dd0c4e6b7f5df0a30"
+SCAN_TYPE = "Trivy Scan"
+
+
+class TrivyScanner:
+    def __init__(
+        self,
+        image: str = TRIVY_IMAGE,
+        digest: str | None = TRIVY_DIGEST,
+        timeout_seconds: int = 600,
+        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 "trivy"
+
+    @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("trivy")
+            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 Trivy in Docker container."""
+        output_file = ctx.output_dir / "trivy-results.json"
+        config = ContainerConfig(
+            image=self._image,
+            image_digest=self._digest,
+            read_only=True,
+            network_disabled=False,
+            no_new_privileges=True,
+        )
+
+        command = [
+            "fs",
+            "--format",
+            "json",
+            "--output",
+            "/output/trivy-results.json",
+            "--severity",
+            "CRITICAL,HIGH,MEDIUM,LOW",
+            "--scanners",
+            "vuln,secret,misconfig",
+            "/repo",
+        ]
+
+        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.duration_ms, result.stderr, output_file
+        )
+
+    def _run_native(self, ctx: ScanContext) -> ScanResult:
+        """Run Trivy natively."""
+        try:
+            tool_info = detect_tool("trivy")
+        except (ToolNotFoundError, ToolVersionError) as e:
+            return ScanResult(
+                scanner=self.name,
+                success=False,
+                findings=[],
+                error=str(e),
+                duration_ms=0,
+            )
+
+        output_file = ctx.output_dir / "trivy-results.json"
+        backend = NativeBackend()
+
+        args = [
+            "fs",
+            "--format",
+            "json",
+            "--output",
+            str(output_file),
+            "--severity",
+            "CRITICAL,HIGH,MEDIUM,LOW",
+            "--scanners",
+            "vuln,secret,misconfig",
+            str(ctx.repo_path),
+        ]
+
+        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=True,
+        )
+
+        return self._process_result(
+            result.timed_out, result.duration_ms, result.stderr, output_file
+        )
+
+    def _process_result(
+        self, timed_out: bool, duration_ms: int, stderr: str, output_file: Any
+    ) -> 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():
+            return ScanResult(
+                scanner=self.name,
+                success=False,
+                findings=[],
+                error=stderr or "No output file produced",
+                duration_ms=duration_ms,
+            )
+
+        try:
+            findings = self.parse(output_file.read_text())
+        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] = []
+
+        results = data.get("Results", [])
+        for target in results:
+            target_name = target.get("Target", "")
+            target_type = target.get("Type", "")
+
+            for vuln in target.get("Vulnerabilities", []):
+                findings.append(self._parse_vulnerability(vuln, target_name, target_type))
+
+            for secret in target.get("Secrets", []):
+                findings.append(self._parse_secret(secret, target_name))
+
+            for misconfig in target.get("Misconfigurations", []):
+                findings.append(self._parse_misconfig(misconfig, target_name))
+
+        return findings
+
+    def _parse_vulnerability(self, vuln: dict[str, Any], target: str, target_type: str) -> Finding:
+        return Finding(
+            scanner=self.name,
+            title=vuln.get("Title") or vuln.get("VulnerabilityID", "Unknown"),
+            severity=Severity.from_string(vuln.get("Severity", "unknown")),
+            description=vuln.get("Description", ""),
+            file_path=target,
+            cve=vuln.get("VulnerabilityID"),
+            package_name=vuln.get("PkgName"),
+            package_version=vuln.get("InstalledVersion"),
+            fixed_version=vuln.get("FixedVersion"),
+            extra={"target_type": target_type},
+        )
+
+    def _parse_secret(self, secret: dict[str, Any], target: str) -> Finding:
+        return Finding(
+            scanner=self.name,
+            title=secret.get("Title", "Secret detected"),
+            severity=Severity.from_string(secret.get("Severity", "high")),
+            description=secret.get("Match", ""),
+            file_path=target,
+            line=secret.get("StartLine"),
+            rule_id=secret.get("RuleID"),
+        )
+
+    def _parse_misconfig(self, misconfig: dict[str, Any], target: str) -> Finding:
+        return Finding(
+            scanner=self.name,
+            title=misconfig.get("Title", "Misconfiguration"),
+            severity=Severity.from_string(misconfig.get("Severity", "medium")),
+            description=misconfig.get("Description", ""),
+            file_path=target,
+            rule_id=misconfig.get("ID"),
+            extra={"resolution": misconfig.get("Resolution", "")},
+        )

kekkai/scanners/url_policy.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import ipaddress
+import socket
+import urllib.parse
+from dataclasses import dataclass, field
+
+
+class UrlPolicyError(ValueError):
+    """Raised when a URL fails policy validation."""
+
+
+@dataclass(frozen=True)
+class UrlPolicy:
+    """URL validation policy for DAST scanning targets.
+
+    By default, blocks all private/internal IP ranges (SSRF protection).
+    Can be configured with explicit allowlist patterns.
+    """
+
+    allow_private_ips: bool = False
+    allowed_domains: frozenset[str] = field(default_factory=frozenset)
+    blocked_domains: frozenset[str] = field(default_factory=frozenset)
+    max_redirects: int = 2
+    allowed_schemes: frozenset[str] = field(default_factory=lambda: frozenset({"http", "https"}))
+
+
+def validate_target_url(url: str, policy: UrlPolicy | None = None) -> str:
+    """Validate and normalize a target URL for DAST scanning.
+
+    Args:
+        url: The URL to validate
+        policy: Optional URL policy (uses default restrictive policy if None)
+
+    Returns:
+        Normalized URL string
+
+    Raises:
+        UrlPolicyError: If URL fails validation
+    """
+    policy = policy or UrlPolicy()
+
+    parsed = urllib.parse.urlsplit(url)
+    scheme = parsed.scheme.lower()
+
+    if scheme not in policy.allowed_schemes:
+        raise UrlPolicyError(f"unsupported scheme: {scheme}")
+
+    if not parsed.netloc:
+        raise UrlPolicyError("missing host")
+
+    if parsed.username or parsed.password:
+        raise UrlPolicyError("credentials in URL not allowed")
+
+    hostname = parsed.hostname
+    if not hostname:
+        raise UrlPolicyError("missing hostname")
+
+    hostname_lower = hostname.lower()
+
+    # Check blocked domains
+    if policy.blocked_domains:
+        for blocked in policy.blocked_domains:
+            if hostname_lower == blocked or hostname_lower.endswith(f".{blocked}"):
+                raise UrlPolicyError(f"blocked domain: {hostname}")
+
+    # Check localhost variants
+    if hostname_lower in {"localhost"} or hostname_lower.endswith(".local"):
+        raise UrlPolicyError("local hostnames are blocked")
+
+    # Check allowed domains (if specified, acts as allowlist)
+    if policy.allowed_domains:
+        allowed = False
+        for domain in policy.allowed_domains:
+            if hostname_lower == domain or hostname_lower.endswith(f".{domain}"):
+                allowed = True
+                break
+        if not allowed:
+            raise UrlPolicyError(f"domain not in allowlist: {hostname}")
+
+    # Validate IP addresses
+    if _is_ip_literal(hostname):
+        ip = ipaddress.ip_address(hostname)
+        if not policy.allow_private_ips and _is_blocked_ip(ip):
+            raise UrlPolicyError(f"private/internal IP blocked: {hostname}")
+    else:
+        # Resolve hostname and check all IPs
+        resolved = _resolve_host(hostname)
+        if not resolved:
+            raise UrlPolicyError(f"hostname resolution failed: {hostname}")
+        if not policy.allow_private_ips:
+            for ip in resolved:
+                if _is_blocked_ip(ip):
+                    raise UrlPolicyError(f"hostname resolves to blocked IP: {hostname} -> {ip}")
+
+    # Normalize the URL
+    normalized = urllib.parse.urlunsplit(
+        (scheme, parsed.netloc, parsed.path or "/", parsed.query, "")
+    )
+    return normalized
+
+
+def _is_ip_literal(hostname: str) -> bool:
+    """Check if hostname is an IP address literal."""
+    try:
+        ipaddress.ip_address(hostname)
+        return True
+    except ValueError:
+        return False
+
+
+def _resolve_host(hostname: str) -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+    """Resolve hostname to IP addresses."""
+    try:
+        infos = socket.getaddrinfo(hostname, None)
+    except socket.gaierror:
+        return []
+
+    resolved: list[ipaddress.IPv4Address | ipaddress.IPv6Address] = []
+    for info in infos:
+        sockaddr = info[4]
+        if not sockaddr:
+            continue
+        address = sockaddr[0]
+        try:
+            resolved.append(ipaddress.ip_address(address))
+        except ValueError:
+            continue
+    return resolved
+
+
+def _is_blocked_ip(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    """Check if IP is in a blocked range (non-global/public)."""
+    # Block all non-global IPs by default (private, loopback, link-local, etc.)
+    return not ip.is_global
+
+
+def is_private_ip_range(cidr: str) -> bool:
+    """Check if a CIDR range is private/internal."""
+    try:
+        network = ipaddress.ip_network(cidr, strict=False)
+        # A range is "private" if it's not fully global
+        return not all(
+            ipaddress.ip_address(int(network.network_address) + i).is_global
+            for i in range(min(256, network.num_addresses))
+        )
+    except ValueError:
+        return True  # Invalid CIDR = blocked
+
+
+# Common private/internal CIDR ranges for reference
+PRIVATE_CIDRS = frozenset(
+    {
+        "10.0.0.0/8",  # RFC 1918
+        "172.16.0.0/12",  # RFC 1918
+        "192.168.0.0/16",  # RFC 1918
+        "127.0.0.0/8",  # Loopback
+        "169.254.0.0/16",  # Link-local
+        "::1/128",  # IPv6 loopback
+        "fe80::/10",  # IPv6 link-local
+        "fc00::/7",  # IPv6 ULA
+    }
+)