kekkai-cli 1.0.0__py3-none-any.whl

kekkai/github/commenter.py

@@ -0,0 +1,198 @@
+"""GitHub PR commenter for posting scan findings."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import httpx  # type: ignore[import-not-found,unused-ignore]
+
+from ..scanners.base import Finding, Severity
+from .models import GitHubConfig, PRComment, PRCommentResult
+from .sanitizer import escape_markdown, redact_secrets
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+logger = logging.getLogger(__name__)
+
+MAX_COMMENTS_PER_PR = 50
+SEVERITY_EMOJI = {
+    Severity.CRITICAL: "🔴",
+    Severity.HIGH: "🟠",
+    Severity.MEDIUM: "🟡",
+    Severity.LOW: "🟢",
+    Severity.INFO: "🔵",
+    Severity.UNKNOWN: "⚪",
+}
+SEVERITY_ORDER = ["critical", "high", "medium", "low", "info", "unknown"]
+
+
+def post_pr_comments(
+    findings: Sequence[Finding],
+    config: GitHubConfig,
+    max_comments: int = MAX_COMMENTS_PER_PR,
+    min_severity: str = "medium",
+    timeout: float = 60.0,
+) -> PRCommentResult:
+    """Post findings as PR review comments.
+
+    Args:
+        findings: List of findings to post.
+        config: GitHub API configuration.
+        max_comments: Maximum number of comments to post.
+        min_severity: Minimum severity level to include.
+        timeout: HTTP request timeout in seconds.
+
+    Returns:
+        Result containing success status and counts.
+    """
+    # Filter and prepare comments
+    filtered = _filter_findings(findings, min_severity)
+    deduped = _dedupe_by_location(filtered)
+    limited = deduped[:max_comments]
+
+    if not limited:
+        return PRCommentResult(
+            success=True,
+            comments_posted=0,
+            comments_skipped=len(findings) - len(limited),
+        )
+
+    # Build comments for findings with file paths
+    comments = []
+    skipped = 0
+    for finding in limited:
+        if not finding.file_path:
+            skipped += 1
+            continue
+        comment = PRComment(
+            path=finding.file_path,
+            line=finding.line or 1,
+            body=_format_comment(finding),
+        )
+        comments.append(comment)
+
+    if not comments:
+        return PRCommentResult(
+            success=True,
+            comments_posted=0,
+            comments_skipped=len(findings),
+        )
+
+    # Post review with comments
+    try:
+        review_url = _create_review(config, comments, timeout)
+        return PRCommentResult(
+            success=True,
+            comments_posted=len(comments),
+            comments_skipped=len(findings) - len(comments),
+            review_url=review_url,
+        )
+    except httpx.HTTPStatusError as e:
+        logger.error("GitHub API error: %s", e.response.text)
+        return PRCommentResult(
+            success=False,
+            errors=[f"GitHub API error: {e.response.status_code}"],
+        )
+    except httpx.RequestError as e:
+        logger.error("Request error: %s", e)
+        return PRCommentResult(
+            success=False,
+            errors=[f"Request failed: {e!s}"],
+        )
+
+
+def _create_review(
+    config: GitHubConfig,
+    comments: list[PRComment],
+    timeout: float,
+) -> str | None:
+    """Create a PR review with inline comments."""
+    url = f"{config.api_base}/repos/{config.owner}/{config.repo}/pulls/{config.pr_number}/reviews"
+
+    headers = {
+        "Authorization": f"Bearer {config.token}",
+        "Accept": "application/vnd.github.v3+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+
+    payload = {
+        "event": "COMMENT",
+        "body": _format_summary(len(comments)),
+        "comments": [c.to_dict() for c in comments],
+    }
+
+    with httpx.Client(timeout=timeout) as client:
+        response = client.post(url, headers=headers, json=payload)
+        response.raise_for_status()
+        data: dict[str, str] = response.json()
+        return data.get("html_url")
+
+
+def _format_comment(finding: Finding) -> str:
+    """Format a finding as a safe markdown comment."""
+    emoji = SEVERITY_EMOJI.get(finding.severity, "⚪")
+    severity_text = finding.severity.value.upper()
+
+    # Sanitize user-controlled content
+    title = escape_markdown(finding.title)
+    description = redact_secrets(finding.description)
+    description = escape_markdown(description[:500])
+
+    lines = [
+        f"### {emoji} {severity_text}: {title}",
+        "",
+        f"**Scanner:** {escape_markdown(finding.scanner)}",
+    ]
+
+    if finding.rule_id:
+        # Rule IDs in code blocks don't need escaping, but sanitize backticks
+        rule_id = finding.rule_id.replace("`", "'")
+        lines.append(f"**Rule:** `{rule_id}`")
+
+    if finding.cve:
+        cve = finding.cve.replace("`", "'")
+        lines.append(f"**CVE:** `{cve}`")
+
+    if finding.cwe:
+        cwe = finding.cwe.replace("`", "'")
+        lines.append(f"**CWE:** `{cwe}`")
+
+    lines.extend(["", description, ""])
+    lines.append("---")
+    lines.append("<sub>Posted by [Kekkai](https://github.com/kademoslabs/kekkai)</sub>")
+
+    return "\n".join(lines)
+
+
+def _format_summary(count: int) -> str:
+    """Format the review summary body."""
+    return f"🛡️ **Kekkai Security Scan** found {count} finding(s) in this PR."
+
+
+def _filter_findings(
+    findings: Sequence[Finding],
+    min_severity: str,
+) -> list[Finding]:
+    """Filter findings by minimum severity level."""
+    try:
+        min_idx = SEVERITY_ORDER.index(min_severity.lower())
+    except ValueError:
+        min_idx = 2  # Default to medium
+
+    return [f for f in findings if SEVERITY_ORDER.index(f.severity.value.lower()) <= min_idx]
+
+
+def _dedupe_by_location(findings: Sequence[Finding]) -> list[Finding]:
+    """Deduplicate findings by file path and line number."""
+    seen: set[tuple[str | None, int | None]] = set()
+    result: list[Finding] = []
+
+    for finding in findings:
+        key = (finding.file_path, finding.line)
+        if key not in seen:
+            seen.add(key)
+            result.append(finding)
+
+    return result

kekkai/github/models.py

@@ -0,0 +1,56 @@
+"""Data models for GitHub PR commenter."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class GitHubConfig:
+    """Configuration for GitHub API access."""
+
+    token: str
+    owner: str
+    repo: str
+    pr_number: int
+    api_base: str = "https://api.github.com"
+
+    def __post_init__(self) -> None:
+        if not self.token:
+            raise ValueError("GitHub token is required")
+        if not self.owner:
+            raise ValueError("Repository owner is required")
+        if not self.repo:
+            raise ValueError("Repository name is required")
+        if self.pr_number < 1:
+            raise ValueError("PR number must be positive")
+
+
+@dataclass(frozen=True)
+class PRComment:
+    """A comment to post on a PR."""
+
+    path: str
+    line: int
+    body: str
+    side: str = "RIGHT"
+
+    def to_dict(self) -> dict[str, str | int]:
+        """Convert to GitHub API format."""
+        return {
+            "path": self.path,
+            "line": self.line,
+            "body": self.body,
+            "side": self.side,
+        }
+
+
+@dataclass
+class PRCommentResult:
+    """Result of posting PR comments."""
+
+    success: bool
+    comments_posted: int = 0
+    comments_skipped: int = 0
+    errors: list[str] = field(default_factory=list)
+    review_url: str | None = None

