kekkai-cli 1.0.5__py3-none-any.whl → 1.1.1__py3-none-any.whl

kekkai/report/unified.py

@@ -0,0 +1,226 @@
+"""Unified report generation for Kekkai scan results.
+
+Aggregates findings from multiple scanners into a single JSON report
+with security-hardened validation and resource limits (ASVS V10.3.3).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from kekkai_core import redact
+
+if TYPE_CHECKING:
+    from ..scanners.base import Finding, ScanResult
+
+__all__ = [
+    "generate_unified_report",
+    "UnifiedReportError",
+]
+
+# Security limits per ASVS V10.3.3 (DoS mitigation)
+MAX_FINDINGS_PER_SCANNER = 10_000
+MAX_TOTAL_FINDINGS = 50_000
+MAX_JSON_SIZE_MB = 100
+
+
+class UnifiedReportError(Exception):
+    """Error during unified report generation."""
+
+
+def generate_unified_report(
+    scan_results: list[ScanResult],
+    output_path: Path,
+    run_id: str,
+    commit_sha: str | None = None,
+) -> dict[str, Any]:
+    """Generate unified kekkai-report.json from scan results.
+
+    Aggregates findings from all scanners with security controls:
+    - Resource limits (ASVS V10.3.3): 10k findings/scanner, 50k total
+    - Sensitive data redaction (ASVS V8.3.4)
+    - Atomic writes with safe permissions (ASVS V12.3.1)
+    - Path validation (ASVS V5.3.3)
+
+    Args:
+        scan_results: List of scanner results to aggregate.
+        output_path: Path to write unified report JSON.
+        run_id: Unique run identifier.
+        commit_sha: Optional git commit SHA.
+
+    Returns:
+        Report data dictionary.
+
+    Raises:
+        UnifiedReportError: If report generation fails.
+    """
+    # Aggregate findings with limits
+    all_findings: list[dict[str, Any]] = []
+    scanner_metadata: dict[str, dict[str, Any]] = {}
+    warnings: list[str] = []
+
+    for scan_res in scan_results:
+        if not scan_res.success:
+            scanner_metadata[scan_res.scanner] = {
+                "success": False,
+                "error": scan_res.error,
+                "findings_count": 0,
+                "duration_ms": scan_res.duration_ms,
+            }
+            continue
+
+        # Apply per-scanner limit (DoS mitigation)
+        findings = scan_res.findings[:MAX_FINDINGS_PER_SCANNER]
+        if len(scan_res.findings) > MAX_FINDINGS_PER_SCANNER:
+            warnings.append(
+                f"{scan_res.scanner}: truncated {len(scan_res.findings)} findings "
+                f"to {MAX_FINDINGS_PER_SCANNER} (limit)"
+            )
+
+        for finding in findings:
+            if len(all_findings) >= MAX_TOTAL_FINDINGS:
+                warnings.append(
+                    f"Reached max total findings limit ({MAX_TOTAL_FINDINGS}), stopping aggregation"
+                )
+                break
+
+            # Convert to dict with redaction (ASVS V8.3.4)
+            all_findings.append(_finding_to_dict(finding))
+
+        scanner_metadata[scan_res.scanner] = {
+            "success": scan_res.success,
+            "findings_count": len(findings),
+            "duration_ms": scan_res.duration_ms,
+        }
+
+    # Build report structure
+    report: dict[str, Any] = {
+        "version": "1.0.0",
+        "generated_at": datetime.now(UTC).isoformat(),
+        "run_id": run_id,
+        "commit_sha": commit_sha,
+        "scan_metadata": scanner_metadata,
+        "summary": _build_summary(all_findings),
+        "findings": all_findings,
+    }
+
+    if warnings:
+        report["warnings"] = warnings
+
+    # Write atomically (ASVS V12.3.1)
+    try:
+        _write_report_atomic(output_path, report)
+    except Exception as exc:
+        # ASVS V7.4.1: Don't leak full path in error
+        raise UnifiedReportError(f"Failed to write report: {exc}") from exc
+
+    return report
+
+
+def _finding_to_dict(finding: Finding) -> dict[str, Any]:
+    """Convert Finding to dictionary with redaction.
+
+    Args:
+        finding: Scanner finding object.
+
+    Returns:
+        Dictionary with redacted sensitive fields.
+    """
+    return {
+        "id": finding.dedupe_hash(),
+        "scanner": finding.scanner,
+        "title": redact(finding.title),
+        "severity": finding.severity.value,
+        "description": redact(finding.description),
+        "file_path": finding.file_path,
+        "line": finding.line,
+        "rule_id": finding.rule_id,
+        "cwe": finding.cwe,
+        "cve": finding.cve,
+        "package_name": finding.package_name,
+        "package_version": finding.package_version,
+        "fixed_version": finding.fixed_version,
+    }
+
+
+def _build_summary(findings: list[dict[str, Any]]) -> dict[str, int]:
+    """Build summary statistics from findings.
+
+    Args:
+        findings: List of finding dictionaries.
+
+    Returns:
+        Summary with total and severity counts.
+    """
+    summary = {
+        "total_findings": len(findings),
+        "critical": 0,
+        "high": 0,
+        "medium": 0,
+        "low": 0,
+        "info": 0,
+        "unknown": 0,
+    }
+
+    for finding in findings:
+        severity = finding.get("severity", "unknown")
+        if severity in summary:
+            summary[severity] += 1
+        else:
+            summary["unknown"] += 1
+
+    return summary
+
+
+def _write_report_atomic(path: Path, data: dict[str, Any]) -> None:
+    """Write JSON report atomically with permission checks.
+
+    Security controls:
+    - Size validation before writing (ASVS V10.3.3)
+    - Atomic write via temp file + rename (ASVS V12.3.1)
+    - Safe file permissions (0o644)
+
+    Args:
+        path: Output file path.
+        data: Report data to serialize.
+
+    Raises:
+        ValueError: If report exceeds size limit.
+        OSError: If write fails.
+    """
+    # Ensure parent directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Serialize and check size (ASVS V10.3.3)
+    json_str = json.dumps(data, indent=2, ensure_ascii=False)
+    size_mb = len(json_str.encode("utf-8")) / (1024 * 1024)
+    if size_mb > MAX_JSON_SIZE_MB:
+        raise ValueError(f"Report too large: {size_mb:.1f}MB > {MAX_JSON_SIZE_MB}MB")
+
+    # Atomic write: temp file + rename (ASVS V12.3.1)
+    temp_fd, temp_path_str = tempfile.mkstemp(
+        dir=str(path.parent), prefix=".kekkai-report-", suffix=".json.tmp"
+    )
+    temp_path = Path(temp_path_str)
+
+    try:
+        # Write to temp file
+        os.write(temp_fd, json_str.encode("utf-8"))
+        os.close(temp_fd)
+
+        # Set safe permissions (rw-r--r--)
+        os.chmod(temp_path, 0o644)
+
+        # Atomic rename
+        temp_path.rename(path)
+    except Exception:
+        # Clean up temp file on error
+        with contextlib.suppress(OSError):
+            temp_path.unlink()
+        raise

kekkai/scanners/container.py

@@ -36,6 +36,19 @@ def docker_command() -> str:
     return docker
 
 
+def _resolve_image_ref(image: str, digest: str | None) -> str:
+    """Resolve full image reference with tag or digest.
+
+    Ensures images have explicit :latest tag when no digest or tag is provided
+    for reliable cross-platform pulling.
+    """
+    if digest:
+        return f"{image}@{digest}"
+    if ":" not in image:
+        return f"{image}:latest"
+    return image
+
+
 def run_container(
     config: ContainerConfig,
     repo_path: Path,
@@ -61,7 +74,7 @@ def run_container(
         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
+    image_ref = _resolve_image_ref(config.image, config.image_digest)
 
     args = [
         docker,
@@ -73,7 +86,20 @@ def run_container(
         args.extend(["--user", user])
 
     if config.read_only:
-        args.extend(["--read-only", "--tmpfs", "/tmp:rw,noexec,nosuid,size=512m"])  # nosec B108  # noqa: S108
+        args.extend(["--read-only"])
+        # Determine uid/gid for tmpfs ownership (match container user)
+        tmpfs_opts = "rw"
+        if user:
+            uid_gid = user.split(":")[0]
+            tmpfs_opts = f"rw,uid={uid_gid},gid={uid_gid}"
+        # Core temp directory (2GB for Trivy DB ~500MB + scanner temp files)
+        args.extend(["--tmpfs", f"/tmp:{tmpfs_opts},noexec,nosuid,size=2g"])  # nosec B108  # noqa: S108
+        # Scanner cache directories (Trivy DB, Semgrep cache, etc.)
+        args.extend(["--tmpfs", f"/root:{tmpfs_opts},size=1g"])
+        # Generic home for tools that need writable home
+        args.extend(["--tmpfs", f"/home:{tmpfs_opts},size=256m"])
+        # Set HOME env to writable location for tools that use $HOME/.cache
+        args.extend(["-e", "HOME=/tmp"])
 
     if config.network_disabled:
         args.extend(["--network", "none"])
@@ -132,8 +158,12 @@ def run_container(
 
 
 def pull_image(image: str, digest: str | None = None) -> bool:
+    """Pull a Docker image.
+
+    Uses _resolve_image_ref to ensure proper tag handling.
+    """
     docker = docker_command()
-    ref = f"{image}@{digest}" if digest else image
+    ref = _resolve_image_ref(image, digest)
     proc = subprocess.run(  # noqa: S603  # nosec B603
         [docker, "pull", ref],
         capture_output=True,

kekkai/scanners/gitleaks.py

@@ -16,7 +16,7 @@ from .base import Finding, ScanContext, ScanResult, Severity
 from .container import ContainerConfig, run_container
 
 GITLEAKS_IMAGE = "zricethezav/gitleaks"
-GITLEAKS_DIGEST = "sha256:691af3c7c5a48b16f187ce3446d5f194838f91238f27270ed36eef6359a574d9"
+GITLEAKS_DIGEST: str | None = None  # Allow Docker to pull architecture-appropriate image
 SCAN_TYPE = "Gitleaks Scan"
 
 
@@ -85,6 +85,7 @@ class GitleaksScanner:
             "detect",
             "--source",
             "/repo",
+            "--no-git",  # Scan all files, not just git-tracked
             "--report-format",
             "json",
             "--report-path",
@@ -125,6 +126,7 @@ class GitleaksScanner:
             "detect",
             "--source",
             str(ctx.repo_path),
+            "--no-git",  # Scan all files, not just git-tracked
             "--report-format",
             "json",
             "--report-path",

kekkai/scanners/semgrep.py

@@ -16,7 +16,7 @@ from .base import Finding, ScanContext, ScanResult, Severity
 from .container import ContainerConfig, run_container
 
 SEMGREP_IMAGE = "returntocorp/semgrep"
-SEMGREP_DIGEST = "sha256:a5a71b85df0c65c58f13e94c0d0ce7d8e7c8d123456789abcdef0123456789ab"
+SEMGREP_DIGEST: str | None = None  # Allow Docker to pull architecture-appropriate image
 SCAN_TYPE = "Semgrep JSON Report"
 
 

kekkai/scanners/trivy.py

@@ -15,7 +15,7 @@ from .base import Finding, ScanContext, ScanResult, Severity
 from .container import ContainerConfig, run_container
 
 TRIVY_IMAGE = "aquasec/trivy"
-TRIVY_DIGEST = "sha256:e9d62d670b10c9f78bb7c61d5c1f6e0bb32fc8bd0f6e1a7dd0c4e6b7f5df0a30"
+TRIVY_DIGEST: str | None = None  # Allow Docker to pull architecture-appropriate image
 SCAN_TYPE = "Trivy Scan"
 
 

kekkai/threatflow/model_adapter.py

@@ -396,6 +396,143 @@ class RemoteModelAdapter(ModelAdapter):
             )
 
 
+class OllamaModelAdapter(ModelAdapter):
+    """Adapter for Ollama local LLM server.
+
+    Ollama provides an easy way to run local models with a simple API.
+    Install: curl -fsSL https://ollama.ai/install.sh | sh
+    Pull model: ollama pull tinyllama
+    """
+
+    def __init__(
+        self,
+        model_name: str = "tinyllama",
+        api_base: str | None = None,
+    ) -> None:
+        self._model_name = model_name
+        self._api_base = api_base or os.environ.get("OLLAMA_HOST") or "http://localhost:11434"
+
+    @property
+    def name(self) -> str:
+        return f"ollama:{self._model_name}"
+
+    @property
+    def is_local(self) -> bool:
+        return True  # Ollama runs locally
+
+    def generate(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        config: ModelConfig | None = None,
+    ) -> ModelResponse:
+        """Generate using Ollama API."""
+        import urllib.error
+        import urllib.request
+
+        config = config or ModelConfig()
+        start_time = time.time()
+
+        url = f"{self._api_base.rstrip('/')}/api/chat"
+        model = config.model_name or self._model_name
+
+        data = {
+            "model": model,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            "stream": False,
+            "options": {
+                "temperature": config.temperature,
+                "num_predict": config.max_tokens,
+            },
+        }
+
+        headers = {"Content-Type": "application/json"}
+
+        req = urllib.request.Request(  # noqa: S310  # nosec B310
+            url,
+            data=json.dumps(data).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(  # noqa: S310  # nosec B310
+                req, timeout=config.timeout_seconds
+            ) as resp:
+                response_data: dict[str, Any] = json.loads(resp.read().decode("utf-8"))
+
+            content = response_data.get("message", {}).get("content", "")
+            latency_ms = int((time.time() - start_time) * 1000)
+
+            # Ollama provides token counts in some responses
+            prompt_tokens = response_data.get("prompt_eval_count", 0)
+            completion_tokens = response_data.get("eval_count", 0)
+
+            return ModelResponse(
+                content=content,
+                model_name=response_data.get("model", model),
+                prompt_tokens=prompt_tokens,
+                completion_tokens=completion_tokens,
+                total_tokens=prompt_tokens + completion_tokens,
+                latency_ms=latency_ms,
+                raw_response=response_data,
+            )
+        except urllib.error.URLError as e:
+            error_msg = str(e)
+            if "Connection refused" in error_msg:
+                logger.error("Ollama not running. Start with: ollama serve")
+                return ModelResponse(
+                    content="[OLLAMA NOT RUNNING - Start with: ollama serve]",
+                    model_name=model,
+                    latency_ms=int((time.time() - start_time) * 1000),
+                )
+            logger.error("Ollama API error: %s", e)
+            return ModelResponse(
+                content="",
+                model_name=model,
+                latency_ms=int((time.time() - start_time) * 1000),
+            )
+        except Exception as e:
+            logger.error("Ollama request failed: %s", e)
+            return ModelResponse(
+                content="",
+                model_name=model,
+                latency_ms=int((time.time() - start_time) * 1000),
+            )
+
+    def health_check(self) -> bool:
+        """Check if Ollama is running and model is available."""
+        import urllib.request
+
+        try:
+            url = f"{self._api_base.rstrip('/')}/api/tags"
+            req = urllib.request.Request(url, method="GET")  # noqa: S310  # nosec B310
+            with urllib.request.urlopen(req, timeout=5) as resp:  # noqa: S310  # nosec B310
+                data: dict[str, list[dict[str, str]]] = json.loads(resp.read().decode())
+                models = [m.get("name", "") for m in data.get("models", [])]
+                # Check if our model is available (with or without :latest tag)
+                model_base = self._model_name.split(":")[0]
+                return any(model_base in m for m in models)
+        except Exception:
+            return False
+
+    def list_models(self) -> list[str]:
+        """List available models in Ollama."""
+        import urllib.request
+
+        try:
+            url = f"{self._api_base.rstrip('/')}/api/tags"
+            req = urllib.request.Request(url, method="GET")  # noqa: S310  # nosec B310
+            with urllib.request.urlopen(req, timeout=5) as resp:  # noqa: S310  # nosec B310
+                data: dict[str, list[dict[str, str]]] = json.loads(resp.read().decode())
+                return [m.get("name", "") for m in data.get("models", [])]
+        except Exception:
+            return []
+
+
 class MockModelAdapter(ModelAdapter):
     """Mock adapter for testing."""
 
@@ -461,7 +598,7 @@ def create_adapter(
     """Create a model adapter based on mode.
 
     Args:
