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

kekkai/cli.py

@@ -58,6 +58,11 @@ def main(argv: Sequence[str] | None = None) -> int:
     init_parser = subparsers.add_parser("init", help="initialize config and directories")
     init_parser.add_argument("--config", type=str, help="Path to config file")
     init_parser.add_argument("--force", action="store_true", help="Overwrite existing config")
+    init_parser.add_argument(
+        "--ci",
+        action="store_true",
+        help="Auto-generate GitHub Actions workflow for CI/CD integration",
+    )
 
     scan_parser = subparsers.add_parser("scan", help="run a scan pipeline")
     scan_parser.add_argument("--config", type=str, help="Path to config file")
@@ -147,7 +152,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         help="Minimum severity for PR comments (default: medium)",
     )
 
-    dojo_parser = subparsers.add_parser("dojo", help="manage local DefectDojo stack")
+    dojo_parser = subparsers.add_parser("dojo", help=argparse.SUPPRESS)
     dojo_subparsers = dojo_parser.add_subparsers(dest="dojo_command")
 
     dojo_up = dojo_subparsers.add_parser("up", help="start the local DefectDojo stack")
@@ -378,7 +383,7 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     parsed = parser.parse_args(args)
     if parsed.command == "init":
-        return _command_init(parsed.config, parsed.force)
+        return _command_init(parsed.config, parsed.force, parsed.ci)
     if parsed.command == "scan":
         return _command_scan(
             parsed.config,
@@ -427,7 +432,7 @@ def _handle_no_args() -> int:
     return 0
 
 
-def _command_init(config_override: str | None, force: bool) -> int:
+def _command_init(config_override: str | None, force: bool, ci: bool = False) -> int:
     cfg_path = _resolve_config_path(config_override)
     if cfg_path.exists() and not force:
         print(f"Config already exists at {cfg_path}. Use --force to overwrite.")
@@ -441,6 +446,27 @@ def _command_init(config_override: str | None, force: bool) -> int:
     cfg_path.write_text(load_config_text(base_dir))
     print_dashboard()
     console.print(f"\n[success]Initialized config at[/success] [cyan]{cfg_path}[/cyan]\n")
+
+    # Auto-generate GitHub Actions workflow if --ci flag is set
+    if ci:
+        workflow_created = _generate_github_workflow()
+        if workflow_created:
+            console.print(
+                "[success]✓[/success] Created GitHub Actions workflow: "
+                "[cyan].github/workflows/kekkai-security.yml[/cyan]"
+            )
+            console.print(
+                "\n[info]Next steps:[/info]\n"
+                "  1. Commit the workflow file:\n"
+                "     [dim]git add .github/workflows/kekkai-security.yml[/dim]\n"
+                "  2. Push to GitHub\n"
+                "  3. Security scans will run automatically on pull requests\n"
+            )
+        else:
+            console.print(
+                "[warning]⚠[/warning]  Not a Git repository or .github/workflows/ cannot be created"
+            )
+
     return 0
 
 
@@ -604,6 +630,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 +878,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 +1182,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 +1525,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 +1544,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 +1612,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(
@@ -1661,6 +1778,91 @@ def _resolve_dojo_open_port(parsed: argparse.Namespace, compose_root: Path) -> i
     return dojo.DEFAULT_PORT
 
 
+def _generate_github_workflow() -> bool:
+    """Generate GitHub Actions workflow file for security scanning.
+
+    Returns:
+        True if workflow was created successfully, False otherwise.
+    """
+    # Check if we're in a git repository
+    cwd = Path.cwd()
+    git_dir = cwd / ".git"
+    if not git_dir.exists():
+        return False
+
+    # Create .github/workflows directory
+    workflows_dir = cwd / ".github" / "workflows"
+    try:
+        workflows_dir.mkdir(parents=True, exist_ok=True)
+    except (OSError, PermissionError):
+        return False
+
+    # Generate workflow file
+    workflow_path = workflows_dir / "kekkai-security.yml"
+    if workflow_path.exists():
+        # Don't overwrite existing workflow
+        return False
+
+    workflow_content = """name: Kekkai Security Scan
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches:
+      - main
+      - develop
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Kekkai
+        run: |
+          python -m pip install --upgrade pip
+          pip install kekkai-cli
+
+      - name: Run Security Scan
+        run: |
+          kekkai scan --ci --fail-on high
+        continue-on-error: true
+
+      - name: Post PR Comments (if PR)
+        if: github.event_name == 'pull_request'
+        run: |
+          kekkai scan --pr-comment --max-comments 50
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        continue-on-error: true
+
+      - name: Upload Results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: kekkai-scan-results
+          path: ~/.kekkai/runs/*/
+          retention-days: 30
+"""
+
+    try:
+        workflow_path.write_text(workflow_content, encoding="utf-8")
+        return True
+    except (OSError, PermissionError):
+        return False
+
+
 def _resolve_config_path(config_override: str | None) -> Path:
     if config_override:
         return Path(config_override).expanduser().resolve()

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 = "2.0.0"
 
 
 def print_dashboard() -> None:
@@ -88,9 +88,8 @@ def print_dashboard() -> None:
     menu_table.add_column("Description", style="desc", ratio=3)
 
     menu_table.add_row("kekkai scan", "Run security scan in current directory")
-    menu_table.add_row("kekkai threatflow", "Generate AI-powered threat model")
-    menu_table.add_row("kekkai dojo", "Manage local DefectDojo instance")
     menu_table.add_row("kekkai triage", "Interactive finding review (TUI)")
+    menu_table.add_row("kekkai threatflow", "Generate AI-powered threat model")
     menu_table.add_row("kekkai report", "Generate compliance reports")
     menu_table.add_row("kekkai config", "Manage settings and keys")
 

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