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

kekkai/dojo.py

@@ -49,7 +49,10 @@ def compose_command() -> list[str]:
     docker_compose = shutil.which("docker-compose")
     if docker_compose:
         return [docker_compose]
-    raise RuntimeError("Docker Compose not found; install docker and docker compose")
+    raise RuntimeError(
+        "Docker Compose not found. Please install Docker Desktop "
+        "or the 'docker-compose-plugin' package for your system."
+    )
 
 
 def check_port_available(port: int, host: str = "127.0.0.1") -> bool:
@@ -62,6 +65,21 @@ def check_port_available(port: int, host: str = "127.0.0.1") -> bool:
     return True
 
 
+def find_available_port(preferred: int, max_attempts: int = 20) -> tuple[int, bool]:
+    """Find an available port, starting from preferred.
+
+    Returns:
+        Tuple of (port, was_fallback) - was_fallback is True if not the preferred port
+    """
+    if check_port_available(preferred):
+        return preferred, False
+    for offset in range(1, max_attempts + 1):
+        candidate = preferred + offset
+        if check_port_available(candidate):
+            return candidate, True
+    raise RuntimeError(f"No available ports found in range {preferred}-{preferred + max_attempts}")
+
+
 def load_env_file(path: Path) -> dict[str, str]:
     if not path.exists():
         return {}
@@ -115,7 +133,6 @@ def ensure_env(path: Path, port: int, tls_port: int) -> dict[str, str]:
 
 def build_compose_yaml() -> str:
     return (
-        'version: "3.9"\n'
         "services:\n"
         "  nginx:\n"
         "    image: defectdojo/defectdojo-nginx:${NGINX_VERSION:-latest}\n"
@@ -278,15 +295,24 @@ def compose_up(
     tls_port: int,
     wait: bool,
     open_browser: bool,
-) -> dict[str, str]:
-    if not check_port_available(port):
-        raise RuntimeError(f"Port {port} is already in use")
-    if not check_port_available(tls_port):
-        raise RuntimeError(f"Port {tls_port} is already in use")
+) -> tuple[dict[str, str], int, int]:
+    """Start DefectDojo stack.
+
+    Returns:
+        Tuple of (env_dict, actual_port, actual_tls_port)
+    """
+    # Auto-select available ports
+    actual_port, port_fallback = find_available_port(port)
+    actual_tls_port, tls_fallback = find_available_port(tls_port)
 
     compose_file = compose_root / "docker-compose.yml"
     env_file = compose_root / ".env"
