kekkai-cli 1.0.0__py3-none-any.whl

kekkai/triage/app.py

@@ -0,0 +1,168 @@
+"""Main Textual application for triage TUI.
+
+Provides the entry point for interactive finding triage with
+keyboard-driven navigation and ignore file generation.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from textual.app import App
+
+from .audit import TriageAuditLog
+from .ignore import IgnoreFile
+from .models import FindingEntry, TriageDecision, TriageState, load_findings_from_json
+from .screens import FindingListScreen
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = [
+    "TriageApp",
+    "run_triage",
+]
+
+
+class TriageApp(App[None]):
+    """Interactive triage application for security findings.
+
+    Allows reviewing findings, marking false positives, and
+    generating .kekkaiignore files.
+
+    Attributes:
+        findings: List of findings to triage.
+        ignore_file: IgnoreFile manager for output.
+        audit_log: Audit log for recording decisions.
+    """
+
+    TITLE = "Kekkai Triage"
+    CSS = """
+    Screen {
+        background: $background;
+    }
+    """
+
+    def __init__(
+        self,
+        findings: Sequence[FindingEntry] | None = None,
+        input_path: Path | None = None,
+        output_path: Path | None = None,
+        audit_path: Path | None = None,
+    ) -> None:
+        """Initialize triage application.
+
+        Args:
+            findings: Pre-loaded findings to triage.
+            input_path: Path to findings JSON file.
+            output_path: Path for .kekkaiignore output.
+            audit_path: Path for audit log.
+        """
+        super().__init__()
+        self._input_path = input_path
+        self._findings_list: list[FindingEntry] = list(findings) if findings else []
+        self.ignore_file = IgnoreFile(output_path)
+        self.audit_log = TriageAuditLog(audit_path)
+        self._decisions: dict[str, TriageDecision] = {}
+
+    @property
+    def findings(self) -> list[FindingEntry]:
+        """Get findings list, loading from file if needed."""
+        if not self._findings_list and self._input_path:
+            self._load_findings()
+        return self._findings_list
+
+    def _load_findings(self) -> None:
+        """Load findings from input file."""
+        if not self._input_path or not self._input_path.exists():
+            return
+
+        try:
+            content = self._input_path.read_text(encoding="utf-8")
+            data = json.loads(content)
+
+            if isinstance(data, list):
+                self._findings_list = load_findings_from_json(data)
+            elif isinstance(data, dict) and "findings" in data:
+                self._findings_list = load_findings_from_json(data["findings"])
+        except (json.JSONDecodeError, KeyError, TypeError):
+            self._findings_list = []
+
+    def on_mount(self) -> None:
+        """Handle app mount."""
+        self.push_screen(
+            FindingListScreen(
+                findings=self.findings,
+                on_state_change=self._handle_state_change,
+                on_save=self._handle_save,
+            )
+        )
+
+    def _handle_state_change(self, index: int, state: TriageState) -> None:
+        """Handle finding state change.
+
+        Args:
+            index: Finding index.
+            state: New triage state.
+        """
+        if index >= len(self.findings):
+            return
+
+        finding = self.findings[index]
+        ignore_pattern = None
+
+        if state == TriageState.FALSE_POSITIVE:
+            ignore_pattern = finding.generate_ignore_pattern()
+
+        decision = TriageDecision(
+            finding_id=finding.id,
+            state=state,
+            reason=finding.notes,
+            ignore_pattern=ignore_pattern,
+        )
+
+        self._decisions[finding.id] = decision
+        self.audit_log.log_decision(decision)
+
+    def _handle_save(self) -> None:
+        """Handle save action."""
+        self.ignore_file.load()
+
+        for finding in self.findings:
+            if finding.state == TriageState.FALSE_POSITIVE:
+                pattern = finding.generate_ignore_pattern()
+                if not self.ignore_file.has_pattern(pattern):
+                    self.ignore_file.add_entry(
+                        pattern=pattern,
+                        comment=finding.notes[:100] if finding.notes else finding.title[:100],
+                        finding_id=finding.id,
+                    )
+
+        self.ignore_file.save()
+        self.audit_log.log_action("save_ignore_file", finding_id="*")
+
+
+def run_triage(
+    input_path: Path | None = None,
+    output_path: Path | None = None,
+    findings: Sequence[FindingEntry] | None = None,
+) -> int:
+    """Run the triage TUI.
+
+    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).
+    """
+    app = TriageApp(
+        findings=findings,
+        input_path=input_path,
+        output_path=output_path,
+    )
+    app.run()
+    return 0

kekkai/triage/audit.py

@@ -0,0 +1,203 @@
+"""Audit logging for triage decisions.
+
+Provides append-only audit trail for all triage decisions to
+support non-repudiation and compliance requirements.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from .models import TriageDecision
+
+__all__ = [
+    "TriageAuditLog",
+    "AuditEntry",
+]
+
+
+class AuditEntry:
+    """A single audit log entry.
+
+    Attributes:
+        timestamp: When the action occurred (ISO format).
+        action: The action performed (e.g., "mark_false_positive").
+        finding_id: ID of the affected finding.
+        user: User who performed the action.
+        details: Additional action details.
+    """
+
+    def __init__(
+        self,
+        action: str,
+        finding_id: str,
+        user: str = "",
+        details: dict[str, str] | None = None,
+        timestamp: str | None = None,
+    ) -> None:
+        self.timestamp = timestamp or datetime.now(UTC).isoformat()
+        self.action = action
+        self.finding_id = finding_id
+        self.user = user or os.environ.get("USER", "unknown")
+        self.details = details or {}
+
+    def to_dict(self) -> dict[str, str | dict[str, str]]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "timestamp": self.timestamp,
+            "action": self.action,
+            "finding_id": self.finding_id,
+            "user": self.user,
+            "details": self.details,
+        }
+
+    def to_json(self) -> str:
+        """Convert to JSON string."""
+        return json.dumps(self.to_dict(), separators=(",", ":"))
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str | dict[str, str]]) -> AuditEntry:
+        """Create from dictionary."""
+        details_raw = data.get("details", {})
+        details = dict(details_raw) if isinstance(details_raw, dict) else {}
+        return cls(
+            timestamp=str(data.get("timestamp", "")),
+            action=str(data.get("action", "")),
+            finding_id=str(data.get("finding_id", "")),
+            user=str(data.get("user", "")),
+            details={str(k): str(v) for k, v in details.items()},
+        )
+
+
+class TriageAuditLog:
+    """Append-only audit log for triage decisions.
+
+    Stores entries in JSON Lines format (.jsonl) for easy parsing
+    and tamper evidence.
+
+    Attributes:
+        path: Path to the audit log file.
+    """
+
+    DEFAULT_PATH = Path.home() / ".kekkai" / "triage-audit.jsonl"
+
+    def __init__(self, path: Path | None = None) -> None:
+        """Initialize audit log.
+
+        Args:
+            path: Path to audit log file. Defaults to ~/.kekkai/triage-audit.jsonl.
+        """
+        self.path = path or self.DEFAULT_PATH
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def log(self, entry: AuditEntry) -> None:
+        """Append an entry to the audit log.
+
+        Args:
+            entry: The audit entry to log.
+        """
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(entry.to_json() + "\n")
+
+    def log_decision(self, decision: TriageDecision) -> None:
+        """Log a triage decision.
+
+        Args:
+            decision: The triage decision to log.
+        """
+        entry = AuditEntry(
+            action=f"triage_{decision.state.value}",
+            finding_id=decision.finding_id,
+            user=decision.user,
+            details={
+                "reason": decision.reason,
+                "ignore_pattern": decision.ignore_pattern or "",
+            },
+        )
+        self.log(entry)
+
+    def log_action(
+        self,
+        action: str,
+        finding_id: str,
+        details: dict[str, str] | None = None,
+    ) -> None:
+        """Log a generic action.
+
+        Args:
+            action: Action name.
+            finding_id: Affected finding ID.
+            details: Additional details.
+        """
+        entry = AuditEntry(
+            action=action,
+            finding_id=finding_id,
+            details=details,
+        )
+        self.log(entry)
+
+    def read_all(self) -> list[AuditEntry]:
+        """Read all entries from the log.
+
+        Returns:
+            List of all audit entries.
+        """
+        entries: list[AuditEntry] = []
+
+        if not self.path.exists():
+            return entries
+
+        with self.path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    data = json.loads(line)
+                    entries.append(AuditEntry.from_dict(data))
+                except json.JSONDecodeError:
+                    continue
+
+        return entries
+
+    def read_for_finding(self, finding_id: str) -> list[AuditEntry]:
+        """Read entries for a specific finding.
+
+        Args:
+            finding_id: The finding ID to filter by.
+
+        Returns:
+            List of matching audit entries.
+        """
+        return [e for e in self.read_all() if e.finding_id == finding_id]
+
+    def get_recent(self, count: int = 100) -> list[AuditEntry]:
+        """Get most recent entries.
+
+        Args:
+            count: Maximum number of entries to return.
+
+        Returns:
+            List of recent audit entries (newest last).
+        """
+        all_entries = self.read_all()
+        return all_entries[-count:] if len(all_entries) > count else all_entries
+
+
+def log_decisions(decisions: Sequence[TriageDecision], log_path: Path | None = None) -> None:
+    """Log multiple triage decisions.
+
+    Args:
+        decisions: Decisions to log.
+        log_path: Optional custom log path.
+    """
+    audit_log = TriageAuditLog(log_path)
+    for decision in decisions:
+        audit_log.log_decision(decision)