kekkai/github/sanitizer.py

@@ -0,0 +1,112 @@
+"""Sanitization utilities for GitHub PR comments."""
+
+from __future__ import annotations
+
+import re
+
+# Markdown special characters that need escaping
+MARKDOWN_SPECIAL_CHARS = r"[\`*_{}\[\]()#+\-.!|>~]"
+
+# Patterns for potential secrets (conservative to avoid false positives)
+_AWS_KEY_PATTERN = re.compile(r"AKIA[0-9A-Z]{16}", re.IGNORECASE)
+_API_KEY_PATTERN = re.compile(
+    r"(?:api[_-]?key|apikey|secret|password|token)\s*[:=]\s*['\"]?" r"([A-Za-z0-9_\-]{20,})['\"]?",
+    re.IGNORECASE,
+)
+_BEARER_PATTERN = re.compile(r"Bearer\s+[A-Za-z0-9_\-\.]{20,}", re.IGNORECASE)
+_JWT_PATTERN = re.compile(r"eyJ[A-Za-z0-9_-]*\.eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*")
+_PRIVATE_KEY_PATTERN = re.compile(
+    r"-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----.*?" r"-----END\s+(?:RSA\s+)?PRIVATE\s+KEY-----",
+    re.DOTALL,
+)
+_GITHUB_TOKEN_PATTERN = re.compile(r"gh[pousr]_[A-Za-z0-9_]{36,}")
+_HEX_SECRET_PATTERN = re.compile(r"(?<![A-Fa-f0-9])[A-Fa-f0-9]{40,}(?![A-Fa-f0-9])")
+
+# Order matters: specific patterns first, generic last
+SECRET_PATTERNS = [
+    # Specific patterns first
+    (_JWT_PATTERN, "[JWT_REDACTED]"),
+    (_GITHUB_TOKEN_PATTERN, "[GITHUB_TOKEN_REDACTED]"),
+    (_AWS_KEY_PATTERN, "[AWS_KEY_REDACTED]"),
+    (_PRIVATE_KEY_PATTERN, "[PRIVATE_KEY_REDACTED]"),
+    (_BEARER_PATTERN, "Bearer [REDACTED]"),
+    # Generic patterns last
+    (_API_KEY_PATTERN, "[REDACTED]"),
+    (_HEX_SECRET_PATTERN, "[HEX_SECRET_REDACTED]"),
+]
+
+# Patterns for redacting common sensitive values (applied last)
+SENSITIVE_VALUE_PATTERN = re.compile(
+    r"(api[_-]?key|apikey|secret|password|credential|auth)\s*[:=]\s*['\"]?([^\s'\"]{8,})['\"]?",
+    re.IGNORECASE,
+)
+
+
+def escape_markdown(text: str) -> str:
+    """Escape markdown special characters to prevent injection.
+
+    Args:
+        text: Raw text that may contain markdown special characters.
+
+    Returns:
+        Text with markdown characters escaped.
+    """
+    if not text:
+        return ""
+
+    # Escape backslashes first to avoid double-escaping
+    result = text.replace("\\", "\\\\")
+
+    # Escape markdown special characters
+    for char in "`*_{}[]()#+-.!|>~":
+        result = result.replace(char, f"\\{char}")
+
+    # Remove potential HTML tags
+    result = re.sub(r"<[^>]+>", "", result)
+
+    # Truncate to reasonable length
+    max_length = 2000
+    if len(result) > max_length:
+        result = result[: max_length - 3] + "..."
+
+    return result
+
+
+def redact_secrets(text: str) -> str:
+    """Redact potential secrets from text.
+
+    Args:
+        text: Text that may contain secrets.
+
+    Returns:
+        Text with secrets redacted.
+    """
+    if not text:
+        return ""
+
+    result = text
+
+    # Apply secret patterns
+    for pattern, replacement in SECRET_PATTERNS:
+        result = pattern.sub(replacement, result)
+
+    # Redact sensitive key=value pairs
+    result = SENSITIVE_VALUE_PATTERN.sub(r"\1=[REDACTED]", result)
+
+    return result
+
+
+def sanitize_for_comment(text: str) -> str:
+    """Full sanitization pipeline for PR comments.
+
+    Args:
+        text: Raw text to sanitize.
+
+    Returns:
+        Text safe for PR comments.
+    """
+    # First redact secrets
+    text = redact_secrets(text)
+    # Then escape markdown
+    text = escape_markdown(text)
+    return text