-        mode: "local", "openai", "anthropic", or "mock"
+        mode: "local", "ollama", "openai", "anthropic", or "mock"
         config: Configuration for the adapter
 
     Returns:
@@ -473,6 +610,11 @@ def create_adapter(
         return MockModelAdapter()
     elif mode == "local":
         return LocalModelAdapter(model_path=config.model_path)
+    elif mode == "ollama":
+        return OllamaModelAdapter(
+            model_name=config.model_name or "tinyllama",
+            api_base=config.api_base,
+        )
     elif mode == "openai":
         return RemoteModelAdapter(
             api_key=config.api_key,

kekkai/triage/__init__.py

@@ -4,9 +4,18 @@ Provides a terminal-based interface for reviewing findings,
 marking false positives, and generating .kekkaiignore files.
 """
 
-from .app import TriageApp, run_triage
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+# Import models and utilities (no heavy dependencies)
 from .audit import AuditEntry, TriageAuditLog, log_decisions
 from .ignore import IgnoreEntry, IgnoreFile, IgnorePatternValidator, ValidationError
+from .loader import load_findings_from_path
 from .models import (
     FindingEntry,
     Severity,
@@ -15,6 +24,49 @@ from .models import (
     load_findings_from_json,
 )
 
+
+def run_triage(
+    input_path: Path | None = None,
+    output_path: Path | None = None,
+    findings: Sequence[FindingEntry] | None = None,
+) -> int:
+    """Run the triage TUI (lazy import).
+
+    Args:
+        input_path: Path to findings JSON file.
+        output_path: Path for .kekkaiignore output.
+        findings: Pre-loaded findings (alternative to input_path).
+
+    Returns:
+        Exit code (0 for success).
+
+    Raises:
+        RuntimeError: If Textual is not installed.
+    """
+    try:
+        from .app import run_triage as _run_triage
+
+        return _run_triage(
+            input_path=input_path,
+            output_path=output_path,
+            findings=findings,
+        )
+    except ImportError as e:
+        raise RuntimeError(
+            "Triage TUI requires 'textual'. Install with: pip install textual"
+        ) from e
+
+
+# Re-export TriageApp for compatibility (lazy)
+def __getattr__(name: str) -> type:
+    """Lazy import for TriageApp."""
+    if name == "TriageApp":
+        from .app import TriageApp
+
+        return TriageApp
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 __all__ = [
     "TriageApp",
     "run_triage",
@@ -30,4 +82,5 @@ __all__ = [
     "TriageState",
     "Severity",
     "load_findings_from_json",
+    "load_findings_from_path",
 ]