iflow-mcp-m507_ai-soc-agent 1.0.0__py3-none-any.whl

src/integrations/case_management/thehive/thehive_client.py

@@ -0,0 +1,193 @@
+"""
+TheHive implementation of the generic ``CaseManagementClient`` interface.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ....api.case_management import (
+    Case,
+    CaseAssignment,
+    CaseComment,
+    CaseManagementClient,
+    CaseObservable,
+    CaseSearchQuery,
+    CaseStatus,
+    CaseSummary,
+)
+from ....core.config import SamiConfig
+from ....core.errors import IntegrationError
+from ....core.logging import get_logger
+from .thehive_http import TheHiveHttpClient
+from .thehive_mapper import (
+    case_to_thehive_payload,
+    comment_to_thehive_payload,
+    observable_to_thehive_payload,
+    status_to_thehive_status,
+    thehive_case_to_generic,
+    thehive_case_to_summary,
+    thehive_comment_to_generic,
+)
+
+
+logger = get_logger("sami.integrations.thehive.client")
+
+
+class TheHiveCaseManagementClient(CaseManagementClient):
+    """
+    Case management client backed by TheHive.
+    """
+
+    def __init__(self, http_client: TheHiveHttpClient) -> None:
+        self._http = http_client
+
+    @classmethod
+    def from_config(cls, config: SamiConfig) -> "TheHiveCaseManagementClient":
+        """
+        Factory to construct a client from ``SamiConfig``.
+        """
+
+        if not config.thehive:
+            raise IntegrationError("TheHive configuration is not set in SamiConfig")
+
+        http_client = TheHiveHttpClient(
+            base_url=config.thehive.base_url,
+            api_key=config.thehive.api_key,
+            timeout_seconds=config.thehive.timeout_seconds,
+        )
+        return cls(http_client=http_client)
+
+    # Core CRUD operations
+
+    def create_case(self, case: Case) -> Case:
+        payload = case_to_thehive_payload(case)
+        raw = self._http.post("/api/case", json=payload)
+        return thehive_case_to_generic(raw)
+
+    def get_case(self, case_id: str) -> Case:
+        raw = self._http.get(f"/api/case/{case_id}")
+        return thehive_case_to_generic(raw)
+
+    def list_cases(
+        self,
+        status: Optional[CaseStatus] = None,
+        limit: int = 50,
+    ) -> List[CaseSummary]:
+        params = {"range": f"[0,{max(limit - 1, 0)}]"}
+        if status is not None:
+            params["status"] = status_to_thehive_status(status).value
+        raw_list = self._http.get("/api/case", params=params)
+        return [thehive_case_to_summary(raw) for raw in raw_list]
+
+    def search_cases(self, query: CaseSearchQuery) -> List[CaseSummary]:
+        # Very simple text/field search mapping; real implementations may need
+        # to use TheHive's /api/case/_search endpoint with a JSON query body.
+        params: dict = {}
+        if query.text:
+            params["title"] = query.text
+        if query.status:
+            params["status"] = status_to_thehive_status(query.status).value
+
+        raw_list = self._http.get("/api/case", params=params)
+        summaries = [thehive_case_to_summary(raw) for raw in raw_list]
+        return summaries[: query.limit]
+
+    def update_case(self, case_id: str, updates: dict) -> Case:
+        raw = self._http.patch(f"/api/case/{case_id}", json=updates)
+        return thehive_case_to_generic(raw)
+
+    def delete_case(self, case_id: str) -> None:
+        self._http.delete(f"/api/case/{case_id}")
+
+    # Comments and observables
+
+    def add_case_comment(
+        self,
+        case_id: str,
+        content: str,
+        author: Optional[str] = None,
+    ) -> CaseComment:
+        comment = CaseComment(
+            id=None,
+            case_id=case_id,
+            author=author,
+            content=content,
+        )
+        payload = comment_to_thehive_payload(comment)
+        raw = self._http.post(f"/api/case/{case_id}/comment", json=payload)
+        return thehive_comment_to_generic(raw, case_id=case_id)
+
+    def add_case_observable(
+        self,
+        case_id: str,
+        observable: CaseObservable,
+    ) -> CaseObservable:
+        payload = observable_to_thehive_payload(observable)
+        raw = self._http.post(f"/api/case/{case_id}/artifact", json=payload)
+        from .thehive_models import parse_thehive_observable
+
+        return CaseObservable(
+            type=parse_thehive_observable(raw).data_type,
+            value=parse_thehive_observable(raw).data,
+            tags=parse_thehive_observable(raw).tags or [],
+            description=None,
+        )
+
+    # Status and assignment
+
+    def update_case_status(
+        self,
+        case_id: str,
+        status: CaseStatus,
+    ) -> Case:
+        payload = {"status": status_to_thehive_status(status).value}
+        raw = self._http.patch(f"/api/case/{case_id}", json=payload)
+        return thehive_case_to_generic(raw)
+
+    def assign_case(
+        self,
+        case_id: str,
+        assignee: str,
+    ) -> CaseAssignment:
+        payload = {"owner": assignee}
+        raw = self._http.patch(f"/api/case/{case_id}", json=payload)
+        case = thehive_case_to_generic(raw)
+        from datetime import datetime
+
+        return CaseAssignment(
+            case_id=case.id or case_id,
+            assignee=case.assignee or assignee,
+            assigned_at=case.updated_at or datetime.utcnow(),
+        )
+
+    # Linking and timeline
+
+    def link_cases(
+        self,
+        source_case_id: str,
+        target_case_id: str,
+        link_type: str,
+    ) -> None:
+        payload = {
+            "caseId": target_case_id,
+            "nature": link_type,
+        }
+        self._http.post(f"/api/case/{source_case_id}/link", json=payload)
+
+    def get_case_timeline(self, case_id: str) -> List[CaseComment]:
+        # For now, use the comments endpoint as a simple timeline proxy.
+        raw_list = self._http.get(f"/api/case/{case_id}/comment")
+        return [thehive_comment_to_generic(raw, case_id=case_id) for raw in raw_list]
+
+    # Health check
+
+    def ping(self) -> bool:
+        try:
+            self._http.get("/api/health")
+            return True
+        except IntegrationError:
+            logger.exception("TheHive ping failed")
+            return False
+
+

src/integrations/case_management/thehive/thehive_http.py

@@ -0,0 +1,147 @@
+"""
+Low-level HTTP client for TheHive.
+
+This module is responsible for:
+- authentication (API key header)
+- building URLs
+- making HTTP requests
+- basic error handling
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import requests
+
+from ....core.errors import IntegrationError
+from ....core.logging import get_logger
+
+
+logger = get_logger("sami.integrations.thehive.http")
+
+
+@dataclass
+class TheHiveHttpClient:
+    """
+    Simple HTTP client for TheHive's REST API.
+    """
+
+    base_url: str
+    api_key: str
+    timeout_seconds: int = 30
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def authenticate(self) -> None:
+        """
+        Placeholder for any explicit authentication logic.
+
+        TheHive typically uses API keys in headers, so there may be no
+        separate login step. This method exists to match the design doc
+        and as a hook for future changes.
+        """
+
+        logger.debug("TheHiveHttpClient.authenticate called (no-op for API key)")
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make an HTTP request to TheHive and return the parsed JSON body.
+        """
+
+        url = build_url(self.base_url, path)
+        logger.debug(
+            "TheHive HTTP request",
+            extra={"method": method, "url": url, "params": params},
+        )
+
+        try:
+            response = requests.request(
+                method=method.upper(),
+                url=url,
+                headers=self._headers(),
+                json=json,
+                params=params,
+                timeout=self.timeout_seconds,
+            )
+        except requests.RequestException as exc:
+            raise IntegrationError(f"TheHive request failed: {exc}") from exc
+
+        handle_thehive_error(response)
+
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise IntegrationError(
+                f"TheHive response did not contain valid JSON (status={response.status_code})"
+            ) from exc
+
+    def get(
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        json: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        return self.request("POST", path, json=json)
+
+    def patch(
+        self,
+        path: str,
+        json: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        return self.request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> None:
+        self.request("DELETE", path)
+
+
+def build_url(base_url: str, path: str) -> str:
+    """
+    Join base URL and path safely.
+    """
+
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+
+
+def handle_thehive_error(response: requests.Response) -> None:
+    """
+    Raise an IntegrationError for non-success responses from TheHive.
+    """
+
+    if 200 <= response.status_code < 300:
+        return
+
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = {"raw": response.text}
+
+    logger.error(
+        "TheHive HTTP error",
+        extra={
+            "status_code": response.status_code,
+            "payload": payload,
+        },
+    )
+    raise IntegrationError(
+        f"TheHive error {response.status_code}: {payload}"
+    )
+
+

src/integrations/case_management/thehive/thehive_mapper.py

@@ -0,0 +1,190 @@
+"""
+Mapping logic between generic case management DTOs and TheHive models/payloads.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from ....api.case_management import (
+    Case,
+    CaseAssignment,
+    CaseComment,
+    CaseObservable,
+    CasePriority,
+    CaseStatus,
+    CaseSummary,
+)
+from .thehive_models import (
+    TheHiveCase,
+    TheHiveCasePriority,
+    TheHiveCaseStatus,
+    parse_thehive_case,
+    parse_thehive_observable,
+)
+
+
+# Generic → TheHive
+
+
+def case_to_thehive_payload(case: Case) -> Dict[str, Any]:
+    """
+    Convert a generic ``Case`` into a TheHive case creation/update payload.
+    """
+
+    payload: Dict[str, Any] = {
+        "title": case.title,
+        "description": case.description,
+        "tags": case.tags or [],
+    }
+
+    if case.priority is not None:
+        payload["severity"] = {
+            CasePriority.LOW: 1,
+            CasePriority.MEDIUM: 2,
+            CasePriority.HIGH: 3,
+            CasePriority.CRITICAL: 4,
+        }[case.priority]
+
+    if case.status is not None:
+        payload["status"] = status_to_thehive_status(case.status).value
+
+    if case.assignee:
+        payload["owner"] = case.assignee
+
+    return payload
+
+
+def comment_to_thehive_payload(comment: CaseComment) -> Dict[str, Any]:
+    return {
+        "message": comment.content,
+    }
+
+
+def observable_to_thehive_payload(observable: CaseObservable) -> Dict[str, Any]:
+    return {
+        "dataType": observable.type,
+        "data": observable.value,
+        "tags": observable.tags or [],
+        "message": observable.description or "",
+    }
+
+
+def status_to_thehive_status(status: CaseStatus) -> TheHiveCaseStatus:
+    mapping = {
+        CaseStatus.OPEN: TheHiveCaseStatus.OPEN,
+        CaseStatus.IN_PROGRESS: TheHiveCaseStatus.IN_PROGRESS,
+        CaseStatus.CLOSED: TheHiveCaseStatus.RESOLVED,
+    }
+    return mapping.get(status, TheHiveCaseStatus.OPEN)
+
+
+def priority_to_thehive_priority(priority: CasePriority) -> TheHiveCasePriority:
+    mapping = {
+        CasePriority.LOW: TheHiveCasePriority.LOW,
+        CasePriority.MEDIUM: TheHiveCasePriority.MEDIUM,
+        CasePriority.HIGH: TheHiveCasePriority.HIGH,
+        CasePriority.CRITICAL: TheHiveCasePriority.CRITICAL,
+    }
+    return mapping[priority]
+
+
+# TheHive → Generic
+
+
+def thehive_case_to_generic(raw: Dict[str, Any]) -> Case:
+    hive_case: TheHiveCase = parse_thehive_case(raw)
+
+    # Map severity back to CasePriority using simple thresholds.
+    severity = hive_case.severity or 0
+    if severity <= 1:
+        priority = CasePriority.LOW
+    elif severity == 2:
+        priority = CasePriority.MEDIUM
+    elif severity == 3:
+        priority = CasePriority.HIGH
+    else:
+        priority = CasePriority.CRITICAL
+
+    status_mapping = {
+        TheHiveCaseStatus.OPEN: CaseStatus.OPEN,
+        TheHiveCaseStatus.IN_PROGRESS: CaseStatus.IN_PROGRESS,
+        TheHiveCaseStatus.RESOLVED: CaseStatus.CLOSED,
+        TheHiveCaseStatus.DELETED: CaseStatus.CLOSED,
+    }
+    status = status_mapping.get(hive_case.status, CaseStatus.OPEN)
+
+    return Case(
+        id=hive_case.id,
+        title=hive_case.title,
+        description=hive_case.description or "",
+        status=status,
+        priority=priority,
+        created_at=hive_case.start_date,
+        updated_at=hive_case.start_date,
+        assignee=hive_case.owner,
+        tags=hive_case.tags or [],
+        observables=None,
+    )
+
+
+def thehive_case_to_summary(raw: Dict[str, Any]) -> CaseSummary:
+    hive_case: TheHiveCase = parse_thehive_case(raw)
+
+    severity = hive_case.severity or 0
+    if severity <= 1:
+        priority = CasePriority.LOW
+    elif severity == 2:
+        priority = CasePriority.MEDIUM
+    elif severity == 3:
+        priority = CasePriority.HIGH
+    else:
+        priority = CasePriority.CRITICAL
+
+    status_mapping = {
+        TheHiveCaseStatus.OPEN: CaseStatus.OPEN,
+        TheHiveCaseStatus.IN_PROGRESS: CaseStatus.IN_PROGRESS,
+        TheHiveCaseStatus.RESOLVED: CaseStatus.CLOSED,
+        TheHiveCaseStatus.DELETED: CaseStatus.CLOSED,
+    }
+    status = status_mapping.get(hive_case.status, CaseStatus.OPEN)
+
+    return CaseSummary(
+        id=hive_case.id,
+        title=hive_case.title,
+        status=status,
+        priority=priority,
+        created_at=hive_case.start_date,
+        updated_at=hive_case.start_date,
+        assignee=hive_case.owner,
+    )
+
+
+def thehive_comment_to_generic(raw: Dict[str, Any], case_id: str) -> CaseComment:
+    # TheHive uses "message" and "createdAt" in many comment-like resources.
+    from datetime import datetime
+
+    created_at_value = raw.get("createdAt")
+    created_at = None
+    if isinstance(created_at_value, (int, float)):
+        created_at = datetime.fromtimestamp(created_at_value / 1000.0)
+
+    return CaseComment(
+        id=str(raw.get("id") or raw.get("_id")),
+        case_id=case_id,
+        author=raw.get("user"),
+        content=raw.get("message", ""),
+        created_at=created_at,
+    )
+
+
+def thehive_observable_to_generic(raw: Dict[str, Any], case_id: str) -> CaseObservable:
+    hive_obs = parse_thehive_observable(raw)
+    return CaseObservable(
+        type=hive_obs.data_type,
+        value=hive_obs.data,
+        tags=hive_obs.tags or [],
+        description=None,
+    )
+
+

