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

kekkai/cli.py

@@ -604,6 +604,36 @@ def _command_scan(
     )
     manifest.write_manifest(run_dir / "run.json", run_manifest)
 
+    # Generate unified report (aggregates all scanner findings)
+    if scan_results:
+        from .report.unified import UnifiedReportError, generate_unified_report
+
+        # Determine output path for unified report
+        if output_path:
+            # --output flag provided: use it for unified report
+            unified_report_path = Path(output_path).expanduser().resolve()
+            # Security: Validate path (ASVS V5.3.3)
+            if not is_within_base(base_dir, unified_report_path):
+                # Allow explicit paths outside base_dir, but warn
+                console.print(
+                    f"[warning]Writing outside kekkai home: {unified_report_path}[/warning]"
+                )
+        else:
+            # Default: save in run directory
+            unified_report_path = run_dir / "kekkai-report.json"
+
+        try:
+            generate_unified_report(
+                scan_results=scan_results,
+                output_path=unified_report_path,
+                run_id=run_id,
+                commit_sha=commit_sha,
+            )
+            console.print(f"[success]Unified report:[/success] {unified_report_path}")
+        except UnifiedReportError as e:
+            err_msg = sanitize_error(str(e))
+            console.print(f"[warning]Failed to generate unified report: {err_msg}[/warning]")
+
     # Collect all findings for policy evaluation
     all_findings: list[Finding] = []
     scan_errors: list[str] = []
@@ -822,6 +852,26 @@ def _resolve_github_repo(override: str | None) -> tuple[str | None, str | None]:
     return None, None
 
 
