patchi 0.7.5__py3-none-any.whl

patchi/core/detector/dispatcher.py

@@ -0,0 +1,275 @@
+"""
+Dispatcher — routes detection events to the correct specialist agent.
+
+Consumes Event objects (raw or Sigma-enriched) and decides:
+1. Which agent to dispatch to (based on technique_id, suggested_agent, confidence)
+2. Whether the action should be synchronous (block) or async (investigate)
+3. Whether to rate-limit, deduplicate, or skip
+
+The dispatcher is the orchestration layer between detector output and agent execution.
+It does NOT execute agents itself — it produces DispatchInstruction objects that
+the caller (Coordinator or standalone runner) executes.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from patchi.core.agents.base import list_agents
+from patchi.core.detector.event import Event, EventSeverity, TechniqueID
+
+logger = logging.getLogger("patchi.detector.dispatcher")
+
+
+class DispatchUrgency(str):
+    SYNC_BLOCK = "sync_block"  # Block the request / stop processing immediately
+    SYNC_INVESTIGATE = "sync_inv"  # Investigate synchronously (hold response)
+    ASYNC_PRIORITY = "async_pri"  # High-priority async (process within seconds)
+    ASYNC_NORMAL = "async_normal"  # Normal async queue
+    ASYNC_DEFERRED = "async_defer"  # Low-priority, batch later
+    DISCARD = "discard"  # Drop (below threshold)
+
+
+@dataclass
+class DispatchInstruction:
+    """What the dispatcher wants done — one instruction per event."""
+
+    event_id: str
+    technique_id: str
+    agent_name: str
+    urgency: str
+    confidence: float
+    reason: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    created_at: float = field(default_factory=time.monotonic)
+
+
+class Dispatcher:
+    """
+    Routes events to agents based on technique_id, confidence, and agent availability.
+
+    Resolution order:
+      1. If event has `suggested_agent` AND confidence >= threshold → dispatch to that agent
+      2. Map technique_id → agent from TechniqueID.for_agent_type() or agent registration
+      3. If no mapping found and severity >= HIGH → dispatch to TriageAgent
+      4. Otherwise → DISCARD (below threshold)
+
+    Urgency is determined by severity:
+      - CRITICAL → SYNC_BLOCK
+      - HIGH     → SYNC_INVESTIGATE
+      - MEDIUM   → ASYNC_PRIORITY
+      - LOW/INFO → ASYNC_NORMAL
+    """
+
+    def __init__(
+        self,
+        min_confidence: float = 0.3,
+        agent_whitelist: set[str] | None = None,
+    ):
+        self._min_confidence = min_confidence
+        self._agent_whitelist = agent_whitelist
+        self._agent_registry: dict[str, str] = {}  # technique_id -> agent_name
+        self._dedup_window: dict[str, float] = {}  # event_id -> timestamp (for dedup)
+        self._dedup_ttl_s = 300.0  # 5 minute dedup window
+
+        # Build agent registry from TechniqueID mapping + known agents
+        self._build_registry()
+
+    def _build_registry(self) -> None:
+        """Build technique_id → agent_name mapping from all registered agents."""
+        for agent_cls in list_agents():
+            name = getattr(agent_cls, "name", "") or agent_cls.__name__
+            for agent_type in (
+                "injection",
+                "auth",
+                "authz",
+                "dependency",
+                "secret",
+                "network",
+                "runtime",
+                "crypto",
+                "compliance",
+                "triage",
+            ):
+                if agent_type.lower() in name.lower():
+                    tid = TechniqueID.for_agent_type(agent_type)
+                    self._agent_registry[tid.value] = name
+
+        # Hard-coded fallbacks for agents that match by technique rather than name
+        fallbacks = {
+            TechniqueID.INJECTION.value: "InjectionAgent",
+            TechniqueID.BRUTE_FORCE.value: "AuthenticationAuditAgent",
+            TechniqueID.SECRETS_FROM_STORE.value: "SecretScanner",
+            TechniqueID.RESOURCE_DEVELOPMENT.value: "DependencyVulnerabilityAgent",
+            TechniqueID.TRAFFIC_SIGNALING.value: "NetworkAgent",
+            TechniqueID.EXECUTION.value: "RuntimeValidatorAgent",
+            TechniqueID.DEFENSE_EVASION.value: "CryptoAgent",
+            TechniqueID.UNKNOWN.value: "TriageAgent",
+        }
+        self._agent_registry.update(fallbacks)
+
+    # ── Core dispatch logic ──────────────────────────────────────────────────
+
+    def dispatch(self, event: Event, sigma_matches: list | None = None) -> DispatchInstruction:
+        """
+        Create a dispatch instruction for a single event.
+
+        Uses both the raw event and any Sigma rule matches to determine routing.
+        """
+        event_id = event.event_id
+
+        # Dedup check
+        if event_id in self._dedup_window:
+            elapsed = time.monotonic() - self._dedup_window[event_id]
+            if elapsed < self._dedup_ttl_s:
+                return DispatchInstruction(
+                    event_id=event_id,
+                    technique_id="",
+                    agent_name="",
+                    urgency=DispatchUrgency.DISCARD,
+                    confidence=0.0,
+                    reason="Deduplicated (same event_id within window)",
+                )
+
+        self._dedup_window[event_id] = time.monotonic()
+
+        # Step 1: Extract the best technique_id and agent hint
+        technique_id, confidence, suggested_agent = self._resolve_routing(event, sigma_matches)
+
+        if technique_id == TechniqueID.NONE.value:
+            return DispatchInstruction(
+                event_id=event_id,
+                technique_id=technique_id,
+                agent_name="",
+                urgency=DispatchUrgency.DISCARD,
+                confidence=0.0,
+                reason="No technique mapping (info/heartbeat)",
+            )
+
+        # Step 2: Find the agent to dispatch to
+        agent_name = self._resolve_agent(technique_id, suggested_agent)
+
+        if not agent_name:
+            if event.severity.sort_key() <= EventSeverity.LOW.sort_key():
+                return DispatchInstruction(
+                    event_id=event_id,
+                    technique_id=technique_id,
+                    agent_name="",
+                    urgency=DispatchUrgency.DISCARD,
+                    confidence=confidence,
+                    reason=f"No agent found for technique {technique_id} and severity too low",
+                )
+            agent_name = "TriageAgent"
+
+        # Step 3: Apply whitelist filter
+        if self._agent_whitelist and agent_name not in self._agent_whitelist:
+            return DispatchInstruction(
+                event_id=event_id,
+                technique_id=technique_id,
+                agent_name="",
+                urgency=DispatchUrgency.DISCARD,
+                confidence=confidence,
+                reason=f"Agent {agent_name} not in whitelist",
+            )
+
+        # Step 4: Determine urgency
+        urgency = self._resolve_urgency(event.severity, confidence)
+
+        # Build reason string
+        reason_parts = []
+        if suggested_agent:
+            reason_parts.append(f"suggested={suggested_agent}")
+        reason_parts.append(f"confidence={confidence:.2f}")
+        reason_parts.append(f"severity={event.severity.value}")
+        if sigma_matches:
+            reason_parts.append(f"sigma_rules={len(sigma_matches)}")
+
+        return DispatchInstruction(
+            event_id=event_id,
+            technique_id=technique_id,
+            agent_name=agent_name,
+            urgency=urgency,
+            confidence=confidence,
+            reason="; ".join(reason_parts),
+            payload=event.payload,
+        )
+
+    def dispatch_batch(self, events: list[Event]) -> list[DispatchInstruction]:
+        """Dispatch a batch of events. Deduplicates by event_id."""
+        seen: set[str] = set()
+        results: list[DispatchInstruction] = []
+        for event in events:
+            if event.event_id in seen:
+                continue
+            seen.add(event.event_id)
+            instruction = self.dispatch(event)
+            if instruction.urgency != DispatchUrgency.DISCARD:
+                results.append(instruction)
+        return results
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    def _resolve_routing(
+        self,
+        event: Event,
+        sigma_matches: list | None,
+    ) -> tuple[str, float, str]:
+        """Determine the best technique_id, confidence, and suggested_agent."""
+        tid = (
+            event.technique_id.value
+            if isinstance(event.technique_id, TechniqueID)
+            else event.technique_id
+        )
+        confidence = event.confidence
+        suggested_agent = event.suggested_agent or ""
+
+        # If Sigma matched, boost confidence and use Sigma's technique_id
+        if sigma_matches:
+            best = sigma_matches[0]
+            tid = (
+                best.technique_id.value
+                if isinstance(best.technique_id, TechniqueID)
+                else str(best.technique_id)
+            )
+            confidence = max(confidence, best.confidence)
+            if best.target_agent:
+                suggested_agent = best.target_agent
+
+        return tid, confidence, suggested_agent
+
+    def _resolve_agent(self, technique_id: str, suggested_agent: str | None) -> str:
+        """Find the agent to handle this technique, with fallback logic."""
+        if suggested_agent:
+            return suggested_agent
+        return self._agent_registry.get(technique_id, "")
+
+    def _resolve_urgency(self, severity: EventSeverity, confidence: float) -> str:
+        """Map severity + confidence to urgency level."""
+        if severity == EventSeverity.CRITICAL:
+            if confidence >= 0.7:
+                return DispatchUrgency.SYNC_BLOCK
+            return DispatchUrgency.SYNC_INVESTIGATE
+        if severity == EventSeverity.HIGH:
+            if confidence >= 0.5:
+                return DispatchUrgency.SYNC_INVESTIGATE
+            return DispatchUrgency.ASYNC_PRIORITY
+        if severity == EventSeverity.MEDIUM:
+            return (
+                DispatchUrgency.ASYNC_PRIORITY
+                if confidence >= 0.5
+                else DispatchUrgency.ASYNC_NORMAL
+            )
+        return DispatchUrgency.ASYNC_NORMAL
+
+    def stats(self) -> dict:
+        return {
+            "agent_registry_size": len(self._agent_registry),
+            "dedup_window_size": len(self._dedup_window),
+            "known_techniques": list(self._agent_registry.keys()),
+        }
+
+    def clear_dedup(self) -> None:
+        self._dedup_window.clear()

patchi/core/detector/event.py

@@ -0,0 +1,254 @@
+"""
+Event schema — the universal envelope for everything Patchi detects, routes, or acts on.
+
+Every signal source (HTTP traffic, logs, syscalls, git diffs, agent findings) normalizes
+into this schema before reaching the dispatcher. Every action, override, and audit log
+entry also uses it. This is the single contract between all pipeline stages.
+
+MITRE ATT&CK v14 technique IDs are used as the primary classification axis because:
+- They're stable, versioned, and community-maintained (not invented here)
+- They map 1:1 to the specialist agent roster
+- Atomic Red Team tests emit known technique_ids, making end-to-end validation tractable
+- OWASP/CWE mappings are secondary labels (we maintain the bidirectional map)
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+# ── Event severity (extends the Finding severity model) ──────────────────────
+
+
+class EventSeverity(StrEnum):
+    DEBUG = "debug"  # No alerting, diagnostics only
+    INFO = "info"  # Informational, never alerts
+    LOW = "low"  # Digest-only, no immediate action
+    MEDIUM = "medium"  # Worthy of investigation
+    HIGH = "high"  # Requires prompt attention
+    CRITICAL = "critical"  # Immediate action required
+
+    def sort_key(self) -> int:
+        return {
+            "debug": 5,
+            "info": 4,
+            "low": 3,
+            "medium": 2,
+            "high": 1,
+            "critical": 0,
+        }[self.value]
+
+    def to_enum(self) -> str:
+        return self.value
+
+
+# ── Event source types ──────────────────────────────────────────────────────
+
+
+class EventSource(StrEnum):
+    """Where the event originated. Each maps to a signal source type."""
+
+    AGENT = "agent"  # A Patchi agent produced a finding
+    HTTP_TRAFFIC = "http_traffic"  # Ingress/egress HTTP request
+    LOG_LINE = "log_line"  # Application or access log
+    SYSCALL = "syscall"  # Host/container syscall (Falco)
+    NETWORK_FLOW = "network_flow"  # Network protocol event (Suricata/Zeek)
+    DEPENDENCY_SCAN = "dependency"  # Dependency manifest / CVE scan
+    SECRET_SCAN = "secret"  # Secret scanning hit
+    GIT_EVENT = "git_event"  # Commit, PR, diff, push
+    CONFIG_CHANGE = "config"  # Config file or env var change
+    HEARTBEAT = "heartbeat"  # System health / uptime check
+    USER_ACTION = "user_action"  # Explicit user command or override
+    ANOMALY = "anomaly"  # Detected by the anomaly layer
+
+
+# ── MITRE ATT&CK technique / tactic IDs ──────────────────────────────────────
+
+
+# Selected ATT&CK technique IDs relevant to Patchi's agent roster.
+# v14+ stable IDs; see https://attack.mitre.org/techniques/enterprise/
+
+
+class TechniqueID(StrEnum):
+    INITIAL_ACCESS = "T1190"  # Exploit Public-Facing Application
+    EXECUTION = "T1203"  # Exploitation for Client Execution
+    PERSISTENCE = "T1505"  # Server Software Component
+    DEFENSE_EVASION = "T1562"  # Impair Defenses
+    CREDENTIAL_ACCESS = "T1552"  # Unsecured Credentials
+    DISCOVERY = "T1046"  # Network Service Discovery
+    COLLECTION = "T1567"  # Exfiltration Over Web Service
+    COMMAND_AND_CONTROL = "T1071"  # Application Layer Protocol
+    EXFILTRATION = "T1048"  # Exfiltration Over Alternative Protocol
+    IMPACT = "T1499"  # Endpoint Denial of Service
+    RESOURCE_DEVELOPMENT = "T1583"  # Acquire Infrastructure
+    INJECTION = "T1055"  # Process Injection
+    VALID_ACCOUNTS = "T1078"  # Valid Accounts
+    BRUTE_FORCE = "T1110"  # Brute Force
+    INPUT_CAPTURE = "T1056"  # Input Capture
+    MODIFY_AUTH_PROCESS = "T1556"  # Modify Authentication Process
+    STEAL_APPLICATION_ACCESS = "T1528"  # Steal Application Access Token
+    SECRETS_FROM_STORE = "T1552.001"  # Credentials in Files / Keychains
+    EXPLOIT_PUBLIC_APP = "T1190"  # Exploit Public-Facing Application
+    MAN_IN_MIDDLE = "T1557"  # Adversary-in-the-Middle
+    TRAFFIC_SIGNALING = "T1573"  # Encrypted Channel
+    PROXY = "T1090"  # Proxy
+    UNKNOWN = "T9999"  # Unclassified / needs triage
+    NONE = "T0000"  # No technique mapping (info/heartbeat)
+
+    @classmethod
+    def for_agent_type(cls, agent_type: str) -> TechniqueID:
+        mapping = {
+            "injection": cls.INJECTION,
+            "auth": cls.BRUTE_FORCE,
+            "authz": cls.VALID_ACCOUNTS,
+            "dependency": cls.RESOURCE_DEVELOPMENT,
+            "secret": cls.SECRETS_FROM_STORE,
+            "network": cls.TRAFFIC_SIGNALING,
+            "runtime": cls.EXECUTION,
+            "triage": cls.UNKNOWN,
+            "crypto": cls.DEFENSE_EVASION,
+            "compliance": cls.IMPACT,
+        }
+        return mapping.get(agent_type, cls.UNKNOWN)
+
+    @classmethod
+    def display_name(cls, tid: str) -> str:
+        names = {
+            "T1190": "Exploit Public-Facing Application",
+            "T1203": "Exploitation for Client Execution",
+            "T1505": "Persistent Server Software Component",
+            "T1562": "Impair Defenses",
+            "T1552": "Unsecured Credentials",
+            "T1046": "Network Service Discovery",
+            "T1567": "Exfiltration Over Web Service",
+            "T1071": "Application Layer Protocol C2",
+            "T1048": "Exfiltration Over Alternative Protocol",
+            "T1499": "Endpoint Denial of Service",
+            "T1583": "Acquire Infrastructure",
+            "T1055": "Process Injection",
+            "T1078": "Valid Accounts",
+            "T1110": "Brute Force",
+            "T1056": "Input Capture",
+            "T1556": "Modify Authentication Process",
+            "T1528": "Steal Application Access Token",
+            "T1552.001": "Credentials from Files",
+            "T1557": "Adversary-in-the-Middle",
+            "T1573": "Encrypted Channel",
+            "T1090": "Proxy",
+            "T9999": "Unclassified",
+            "T0000": "None",
+        }
+        return names.get(tid, "Unknown Technique")
+
+
+# ── The event envelope ───────────────────────────────────────────────────────
+
+
+@dataclass
+class Event:
+    """
+    Universal event envelope.
+
+    Every signal in the system normalizes to this shape before entering the pipeline.
+    Immutable after creation (consumers should not mutate).
+
+    The `id` is a deterministic hash of the event's key fields so the same external
+    signal always produces the same event ID (useful for deduplication). Override with
+    `override_id` for synthetic events.
+    """
+
+    source: EventSource
+    technique_id: TechniqueID | str
+
+    # Core payload
+    summary: str  # One-line human-readable description
+    severity: EventSeverity = EventSeverity.INFO
+    payload: dict[str, Any] = field(default_factory=dict)  # Signal-specific data
+
+    # Routing hints — populated by the detector, consumed by the dispatcher
+    suggested_agent: str | None = None  # e.g. "InjectionAgent"
+    confidence: float = 0.5  # 0.0–1.0, how sure the detector is
+
+    # Enrichment
+    agent_name: str | None = None  # Which agent produced this (if from an agent)
+    finding_id: str | None = None  # Link back to a specific Finding if applicable
+    cwe_ids: list[str] = field(default_factory=list)
+    owasp_category: str = ""
+
+    # Metadata
+    timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    event_id: str = field(default_factory=lambda: uuid.uuid4().hex[:16])
+    source_details: dict[str, str] = field(default_factory=dict)  # host, container, file, repo
+
+    # Audit chain
+    parent_event_id: str | None = None  # Which event triggered this one
+
+    def to_dict(self) -> dict:
+        return {
+            "event_id": self.event_id,
+            "source": self.source.value,
+            "technique_id": self.technique_id.value
+            if isinstance(self.technique_id, TechniqueID)
+            else self.technique_id,
+            "summary": self.summary,
+            "severity": self.severity.value,
+            "payload": self.payload,
+            "suggested_agent": self.suggested_agent,
+            "confidence": self.confidence,
+            "agent_name": self.agent_name,
+            "finding_id": self.finding_id,
+            "cwe_ids": self.cwe_ids,
+            "owasp_category": self.owasp_category,
+            "timestamp": self.timestamp,
+            "source_details": self.source_details,
+            "parent_event_id": self.parent_event_id,
+        }
+
+    @property
+    def technique_display(self) -> str:
+        tid = (
+            self.technique_id.value
+            if isinstance(self.technique_id, TechniqueID)
+            else self.technique_id
+        )
+        return f"{tid} — {TechniqueID.display_name(tid)}"
+
+
+# ── EventBatch (for bulk processing) ─────────────────────────────────────────
+
+
+@dataclass
+class EventBatch:
+    """A time-windowed batch of events for bulk dispatch/audit."""
+
+    events: list[Event] = field(default_factory=list)
+    batch_id: str = field(default_factory=lambda: uuid.uuid4().hex[:16])
+    created: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+    def by_severity(self) -> dict[str, list[Event]]:
+        groups: dict[str, list[Event]] = {}
+        for ev in self.events:
+            groups.setdefault(ev.severity.value, []).append(ev)
+        return groups
+
+    def by_technique(self) -> dict[str, list[Event]]:
+        groups: dict[str, list[Event]] = {}
+        for ev in self.events:
+            tid = (
+                ev.technique_id.value
+                if isinstance(ev.technique_id, TechniqueID)
+                else ev.technique_id
+            )
+            groups.setdefault(tid, []).append(ev)
+        return groups
+
+    def to_dict(self) -> dict:
+        return {
+            "batch_id": self.batch_id,
+            "created": self.created,
+            "count": len(self.events),
+            "events": [e.to_dict() for e in self.events],
+        }