kekkai/installer/__init__.py

@@ -0,0 +1,39 @@
+"""Tool installer module for automatic binary management."""
+
+from .errors import (
+    DownloadError,
+    ExtractionError,
+    InstallerError,
+    SecurityError,
+    UnsupportedPlatformError,
+)
+from .manager import ToolInstaller, get_installer
+from .manifest import (
+    TOOL_MANIFESTS,
+    ToolManifest,
+    get_download_url,
+    get_expected_hash,
+    get_manifest,
+    get_platform_key,
+    validate_manifest_url,
+)
+from .verify import compute_sha256, verify_checksum
+
+__all__ = [
+    "DownloadError",
+    "ExtractionError",
+    "InstallerError",
+    "SecurityError",
+    "TOOL_MANIFESTS",
+    "ToolInstaller",
+    "ToolManifest",
+    "UnsupportedPlatformError",
+    "compute_sha256",
+    "get_download_url",
+    "get_expected_hash",
+    "get_installer",
+    "get_manifest",
+    "get_platform_key",
+    "validate_manifest_url",
+    "verify_checksum",
+]

kekkai/installer/errors.py

@@ -0,0 +1,23 @@
+"""Custom exceptions for the installer module."""
+
+from __future__ import annotations
+
+
+class InstallerError(Exception):
+    """Base exception for installer errors."""
+
+
+class SecurityError(InstallerError):
+    """Raised on security verification failure (checksum mismatch, etc.)."""
+
+
+class DownloadError(InstallerError):
+    """Raised when download fails."""
+
+
+class ExtractionError(InstallerError):
+    """Raised when archive extraction fails."""
+
+
+class UnsupportedPlatformError(InstallerError):
+    """Raised when the current platform is not supported."""

kekkai/installer/extract.py