kekkai/triage/ignore.py

@@ -0,0 +1,269 @@
+"""Ignore file management for triage decisions.
+
+Provides validation and I/O for .kekkaiignore files with strict
+security controls against injection attacks.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = [
+    "IgnorePatternValidator",
+    "IgnoreFile",
+    "ValidationError",
+]
+
+VALID_PATTERN_CHARS = re.compile(r"^[a-zA-Z0-9_./*\-:]+$")
+PATH_TRAVERSAL_PATTERN = re.compile(r"(^|/)\.\.(/|$)")
+DANGEROUS_PATTERNS = [
+    "..",
+    "~",
+    "$",
+    "`",
+    ";",
+    "&",
+    "|",
+    ">",
+    "<",
+    "\\",
+]
+
+
+class ValidationError(Exception):
+    """Raised when pattern validation fails."""
+
+
+@dataclass
+class IgnorePatternValidator:
+    """Validates ignore patterns against security constraints.
+
+    Enforces:
+    - No path traversal (../)
+    - Allowlisted characters only
+    - Maximum pattern length
+    - No shell metacharacters
+    """
+
+    max_pattern_length: int = 500
+
+    def is_valid(self, pattern: str) -> bool:
+        """Check if a pattern is valid.
+
+        Args:
+            pattern: The ignore pattern to validate.
+
+        Returns:
+            True if valid, False otherwise.
+        """
+        if not pattern or not pattern.strip():
+            return False
+
+        if len(pattern) > self.max_pattern_length:
+            return False
+
+        if PATH_TRAVERSAL_PATTERN.search(pattern):
+            return False
+
+        for dangerous in DANGEROUS_PATTERNS:
+            if dangerous in pattern:
+                return False
+
+        return bool(VALID_PATTERN_CHARS.match(pattern))
+
+    def validate(self, pattern: str) -> str:
+        """Validate and return pattern or raise error.
+
+        Args:
+            pattern: The ignore pattern to validate.
+
+        Returns:
+            The validated pattern (stripped).
+
+        Raises:
+            ValidationError: If pattern is invalid.
+        """
+        pattern = pattern.strip()
+
+        if not pattern:
+            raise ValidationError("Empty pattern")
+
+        if len(pattern) > self.max_pattern_length:
+            raise ValidationError(f"Pattern exceeds max length ({self.max_pattern_length})")
+
+        if PATH_TRAVERSAL_PATTERN.search(pattern):
+            raise ValidationError("Path traversal not allowed")
+
+        for dangerous in DANGEROUS_PATTERNS:
+            if dangerous in pattern:
+                raise ValidationError(f"Dangerous character not allowed: {dangerous!r}")
+
+        if not VALID_PATTERN_CHARS.match(pattern):
+            raise ValidationError("Pattern contains invalid characters")
+
+        return pattern
+
+
+@dataclass
+class IgnoreEntry:
+    """An entry in the ignore file.
+
+    Attributes:
+        pattern: The ignore pattern.
+        comment: Optional comment/reason.
+        finding_id: Associated finding ID if applicable.
+    """
+
+    pattern: str
+    comment: str = ""
+    finding_id: str = ""
+
+
+class IgnoreFile:
+    """Manages .kekkaiignore file read/write operations.
+
+    Format:
+        # Comment line
+        scanner:rule_id:file_path  # inline comment
+
+    Attributes:
+        path: Path to the ignore file.
+        entries: List of ignore entries.
+    """
+
+    def __init__(self, path: Path | None = None) -> None:
+        """Initialize ignore file manager.
+
+        Args:
+            path: Path to ignore file. Defaults to .kekkaiignore in cwd.
+        """
+        self.path = path or Path(".kekkaiignore")
+        self.entries: list[IgnoreEntry] = []
+        self._validator = IgnorePatternValidator()
+
+    def load(self) -> list[IgnoreEntry]:
+        """Load entries from file.
+
+        Returns:
+            List of ignore entries.
+        """
+        self.entries = []
+
+        if not self.path.exists():
+            return self.entries
+
+        content = self.path.read_text(encoding="utf-8")
+        for line in content.splitlines():
+            line = line.strip()
+
+            if not line or line.startswith("#"):
+                continue
+
+            comment = ""
+            if " # " in line:
+                line, comment = line.split(" # ", 1)
+                line = line.strip()
+                comment = comment.strip()
+
+            if self._validator.is_valid(line):
+                self.entries.append(IgnoreEntry(pattern=line, comment=comment))
+
+        return self.entries
+
+    def save(self, entries: Sequence[IgnoreEntry] | None = None) -> None:
+        """Save entries to file.
+
+        Args:
+            entries: Entries to save. Uses self.entries if None.
+        """
+        if entries is not None:
+            self.entries = list(entries)
+
+        lines = [
+            "# Kekkai Ignore File",
+            "# Generated by kekkai triage",
+            "# Format: scanner:rule_id:file_path",
+            "",
+        ]
+
+        for entry in self.entries:
+            pattern = self._validator.validate(entry.pattern)
+            if entry.comment:
+                safe_comment = entry.comment.replace("\n", " ").replace("#", "")[:100]
+                lines.append(f"{pattern}  # {safe_comment}")
+            else:
+                lines.append(pattern)
+
+        self.path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    def add_entry(self, pattern: str, comment: str = "", finding_id: str = "") -> None:
+        """Add a validated entry.
+
+        Args:
+            pattern: Ignore pattern to add.
+            comment: Optional comment.
+            finding_id: Associated finding ID.
+
+        Raises:
+            ValidationError: If pattern is invalid.
+        """
+        validated = self._validator.validate(pattern)
+        self.entries.append(IgnoreEntry(pattern=validated, comment=comment, finding_id=finding_id))
+
+    def has_pattern(self, pattern: str) -> bool:
+        """Check if pattern already exists.
+
+        Args:
+            pattern: Pattern to check.
+
+        Returns:
+            True if pattern exists.
+        """
+        return any(e.pattern == pattern for e in self.entries)
+
+    def matches(self, scanner: str, rule_id: str, file_path: str) -> bool:
+        """Check if a finding matches any ignore pattern.
+
+        Args:
+            scanner: Scanner name.
+            rule_id: Rule identifier.
+            file_path: File path.
+
+        Returns:
+            True if finding should be ignored.
+        """
+        full_pattern = f"{scanner}:{rule_id}:{file_path}"
+        scanner_rule = f"{scanner}:{rule_id}"
+        scanner_only = scanner
+
+        for entry in self.entries:
+            pattern = entry.pattern
+            if pattern == full_pattern:
+                return True
+            if pattern == scanner_rule:
+                return True
+            if pattern == scanner_only:
+                return True
+            if "*" in pattern and self._glob_match(pattern, full_pattern):
+                return True
+
+        return False
+
+    def _glob_match(self, pattern: str, target: str) -> bool:
+        """Simple glob matching with * wildcard.
+
+        Args:
+            pattern: Pattern with optional * wildcards.
+            target: String to match against.
+
+        Returns:
+            True if pattern matches target.
+        """
+        regex_pattern = re.escape(pattern).replace(r"\*", ".*")
+        return bool(re.fullmatch(regex_pattern, target))