-    env = ensure_compose_files(compose_file, env_file, port, tls_port)
+    env = ensure_compose_files(compose_file, env_file, actual_port, actual_tls_port)
+
+    # Store port info for later retrieval
+    env["DD_PORT"] = str(actual_port)
+    env["DD_TLS_PORT"] = str(actual_tls_port)
+    write_env_file(env_file, env)
 
     cmd = compose_command() + [
         "--project-name",
@@ -301,11 +327,24 @@ def compose_up(
         raise RuntimeError(proc.stderr.strip() or "Failed to start DefectDojo")
 
     if wait:
-        wait_for_ui(port, timeout=300)
+        wait_for_ui(actual_port, timeout=300)
+        # Generate API key for kekkai upload command
+        try:
+            api_key = generate_api_key(
+                actual_port,
+                env.get("DD_ADMIN_USER", "admin"),
+                env.get("DD_ADMIN_PASSWORD", ""),
+            )
+            env["DD_API_KEY"] = api_key
+            write_env_file(env_file, env)
+        except RuntimeError:
+            # Non-fatal - user can generate API key manually via UI
+            pass
 
     if open_browser:
-        open_ui(port)
-    return env
+        open_ui(actual_port)
+
+    return env, actual_port, actual_tls_port
 
 
 def compose_down(*, compose_root: Path, project_name: str) -> None:
@@ -318,7 +357,11 @@ def compose_down(*, compose_root: Path, project_name: str) -> None:
         "--profile",
         DOJO_PROFILE,
     ]
-    proc = subprocess.run(cmd + ["down", "--remove-orphans"], capture_output=True, text=True)  # noqa: S603  # nosec B603
+    proc = subprocess.run(  # noqa: S603  # nosec B603
+        cmd + ["down", "--remove-orphans", "--volumes"],
+        capture_output=True,
+        text=True,
+    )
     if proc.returncode != 0:
         raise RuntimeError(proc.stderr.strip() or "Failed to stop DefectDojo")
 
@@ -382,9 +425,10 @@ def wait_for_ui(port: int, timeout: int = 300) -> None:
                 if resp.status in {200, 302, 401}:
                     return
                 last_error = f"HTTP {resp.status}"
-        except (URLError, HTTPError) as exc:
+        except (URLError, HTTPError, OSError, ConnectionError) as exc:
+            # OSError/ConnectionError covers ConnectionResetError, BrokenPipeError, etc.
             last_error = str(exc)
-            time.sleep(2)
+        time.sleep(2)
     raise RuntimeError(f"DefectDojo UI did not become ready in time ({last_error})")
 
 
@@ -395,6 +439,39 @@ def open_ui(port: int) -> None:
         webbrowser.open(url)
 
 
+def generate_api_key(port: int, username: str, password: str, timeout: int = 30) -> str:
+    """Generate DefectDojo API key using admin credentials.
+
+    Uses the /api/v2/api-token-auth/ endpoint to get a token.
+
+    Args:
+        port: DefectDojo port
+        username: Admin username
+        password: Admin password
+        timeout: Request timeout in seconds
+
+    Returns:
+        API token string
+
+    Raises:
+        RuntimeError: If token generation fails
+    """
+    url = f"http://localhost:{port}/api/v2/api-token-auth/"
+    data = json.dumps({"username": username, "password": password}).encode()
+    headers = {"Content-Type": "application/json"}
+
+    req = Request(url, data=data, headers=headers, method="POST")  # noqa: S310  # nosec B310
+    try:
+        with urlopen(req, timeout=timeout) as resp:  # noqa: S310  # nosec B310
+            result: dict[str, str] = json.loads(resp.read().decode())
+            token = result.get("token", "")
+            if not token:
+                raise RuntimeError("Empty token returned from DefectDojo")
+            return token
+    except (URLError, HTTPError, OSError) as exc:
+        raise RuntimeError(f"Failed to generate API key: {exc}") from exc
+
+
 def _random_string(length: int) -> str:
     alphabet = string.ascii_letters + string.digits
     return "".join(secrets.choice(alphabet) for _ in range(length))

kekkai/dojo_import.py

@@ -61,7 +61,15 @@ class DojoClient:
 
         try:
             with urlopen(req, timeout=self._timeout) as resp:  # noqa: S310  # nosec B310
-                return json.loads(resp.read().decode()) if resp.read else {}
+                raw_bytes = resp.read()  # Call once and store result
+                if not raw_bytes:  # Check bytes, not method
+                    return {}
+                try:
+                    result: dict[str, Any] = json.loads(raw_bytes.decode())
+                    return result
+                except json.JSONDecodeError:
+                    # Empty or invalid JSON response - return empty dict
+                    return {}
         except HTTPError as exc:
             error_body = exc.read().decode() if exc.fp else str(exc)
             raise RuntimeError(f"Dojo API error {exc.code}: {error_body}") from exc

kekkai/fix/__init__.py

@@ -0,0 +1,47 @@
+"""AI-powered code remediation engine.
+
+Provides `kekkai fix` functionality to generate and apply code fixes
+for security findings using LLM-based suggestions.
+
+Security considerations:
+- All inputs sanitized before LLM processing (reuses TieredSanitizer)
+- Preview mode default (no auto-apply without explicit --apply)
+- Audit logging for all operations (ASVS V8.3.1)
+- Supports local LLM for sensitive codebases
+
+ASVS Requirements:
+- V5.2.5: Sanitize before LLM
+- V5.3.3: Diff format preserves code intent
+- V6.4.1: API keys in env vars only
+- V8.3.1: Audit log for fix applications
+- V13.1.1: HTTPS for remote API calls
+"""
+
+from __future__ import annotations
+
+from .audit import FixAttempt, FixAuditLog, create_session_id
+from .differ import ApplyResult, DiffApplier, DiffHunk, DiffParser, ParsedDiff, generate_diff
+from .engine import FixConfig, FixEngine, FixResult, FixSuggestion, create_fix_engine
+from .prompts import FixPromptBuilder
+
+__all__ = [
+    # Engine
+    "FixEngine",
+    "FixConfig",
+    "FixResult",
+    "FixSuggestion",
+    "create_fix_engine",
+    # Prompts
+    "FixPromptBuilder",
+    # Differ
+    "DiffParser",
+    "DiffApplier",
+    "DiffHunk",
+    "ParsedDiff",
+    "ApplyResult",
+    "generate_diff",
+    # Audit
+    "FixAuditLog",
+    "FixAttempt",
+    "create_session_id",
+]

kekkai/fix/audit.py

@@ -0,0 +1,278 @@
+"""Audit logging for fix applications.
+
+Records all fix attempts, approvals, and applications with timestamps
+for compliance and forensics purposes.
+
+ASVS V8.3.1: Sensitive data not logged inappropriately.
+ASVS V16.3.3: Log security-relevant events.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class FixAttempt:
+    """Record of a single fix attempt."""
+
+    finding_id: str
+    rule_id: str
+    file_path: str
+    line_number: int
+    severity: str
+    timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    model_used: str = ""
+    status: str = "pending"  # pending, approved, applied, rejected, failed
+    error: str | None = None
+    diff_preview: str | None = None
+    lines_added: int = 0
+    lines_removed: int = 0
+    backup_path: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return asdict(self)
+
+
+@dataclass
+class FixAuditLog:
+    """Audit log for fix operations.
+
+    Maintains an append-only log of all fix attempts for a session.
+    """
+
+    session_id: str
+    repo_path: str
+    started_at: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    model_mode: str = "local"
+    attempts: list[FixAttempt] = field(default_factory=list)
+    _output_path: Path | None = field(default=None, repr=False)
+
+    def record_attempt(
+        self,
+        finding_id: str,
+        rule_id: str,
+        file_path: str,
+        line_number: int,
+        severity: str,
+        model_used: str = "",
+    ) -> FixAttempt:
+        """Record a new fix attempt.
+
+        Args:
+            finding_id: Unique identifier for the finding
+            rule_id: Scanner rule that triggered the finding
+            file_path: Path to the affected file
+            line_number: Line number of the finding
+            severity: Finding severity level
+            model_used: LLM model used for fix generation
+
+        Returns:
+            The created FixAttempt record
+        """
+        attempt = FixAttempt(
+            finding_id=finding_id,
+            rule_id=rule_id,
+            file_path=file_path,
+            line_number=line_number,
+            severity=severity,
+            model_used=model_used,
+        )
+        self.attempts.append(attempt)
+        self._auto_save()
+
+        logger.info(
+            "fix_attempt_recorded",
+            extra={
+                "finding_id": finding_id,
+                "rule_id": rule_id,
+                "file_path": file_path,
+                "line_number": line_number,
+            },
+        )
+
+        return attempt
+
+    def update_attempt(
+        self,
+        attempt: FixAttempt,
+        *,
+        status: str | None = None,
+        error: str | None = None,
+        diff_preview: str | None = None,
+        lines_added: int | None = None,
+        lines_removed: int | None = None,
+        backup_path: str | None = None,
+    ) -> None:
+        """Update an existing attempt record.
+
+        Args:
+            attempt: The attempt to update
+            status: New status (approved, applied, rejected, failed)
+            error: Error message if failed
+            diff_preview: Preview of the diff (truncated for security)
+            lines_added: Number of lines added
+            lines_removed: Number of lines removed
+            backup_path: Path to backup file if created
+        """
+        if status is not None:
+            attempt.status = status
+        if error is not None:
+            attempt.error = error
+        if diff_preview is not None:
+            # Truncate diff preview to avoid logging sensitive code
+            attempt.diff_preview = diff_preview[:500] if len(diff_preview) > 500 else diff_preview
+        if lines_added is not None:
+            attempt.lines_added = lines_added
+        if lines_removed is not None:
+            attempt.lines_removed = lines_removed
+        if backup_path is not None:
+            attempt.backup_path = backup_path
+
+        self._auto_save()
+
+        logger.info(
+            "fix_attempt_updated",
+            extra={
+                "finding_id": attempt.finding_id,
+                "status": attempt.status,
+                "lines_changed": (attempt.lines_added + attempt.lines_removed),
+            },
+        )
+
+    def mark_applied(
+        self,
+        attempt: FixAttempt,
+        lines_added: int,
+        lines_removed: int,
+        backup_path: str | None = None,
+    ) -> None:
+        """Mark an attempt as successfully applied."""
+        self.update_attempt(
+            attempt,
+            status="applied",
+            lines_added=lines_added,
+            lines_removed=lines_removed,
+            backup_path=backup_path,
+        )
+
+    def mark_failed(self, attempt: FixAttempt, error: str) -> None:
+        """Mark an attempt as failed."""
+        self.update_attempt(attempt, status="failed", error=error)
+
+    def mark_rejected(self, attempt: FixAttempt, reason: str = "") -> None:
+        """Mark an attempt as rejected by user."""
+        self.update_attempt(attempt, status="rejected", error=reason or "User rejected")
+
+    @property
+    def summary(self) -> dict[str, int]:
+        """Get summary counts by status."""
+        counts: dict[str, int] = {
+            "total": len(self.attempts),
+            "pending": 0,
+            "approved": 0,
+            "applied": 0,
+            "rejected": 0,
+            "failed": 0,
+        }
+        for attempt in self.attempts:
+            if attempt.status in counts:
+                counts[attempt.status] += 1
+        return counts
+
+    def set_output_path(self, path: Path) -> None:
+        """Set the output path for auto-saving."""
+        self._output_path = path
+        self._auto_save()
+
+    def _auto_save(self) -> None:
+        """Auto-save if output path is set."""
+        if self._output_path:
+            self.save(self._output_path)
+
+    def save(self, path: Path) -> None:
+        """Save audit log to JSON file.
+
+        Args:
+            path: Output path for the JSON file
+        """
+        data = {
+            "session_id": self.session_id,
+            "repo_path": self.repo_path,
+            "started_at": self.started_at,
+            "model_mode": self.model_mode,
+            "summary": self.summary,
+            "attempts": [a.to_dict() for a in self.attempts],
+        }
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, indent=2))
+
+        logger.debug("audit_log_saved", extra={"path": str(path)})
+
+    @classmethod
+    def load(cls, path: Path) -> FixAuditLog:
+        """Load audit log from JSON file.
+
+        Args:
+            path: Path to the JSON file
+
+        Returns:
+            Loaded FixAuditLog instance
+        """
+        data = json.loads(path.read_text())
+
+        log = cls(
+            session_id=data["session_id"],
+            repo_path=data["repo_path"],
+            started_at=data.get("started_at", ""),
+            model_mode=data.get("model_mode", "local"),
+        )
+
+        for attempt_data in data.get("attempts", []):
+            attempt = FixAttempt(
+                finding_id=attempt_data["finding_id"],
+                rule_id=attempt_data["rule_id"],
+                file_path=attempt_data["file_path"],
+                line_number=attempt_data["line_number"],
+                severity=attempt_data["severity"],
+                timestamp=attempt_data.get("timestamp", ""),
+                model_used=attempt_data.get("model_used", ""),
+                status=attempt_data.get("status", "pending"),
+                error=attempt_data.get("error"),
+                diff_preview=attempt_data.get("diff_preview"),
+                lines_added=attempt_data.get("lines_added", 0),
+                lines_removed=attempt_data.get("lines_removed", 0),
+                backup_path=attempt_data.get("backup_path"),
+            )
+            log.attempts.append(attempt)
+
+        return log
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "session_id": self.session_id,
+            "repo_path": self.repo_path,
+            "started_at": self.started_at,
+            "model_mode": self.model_mode,
+            "summary": self.summary,
+            "attempts": [a.to_dict() for a in self.attempts],
+        }
+
+
+def create_session_id() -> str:
+    """Generate a unique session ID for audit logging."""
+    import secrets
+
+    timestamp = datetime.now(UTC).strftime("%Y%m%d-%H%M%S")
+    random_suffix = secrets.token_hex(4)
+    return f"fix-{timestamp}-{random_suffix}"