@@ -0,0 +1,161 @@
+"""Archive extraction utilities."""
+
+from __future__ import annotations
+
+import logging
+import os
+import tarfile
+import zipfile
+from pathlib import Path
+
+from .errors import ExtractionError, SecurityError
+
+logger = logging.getLogger(__name__)
+
+
+def _is_safe_path(base_path: Path, target_path: Path) -> bool:
+    """Check if target path is safe (no path traversal).
+
+    Args:
+        base_path: Base extraction directory.
+        target_path: Target path to check.
+
+    Returns:
+        True if path is safe.
+    """
+    try:
+        target_path.resolve().relative_to(base_path.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def extract_tar_gz(archive_path: Path, dest_dir: Path, binary_name: str) -> Path:
+    """Extract a tar.gz archive and return path to binary.
+
+    Args:
+        archive_path: Path to the archive.
+        dest_dir: Destination directory.
+        binary_name: Name of the binary to extract.
+
+    Returns:
+        Path to extracted binary.
+
+    Raises:
+        ExtractionError: If extraction fails.
+        SecurityError: If archive contains path traversal.
+    """
+    try:
+        with tarfile.open(archive_path, "r:gz") as tar:
+            # Security: Check for path traversal
+            for member in tar.getmembers():
+                member_path = dest_dir / member.name
+                if not _is_safe_path(dest_dir, member_path):
+                    raise SecurityError(f"Path traversal detected in archive: {member.name}")
+
+            # Find and extract the binary
+            binary_member = None
+            for member in tar.getmembers():
+                if member.name == binary_name or member.name.endswith(f"/{binary_name}"):
+                    binary_member = member
+                    break
+
+            if not binary_member:
+                raise ExtractionError(f"Binary '{binary_name}' not found in archive")
+
+            # Extract just the binary
+            tar.extract(binary_member, dest_dir, filter="data")
+
+            extracted_path = dest_dir / binary_member.name
+            if not extracted_path.exists():
+                raise ExtractionError(f"Extraction failed: {extracted_path} not found")
+
+            # Move to final location if nested
+            final_path = dest_dir / binary_name
+            if extracted_path != final_path:
+                extracted_path.rename(final_path)
+
+            return final_path
+
+    except tarfile.TarError as e:
+        raise ExtractionError(f"Failed to extract tar.gz: {e}") from e
+
+
+def extract_zip(archive_path: Path, dest_dir: Path, binary_name: str) -> Path:
+    """Extract a zip archive and return path to binary.
+
+    Args:
+        archive_path: Path to the archive.
+        dest_dir: Destination directory.
+        binary_name: Name of the binary to extract.
+
+    Returns:
+        Path to extracted binary.
+
+    Raises:
+        ExtractionError: If extraction fails.
+        SecurityError: If archive contains path traversal.
+    """
+    try:
+        with zipfile.ZipFile(archive_path, "r") as zf:
+            # Security: Check for path traversal
+            for name in zf.namelist():
+                member_path = dest_dir / name
+                if not _is_safe_path(dest_dir, member_path):
+                    raise SecurityError(f"Path traversal detected in archive: {name}")
+
+            # Find and extract the binary
+            binary_name_variants = [binary_name, f"{binary_name}.exe"]
+            binary_member = None
+
+            for name in zf.namelist():
+                base_name = os.path.basename(name)
+                if base_name in binary_name_variants:
+                    binary_member = name
+                    break
+
+            if not binary_member:
+                raise ExtractionError(f"Binary '{binary_name}' not found in archive")
+
+            # Extract just the binary
+            zf.extract(binary_member, dest_dir)
+
+            extracted_path = dest_dir / binary_member
+            if not extracted_path.exists():
+                raise ExtractionError(f"Extraction failed: {extracted_path} not found")
+
+            # Move to final location if nested
+            final_name = binary_name
+            if extracted_path.suffix == ".exe":
+                final_name = f"{binary_name}.exe"
+
+            final_path = dest_dir / final_name
+            if extracted_path != final_path:
+                extracted_path.rename(final_path)
+
+            return final_path
+
+    except zipfile.BadZipFile as e:
+        raise ExtractionError(f"Failed to extract zip: {e}") from e
+
+
+def extract_archive(
+    archive_path: Path, dest_dir: Path, binary_name: str, archive_type: str
+) -> Path:
+    """Extract an archive and return path to binary.
+
+    Args:
+        archive_path: Path to the archive.
+        dest_dir: Destination directory.
+        binary_name: Name of the binary to extract.
+        archive_type: Type of archive ("tar.gz" or "zip").
+
+    Returns:
+        Path to extracted binary.
+    """
+    if archive_type == "tar.gz":
+        return extract_tar_gz(archive_path, dest_dir, binary_name)
+    elif archive_type == "zip":
+        return extract_zip(archive_path, dest_dir, binary_name)
+    else:
+        raise ExtractionError(f"Unsupported archive type: {archive_type}")