+def _normalize_scanner_name(stem: str) -> str:
+    """Normalize filename stem to scanner name.
+
+    Strips the "-results" suffix from scanner output filenames.
+
+    Examples:
+        gitleaks-results -> gitleaks
+        trivy-results -> trivy
+        semgrep-results -> semgrep
+        custom-scanner -> custom-scanner
+
+    Args:
+        stem: File stem (name without extension).
+
+    Returns:
+        Normalized scanner name.
+    """
+    return stem.removesuffix("-results")
+
+
 def _create_scanner(
     name: str,
     zap_target_url: str | None = None,
@@ -1106,22 +1156,57 @@ def _threatflow_banner() -> str:
 def _command_triage(parsed: argparse.Namespace) -> int:
     """Run interactive triage TUI."""
     from .triage import run_triage
+    from .triage.loader import load_findings_from_path
 
     input_path_str = cast(str | None, getattr(parsed, "input", None))
     output_path_str = cast(str | None, getattr(parsed, "output", None))
 
-    input_path = Path(input_path_str).expanduser().resolve() if input_path_str else None
-    output_path = Path(output_path_str).expanduser().resolve() if output_path_str else None
+    # Default to latest run if no input specified
+    if not input_path_str:
+        runs_dir = app_base_dir() / "runs"
+        if runs_dir.exists():
+            run_dirs = sorted(
+                [d for d in runs_dir.iterdir() if d.is_dir()],
+                key=lambda d: d.stat().st_mtime,
+            )
+            if run_dirs:
+                input_path = run_dirs[-1]
+                console.print(f"[info]Using latest run: {input_path.name}[/info]\n")
+            else:
+                console.print("[danger]No scan runs found. Run 'kekkai scan' first.[/danger]")
+                return 1
+        else:
+            console.print("[danger]No scan runs found. Run 'kekkai scan' first.[/danger]")
+            return 1
+    else:
+        input_path = Path(input_path_str).expanduser().resolve()
 
-    if input_path and not input_path.exists():
-        console.print(f"[danger]Error:[/danger] Input file not found: {input_path}")
+    if not input_path.exists():
+        console.print(f"[danger]Error:[/danger] Input not found: {input_path}")
         return 1
 
+    output_path = Path(output_path_str).expanduser().resolve() if output_path_str else None
+
     console.print("[bold cyan]Kekkai Triage[/bold cyan] - Interactive Finding Review")
     console.print("Use j/k to navigate, f=false positive, c=confirmed, d=deferred")
     console.print("Press Ctrl+S to save, q to quit\n")
 
-    return run_triage(input_path=input_path, output_path=output_path)
+    # Use new loader that supports raw scanner outputs
+    findings, errors = load_findings_from_path(input_path)
+
+    if errors:
+        console.print("[warning]Warnings:[/warning]")
+        for err in errors[:5]:  # Limit to first 5
+            console.print(f"  - {err}")
+        console.print()
+
+    if not findings:
+        console.print("[warning]No findings to triage.[/warning]")
+        return 0
+
+    console.print(f"[info]Loaded {len(findings)} finding(s)[/info]\n")
+
+    return run_triage(findings=findings, output_path=output_path)
 
 
 def _command_fix(parsed: argparse.Namespace) -> int:
@@ -1414,9 +1499,13 @@ def _command_upload(parsed: argparse.Namespace) -> int:
     console.print(f"Product: {product_name}")
     console.print(f"Engagement: {engagement_name}")
 
-    # Find and load scan results
-    scan_files = list(run_dir.glob("*.json"))
-    scan_files = [f for f in scan_files if f.name not in ("run.json", "policy-result.json")]
+    # Find and load scan results - prefer *-results.json first
+    scan_files = sorted(run_dir.glob("*-results.json"))
+    if not scan_files:
+        # Fallback to all JSON (excluding metadata files)
+        scan_files = sorted(
+            [f for f in run_dir.glob("*.json") if f.name not in ("run.json", "policy-result.json")]
+        )
 
     if not scan_files:
         console.print(f"[danger]Error:[/danger] No scan results found in {run_dir}")
@@ -1429,35 +1518,39 @@ def _command_upload(parsed: argparse.Namespace) -> int:
     scanners_map: dict[str, Scanner] = {}
 
     for scan_file in scan_files:
-        scanner_name = scan_file.stem  # e.g., "trivy", "semgrep", "gitleaks"
+        # Normalize scanner name: "gitleaks-results" -> "gitleaks"
+        scanner_name = _normalize_scanner_name(scan_file.stem)
         console.print(f"  Loading {scanner_name}...")
 
+        # Load raw JSON
         try:
-            with scan_file.open() as f:
-                data = _json.load(f)
-        except _json.JSONDecodeError as e:
+            raw_text = scan_file.read_text(encoding="utf-8")
+            _json.loads(raw_text)  # Validate JSON syntax
+        except (OSError, _json.JSONDecodeError) as e:
             console.print(f"    [warning]Skipped (invalid JSON): {e}[/warning]")
             continue
 
-        # Parse findings based on format
-        findings = _parse_findings_from_json(data)
-
-        if findings:
-            scan_results.append(
-                ScanResult(
-                    scanner=scanner_name,
-                    success=True,
-                    findings=findings,
-                    raw_output_path=scan_file,
-                    duration_ms=0,
-                )
+        # Create scanner and use canonical parser
+        scanner = _create_scanner(scanner_name)
+        if not scanner:
+            console.print("    [warning]Skipped (unknown scanner)[/warning]")
+            continue
+
+        # Use canonical scanner parser (reuses validated logic)
+        findings = scanner.parse(raw_text)
+
+        scan_results.append(
+            ScanResult(
+                scanner=scanner.name,  # Use canonical scanner name
+                success=True,
+                findings=findings,
+                raw_output_path=scan_file,
+                duration_ms=0,
             )
-            # Create scanner instance for import
-            scanner = _create_scanner(scanner_name)
-            if scanner:
-                scanners_map[scanner_name] = scanner
+        )
+        scanners_map[scanner.name] = scanner
 
-            console.print(f"    {len(findings)} findings")
+        console.print(f"    {len(findings)} finding(s)")
 
     if not scan_results:
         console.print("[danger]Error:[/danger] No valid scan results to upload")
@@ -1493,11 +1586,9 @@ def _command_upload(parsed: argparse.Namespace) -> int:
     )
 
     success_count = 0
-    scanner_names_list = list(scanners_map.keys())
     for idx, ir in enumerate(import_results):
-        scanner_label = (
-            scanner_names_list[idx] if idx < len(scanner_names_list) else f"scanner-{idx}"
-        )
+        # Label based on actual scan_results order (not scanners_map keys)
+        scanner_label = scan_results[idx].scanner if idx < len(scan_results) else f"scanner-{idx}"
         if ir.success:
             success_count += 1
             console.print(

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/output.py

@@ -57,7 +57,7 @@ BANNER_ASCII = r"""
 /_/\_\\___/_/\_/_/\_\\_,_/_/
 """
 
-VERSION = "1.1.0"
+VERSION = "1.1.1"
 
 
 def print_dashboard() -> None:

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/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",
 ]