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

kekkai/report/generator.py

@@ -0,0 +1,365 @@
+"""Report generation orchestration.
+
+Handles report generation workflow including compliance mapping,
+format selection, and output management.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from kekkai.compliance.mappings import ComplianceMappingResult
+    from kekkai.scanners.base import Finding
+
+
+class ReportFormat(str, Enum):
+    """Available report formats."""
+
+    HTML = "html"
+    PDF = "pdf"
+    COMPLIANCE = "compliance"
+    JSON = "json"
+
+
+@dataclass
+class ReportConfig:
+    """Configuration for report generation."""
+
+    formats: list[ReportFormat] = field(default_factory=lambda: [ReportFormat.HTML])
+    frameworks: list[str] = field(default_factory=lambda: ["PCI-DSS", "SOC2", "OWASP", "HIPAA"])
+    min_severity: str = "info"
+    include_executive_summary: bool = True
+    include_remediation_timeline: bool = True
+    title: str = "Security Scan Report"
+    organization: str = ""
+    project_name: str = ""
+
+
+@dataclass
+class ReportResult:
+    """Result of report generation."""
+
+    success: bool
+    output_files: list[Path] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    generation_time_ms: int = 0
+
+
+@dataclass
+class ReportMetadata:
+    """Metadata included in generated reports."""
+
+    generated_at: str
+    generator_version: str
+    findings_count: int
+    frameworks_mapped: list[str]
+    content_hash: str
+
+
+def generate_report(
+    findings: Sequence[Finding],
+    output_dir: Path,
+    config: ReportConfig | None = None,
+) -> ReportResult:
+    """Generate reports in specified formats.
+
+    Args:
+        findings: Security findings to include
+        output_dir: Directory for output files
+        config: Report configuration
+
+    Returns:
+        ReportResult with output files and status
+    """
+    generator = ReportGenerator(config or ReportConfig())
+    return generator.generate(findings, output_dir)
+
+
+class ReportGenerator:
+    """Orchestrates report generation across formats."""
+
+    def __init__(self, config: ReportConfig) -> None:
+        self.config = config
+
+    def generate(
+        self,
+        findings: Sequence[Finding],
+        output_dir: Path,
+    ) -> ReportResult:
+        """Generate reports for all configured formats."""
+        import time
+
+        start_time = time.monotonic()
+        result = ReportResult(success=True)
+
+        # Ensure output directory exists
+        output_dir = output_dir.expanduser().resolve()
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Filter findings by severity
+        filtered = self._filter_by_severity(list(findings))
+
+        # Map to compliance frameworks
+        from kekkai.compliance import map_findings_to_all_frameworks
+
+        compliance_result = map_findings_to_all_frameworks(filtered)
+
+        # Build report data
+        report_data = self._build_report_data(filtered, compliance_result)
+
+        # Generate each format
+        for fmt in self.config.formats:
+            try:
+                output_path = self._generate_format(fmt, report_data, output_dir)
+                if output_path:
+                    result.output_files.append(output_path)
+            except Exception as e:
+                result.errors.append(f"Failed to generate {fmt.value}: {e}")
+                result.success = False
+
+        result.generation_time_ms = int((time.monotonic() - start_time) * 1000)
+        return result
+
+    def _filter_by_severity(self, findings: list[Finding]) -> list[Finding]:
+        """Filter findings by minimum severity."""
+        from kekkai.scanners.base import Severity
+
+        severity_order = [
+            Severity.CRITICAL,
+            Severity.HIGH,
+            Severity.MEDIUM,
+            Severity.LOW,
+            Severity.INFO,
+            Severity.UNKNOWN,
+        ]
+        min_sev = Severity.from_string(self.config.min_severity)
+        try:
+            min_index = severity_order.index(min_sev)
+        except ValueError:
+            min_index = len(severity_order) - 1
+
+        return [f for f in findings if severity_order.index(f.severity) <= min_index]
+
+    def _build_report_data(
+        self,
+        findings: list[Finding],
+        compliance_result: ComplianceMappingResult,
+    ) -> dict[str, Any]:
+        """Build unified report data structure."""
+        from kekkai.output import VERSION
+
+        # Calculate content hash for integrity
+        content = json.dumps(
+            [f.dedupe_hash() for f in findings],
+            sort_keys=True,
+        )
+        content_hash = hashlib.sha256(content.encode()).hexdigest()[:16]
+
+        metadata = ReportMetadata(
+            generated_at=datetime.now(UTC).isoformat(),
+            generator_version=VERSION,
+            findings_count=len(findings),
+            frameworks_mapped=list(compliance_result.framework_summary.keys()),
+            content_hash=content_hash,
+        )
+
+        # Severity counts
+        severity_counts = self._count_by_severity(findings)
+
+        # Executive summary
+        executive_summary = self._build_executive_summary(findings, compliance_result)
+
+        # Remediation timeline
+        remediation_timeline = self._build_remediation_timeline(findings)
+
+        return {
+            "metadata": metadata,
+            "config": self.config,
+            "findings": findings,
+            "compliance": compliance_result,
+            "severity_counts": severity_counts,
+            "executive_summary": executive_summary,
+            "remediation_timeline": remediation_timeline,
+        }
+
+    def _count_by_severity(self, findings: list[Finding]) -> dict[str, int]:
+        """Count findings by severity."""
+        counts: dict[str, int] = {
+            "critical": 0,
+            "high": 0,
+            "medium": 0,
+            "low": 0,
+            "info": 0,
+        }
+        for f in findings:
+            key = f.severity.value
+            if key in counts:
+                counts[key] += 1
+        return counts
+
+    def _build_executive_summary(
+        self,
+        findings: list[Finding],
+        compliance_result: ComplianceMappingResult,
+    ) -> dict[str, Any]:
+        """Build executive summary section."""
+        severity_counts = self._count_by_severity(findings)
+
+        # Risk score (simple weighted calculation)
+        risk_score = (
+            severity_counts["critical"] * 10
+            + severity_counts["high"] * 5
+            + severity_counts["medium"] * 2
+            + severity_counts["low"] * 1
+        )
+        max_possible = len(findings) * 10 if findings else 1
+        risk_percentage = min(100, int((risk_score / max_possible) * 100))
+
+        # Risk level
+        if risk_percentage >= 70:
+            risk_level = "Critical"
+        elif risk_percentage >= 50:
+            risk_level = "High"
+        elif risk_percentage >= 30:
+            risk_level = "Medium"
+        elif risk_percentage > 0:
+            risk_level = "Low"
+        else:
+            risk_level = "None"
+
+        return {
+            "total_findings": len(findings),
+            "severity_counts": severity_counts,
+            "risk_score": risk_score,
+            "risk_percentage": risk_percentage,
+            "risk_level": risk_level,
+            "frameworks_impacted": compliance_result.framework_summary,
+            "top_issues": self._get_top_issues(findings),
+        }
+
+    def _get_top_issues(self, findings: list[Finding], limit: int = 5) -> list[dict[str, Any]]:
+        """Get top issues by severity."""
+        sorted_findings = sorted(
+            findings,
+            key=lambda f: (
+                ["critical", "high", "medium", "low", "info", "unknown"].index(f.severity.value),
+                f.title,
+            ),
+        )
+        return [
+            {
+                "title": f.title,
+                "severity": f.severity.value,
+                "file": f.file_path,
+                "rule_id": f.rule_id,
+            }
+            for f in sorted_findings[:limit]
+        ]
+
+    def _build_remediation_timeline(self, findings: list[Finding]) -> dict[str, Any]:
+        """Build remediation timeline recommendations."""
+        severity_counts = self._count_by_severity(findings)
+
+        # SLA recommendations based on industry standards
+        return {
+            "immediate": {
+                "description": "Address within 24 hours",
+                "count": severity_counts["critical"],
+                "severity": "critical",
+            },
+            "urgent": {
+                "description": "Address within 7 days",
+                "count": severity_counts["high"],
+                "severity": "high",
+            },
+            "standard": {
+                "description": "Address within 30 days",
+                "count": severity_counts["medium"],
+                "severity": "medium",
+            },
+            "planned": {
+                "description": "Address within 90 days",
+                "count": severity_counts["low"],
+                "severity": "low",
+            },
+            "informational": {
+                "description": "Review and document",
+                "count": severity_counts["info"],
+                "severity": "info",
+            },
+        }
+
+    def _generate_format(
+        self,
+        fmt: ReportFormat,
+        report_data: dict[str, Any],
+        output_dir: Path,
+    ) -> Path | None:
+        """Generate a specific report format."""
+        if fmt == ReportFormat.HTML:
+            from .html import HTMLReportGenerator
+
+            html_gen = HTMLReportGenerator()
+            return html_gen.generate(report_data, output_dir)
+
+        if fmt == ReportFormat.PDF:
+            from .pdf import PDFReportGenerator
+
+            pdf_gen = PDFReportGenerator()
+            return pdf_gen.generate(report_data, output_dir)
+
+        if fmt == ReportFormat.COMPLIANCE:
+            from .compliance_matrix import generate_compliance_matrix
+
+            return generate_compliance_matrix(report_data, output_dir)
+
+        if fmt == ReportFormat.JSON:
+            return self._generate_json(report_data, output_dir)
+
+        return None
+
+    def _generate_json(self, report_data: dict[str, Any], output_dir: Path) -> Path:
+        """Generate JSON report."""
+        output_path = output_dir / "report.json"
+
+        # Convert dataclasses to dicts for JSON serialization
+        json_data = {
+            "metadata": {
+                "generated_at": report_data["metadata"].generated_at,
+                "generator_version": report_data["metadata"].generator_version,
+                "findings_count": report_data["metadata"].findings_count,
+                "frameworks_mapped": report_data["metadata"].frameworks_mapped,
+                "content_hash": report_data["metadata"].content_hash,
+            },
+            "executive_summary": report_data["executive_summary"],
+            "remediation_timeline": report_data["remediation_timeline"],
+            "severity_counts": report_data["severity_counts"],
+            "compliance_summary": report_data["compliance"].framework_summary,
+            "findings": [
+                {
+                    "title": f.title,
+                    "severity": f.severity.value,
+                    "scanner": f.scanner,
+                    "file_path": f.file_path,
+                    "line": f.line,
+                    "rule_id": f.rule_id,
+                    "cwe": f.cwe,
+                    "cve": f.cve,
+                    "description": f.description,
+                }
+                for f in report_data["findings"]
+            ],
+        }
+
+        output_path.write_text(json.dumps(json_data, indent=2))
+        return output_path

kekkai/report/html.py

@@ -0,0 +1,69 @@
+"""HTML report generator.
+
+Uses Jinja2 for templating with autoescaping enabled for XSS prevention.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+
+class HTMLReportGenerator:
+    """Generates HTML security reports."""
+
+    def __init__(self) -> None:
+        self.env = Environment(
+            loader=PackageLoader("kekkai.report", "templates"),
+            autoescape=select_autoescape(["html", "xml"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+        # Add custom filters
+        self.env.filters["severity_class"] = self._severity_class
+        self.env.filters["severity_badge"] = self._severity_badge
+
+    def generate(self, report_data: dict[str, Any], output_dir: Path) -> Path:
+        """Generate HTML report file."""
+        template = self.env.get_template("report.html")
+
+        html_content = template.render(
+            metadata=report_data["metadata"],
+            config=report_data["config"],
+            findings=report_data["findings"],
+            compliance=report_data["compliance"],
+            severity_counts=report_data["severity_counts"],
+            executive_summary=report_data["executive_summary"],
+            remediation_timeline=report_data["remediation_timeline"],
+        )
+
+        output_path = output_dir / "report.html"
+        output_path.write_text(html_content, encoding="utf-8")
+        return output_path
+
+    @staticmethod
+    def _severity_class(severity: str) -> str:
+        """Return CSS class for severity level."""
+        classes = {
+            "critical": "severity-critical",
+            "high": "severity-high",
+            "medium": "severity-medium",
+            "low": "severity-low",
+            "info": "severity-info",
+        }
+        return classes.get(severity.lower(), "severity-unknown")
+
+    @staticmethod
+    def _severity_badge(severity: str) -> str:
+        """Return badge HTML for severity level."""
+        colors = {
+            "critical": "#dc3545",
+            "high": "#fd7e14",
+            "medium": "#ffc107",
+            "low": "#17a2b8",
+            "info": "#6c757d",
+        }
+        color = colors.get(severity.lower(), "#6c757d")
+        return f'<span class="badge" style="background-color: {color};">{severity.upper()}</span>'

kekkai/report/pdf.py

@@ -0,0 +1,63 @@
+"""PDF report generator.
+
+Uses weasyprint for HTML-to-PDF conversion if available.
+Falls back to HTML-only with warning if weasyprint is not installed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .html import HTMLReportGenerator
+
+# Check weasyprint availability
+_WEASYPRINT_AVAILABLE = False
+try:
+    from weasyprint import HTML as WeasyprintHTML  # type: ignore[import-not-found]
+
+    _WEASYPRINT_AVAILABLE = True
+except ImportError:
+    WeasyprintHTML = None
+
+
+class PDFReportGenerator:
+    """Generates PDF security reports.
+
+    Requires weasyprint to be installed. If not available,
+    falls back to HTML generation with a warning.
+    """
+
+    def __init__(self) -> None:
+        self.html_generator = HTMLReportGenerator()
+
+    @property
+    def is_available(self) -> bool:
+        """Check if PDF generation is available."""
+        return _WEASYPRINT_AVAILABLE
+
+    def generate(self, report_data: dict[str, Any], output_dir: Path) -> Path:
+        """Generate PDF report file.
+
+        If weasyprint is not available, generates HTML instead.
+        """
+        # First generate HTML
+        html_path = self.html_generator.generate(report_data, output_dir)
+
+        if not _WEASYPRINT_AVAILABLE:
+            # Return HTML path with warning - caller should handle
+            return html_path
+
+        # Convert HTML to PDF
+        pdf_path = output_dir / "report.pdf"
+
+        html_content = html_path.read_text(encoding="utf-8")
+        html_doc = WeasyprintHTML(string=html_content, base_url=str(output_dir))
+        html_doc.write_pdf(pdf_path)
+
+        return pdf_path
+
+
+def is_pdf_available() -> bool:
+    """Check if PDF generation is available."""
+    return _WEASYPRINT_AVAILABLE

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"