src/integrations/case_management/thehive/thehive_models.py

@@ -0,0 +1,125 @@
+"""
+TheHive-specific data models.
+
+These dataclasses are close to TheHive's API payloads but kept separate
+from the generic DTOs defined under ``src/api``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class TheHiveCaseStatus(str, Enum):
+    OPEN = "Open"
+    IN_PROGRESS = "InProgress"
+    RESOLVED = "Resolved"
+    DELETED = "Deleted"
+
+
+class TheHiveCasePriority(str, Enum):
+    LOW = "Low"
+    MEDIUM = "Medium"
+    HIGH = "High"
+    CRITICAL = "Critical"
+
+
+@dataclass
+class TheHiveUser:
+    id: str
+    login: str
+    name: Optional[str] = None
+
+
+@dataclass
+class TheHiveObservable:
+    id: str
+    data_type: str
+    data: str
+    tlp: Optional[int] = None
+    tags: Optional[List[str]] = None
+
+
+@dataclass
+class TheHiveAlert:
+    id: str
+    title: str
+    description: Optional[str] = None
+    severity: Optional[int] = None
+    source: Optional[str] = None
+    source_ref: Optional[str] = None
+
+
+@dataclass
+class TheHiveCase:
+    id: str
+    title: str
+    description: Optional[str]
+    severity: Optional[int]
+    start_date: Optional[datetime]
+    status: TheHiveCaseStatus
+    owner: Optional[str]
+    tags: Optional[List[str]] = None
+
+
+def parse_thehive_case(raw: Dict[str, Any]) -> TheHiveCase:
+    """
+    Parse a raw TheHive case dict into a ``TheHiveCase`` instance.
+    """
+
+    # TheHive uses numeric timestamps (epoch ms); keep parsing simple and
+    # allow None if absent.
+    start_date_value = raw.get("startDate")
+    start_date: Optional[datetime]
+    if isinstance(start_date_value, (int, float)):
+        start_date = datetime.fromtimestamp(start_date_value / 1000.0)
+    else:
+        start_date = None
+
+    status = raw.get("status", "Open")
+    case_status = TheHiveCaseStatus(status) if status in TheHiveCaseStatus._value2member_map_ else TheHiveCaseStatus.OPEN
+
+    return TheHiveCase(
+        id=str(raw.get("id") or raw.get("_id")),
+        title=raw.get("title", ""),
+        description=raw.get("description"),
+        severity=raw.get("severity"),
+        start_date=start_date,
+        status=case_status,
+        owner=raw.get("owner"),
+        tags=raw.get("tags") or [],
+    )
+
+
+def parse_thehive_observable(raw: Dict[str, Any]) -> TheHiveObservable:
+    """
+    Parse a raw TheHive observable dict.
+    """
+
+    return TheHiveObservable(
+        id=str(raw.get("id") or raw.get("_id")),
+        data_type=raw.get("dataType", ""),
+        data=raw.get("data", ""),
+        tlp=raw.get("tlp"),
+        tags=raw.get("tags") or [],
+    )
+
+
+def parse_thehive_alert(raw: Dict[str, Any]) -> TheHiveAlert:
+    """
+    Parse a raw TheHive alert dict.
+    """
+
+    return TheHiveAlert(
+        id=str(raw.get("id") or raw.get("_id")),
+        title=raw.get("title", ""),
+        description=raw.get("description"),
+        severity=raw.get("severity"),
+        source=raw.get("source"),
+        source_ref=raw.get("sourceRef"),
+    )
+
+

src/integrations/cti/__init__.py

@@ -0,0 +1,6 @@
+"""
+CTI (Cyber Threat Intelligence) integrations.
+
+This package provides integrations with threat intelligence platforms.
+"""
+

src/integrations/cti/local_tip/__init__.py

@@ -0,0 +1,10 @@
+"""
+Local TIP (Threat Intelligence Platform) integration.
+
+This module provides integration with a local TIP for hash lookups.
+"""
+
+from .local_tip_client import LocalTipCTIClient
+
+__all__ = ["LocalTipCTIClient"]
+