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

src/integrations/case_management/iris/iris_http.py

@@ -0,0 +1,274 @@
+"""
+Low-level HTTP client for IRIS.
+
+This module is responsible for:
+- authentication (API key header)
+- building URLs
+- making HTTP requests
+- basic error handling
+"""
+
+from __future__ import annotations
+
+import json
+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.iris.http")
+
+
+@dataclass
+class IrisHttpClient:
+    """
+    Simple HTTP client for IRIS's REST API.
+    
+    IRIS API documentation: https://docs.dfir-iris.org/
+    """
+
+    base_url: str
+    api_key: str
+    timeout_seconds: int = 30
+    verify_ssl: bool = True
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+    def authenticate(self) -> None:
+        """
+        Placeholder for any explicit authentication logic.
+        
+        IRIS 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("IrisHttpClient.authenticate called (no-op for API key)")
+
+    def _build_url(self, endpoint: str) -> str:
+        """
+        Build a full URL from a base URL and an endpoint.
+        
+        IRIS API v2.0.0+ uses direct paths without /api/v1/ prefix for manage endpoints.
+        API endpoints (like /api/ping, /api/versions) use /api/ prefix.
+        
+        Args:
+            endpoint: API endpoint path (e.g., "/manage/cases/list" or "manage/cases/list")
+        
+        Returns:
+            Full URL string
+        """
+        base = self.base_url.rstrip("/")
+        endpoint = endpoint.lstrip("/")
+        
+        # IRIS API structure:
+        # - /api/* for API endpoints (ping, versions, etc.)
+        # - /manage/* for management endpoints (cases, users, etc.)
+        # - /case/* for case-specific operations
+        # No need to add /api/v1/ prefix - use endpoint as-is
+        
+        return f"{base}/{endpoint}"
+
+    def _handle_iris_error(self, response: requests.Response) -> None:
+        """
+        Raise IntegrationError if the response indicates an error.
+        
+        IRIS API returns responses in format: {"status": "success|error", "message": "...", "data": ...}
+        
+        Args:
+            response: HTTP response object
+        
+        Raises:
+            IntegrationError: If the response indicates an error
+        """
+        if response.status_code < 400:
+            # Check if response body indicates an error
+            try:
+                error_data = response.json()
+                if error_data.get("status") == "error":
+                    message = error_data.get("message", "Unknown error")
+                    raise IntegrationError(f"IRIS API error: {message}")
+            except (ValueError, IntegrationError):
+                # If it's already an IntegrationError, re-raise it
+                if isinstance(error_data, dict) and error_data.get("status") == "error":
+                    raise
+                # Otherwise continue (might not be JSON or might be success)
+            return
+
+        # HTTP error status code
+        try:
+            error_data = response.json()
+            # IRIS API error format
+            if error_data.get("status") == "error":
+                message = error_data.get("message", f"HTTP {response.status_code}")
+            else:
+                message = error_data.get("message", f"HTTP {response.status_code}")
+            details = error_data.get("detail") or error_data.get("error", "")
+            full_message = f"{message}: {details}" if details else message
+        except Exception:
+            full_message = f"HTTP {response.status_code}: {response.text[:200]}"
+
+        raise IntegrationError(f"IRIS API error: {full_message}")
+
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make an HTTP request to IRIS API.
+        
+        Args:
+            method: HTTP method (GET, POST, PUT, PATCH, DELETE)
+            endpoint: API endpoint path
+            json_data: JSON payload (for POST, PUT, PATCH)
+            params: Query parameters (for GET, etc.)
+        
+        Returns:
+            Response JSON as dictionary
+        
+        Raises:
+            IntegrationError: If the request fails
+        """
+        url = self._build_url(endpoint)
+        headers = self._headers()
+
+        try:
+            logger.debug(f"IRIS {method} {url}")
+            if params:
+                logger.debug(f"  Query params: {params}")
+            if json_data:
+                logger.debug(f"  JSON payload: {json.dumps(json_data)[:200]}...")
+
+            response = requests.request(
+                method=method,
+                url=url,
+                headers=headers,
+                json=json_data,
+                params=params,
+                timeout=self.timeout_seconds,
+                verify=self.verify_ssl,
+            )
+
+            logger.debug(f"IRIS response status: {response.status_code}")
+            if response.status_code >= 400:
+                logger.error(f"IRIS API error - Status: {response.status_code}, URL: {url}, Response: {response.text[:500]}")
+
+            self._handle_iris_error(response)
+
+            if response.status_code == 204:  # No Content
+                return {}
+
+            response_data = response.json()
+            
+            # IRIS API wraps responses in {"status": "success", "message": "", "data": ...}
+            # Extract the data field if present
+            if isinstance(response_data, dict):
+                if response_data.get("status") == "success" and "data" in response_data:
+                    return response_data["data"]
+                elif response_data.get("status") == "error":
+                    # Error already handled by _handle_iris_error, but just in case
+                    message = response_data.get("message", "Unknown error")
+                    raise IntegrationError(f"IRIS API error: {message}")
+            
+            return response_data
+
+        except requests.exceptions.Timeout as e:
+            raise IntegrationError(f"IRIS API request timeout: {e}") from e
+        except requests.exceptions.RequestException as e:
+            raise IntegrationError(f"IRIS API request failed: {e}") from e
+
+    def get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """GET request."""
+        return self.request("GET", endpoint, params=params)
+
+    def post(self, endpoint: str, json_data: Optional[Dict[str, Any]] = None, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """POST request."""
+        return self.request("POST", endpoint, json_data=json_data, params=params)
+    
+    def post_file(
+        self,
+        endpoint: str,
+        file_path: str,
+        file_field: str = "file",
+        additional_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        POST request with file upload.
+        
+        Args:
+            endpoint: API endpoint path
+            file_path: Path to file to upload
+            file_field: Form field name for the file (default: "file")
+            additional_data: Additional form data to include
+            params: Query parameters to include in the URL
+        
+        Returns:
+            Response JSON as dictionary
+        """
+        import os
+        from pathlib import Path
+        
+        url = self._build_url(endpoint)
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            # Don't set Content-Type - let requests set it for multipart/form-data
+        }
+        
+        if not os.path.exists(file_path):
+            raise IntegrationError(f"File not found: {file_path}")
+        
+        try:
+            with open(file_path, "rb") as f:
+                files = {file_field: (os.path.basename(file_path), f)}
+                data = additional_data or {}
+                
+                logger.debug(f"IRIS POST FILE {url}")
+                if params:
+                    logger.debug(f"  Query params: {params}")
+                logger.debug(f"  File: {file_path}, Field: {file_field}")
+                
+                response = requests.post(
+                    url,
+                    headers=headers,
+                    files=files,
+                    data=data,
+                    params=params,
+                    timeout=self.timeout_seconds,
+                    verify=self.verify_ssl,
+                )
+                
+                logger.debug(f"IRIS response status: {response.status_code}")
+                if response.status_code >= 400:
+                    logger.error(f"IRIS API error - Status: {response.status_code}, URL: {url}, Response: {response.text[:500]}")
+                
+                self._handle_iris_error(response)
+                
+                if response.status_code == 204:
+                    return {}
+                
+                return response.json()
+        except requests.exceptions.Timeout as e:
+            raise IntegrationError(f"IRIS API request timeout: {e}") from e
+        except requests.exceptions.RequestException as e:
+            raise IntegrationError(f"IRIS API request failed: {e}") from e
+
+    def patch(self, endpoint: str, json_data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """PATCH request."""
+        return self.request("PATCH", endpoint, json_data=json_data)
+
+    def delete(self, endpoint: str) -> Dict[str, Any]:
+        """DELETE request."""
+        return self.request("DELETE", endpoint)
+

src/integrations/case_management/iris/iris_mapper.py

@@ -0,0 +1,263 @@
+"""
+Mapping logic between generic case management DTOs and IRIS models/payloads.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ....api.case_management import (
+    Case,
+    CaseAssignment,
+    CaseComment,
+    CaseObservable,
+    CasePriority,
+    CaseStatus,
+    CaseSummary,
+)
+from .iris_models import (
+    IrisCase,
+    IrisCasePriority,
+    IrisCaseStatus,
+    parse_iris_case,
+    parse_iris_ioc,
+)
+
+
+# Generic → IRIS
+
+
+def case_to_iris_payload(case: Case) -> Dict[str, Any]:
+    """
+    Convert a generic ``Case`` into an IRIS case creation/update payload.
+    """
+    payload: Dict[str, Any] = {
+        "case_name": case.title,
+        "case_description": case.description or "",
+        "case_customer": 3,  # Always use "All" client (customer_id: 3)
+        "case_soc_id": "soc_id_default",  # Required field - default SOC ID
+    }
+    
+    # Convert tags list to comma-separated string (only if tags exist)
+    if case.tags:
+        tags_str = ", ".join(case.tags)
+        payload["case_tags"] = tags_str  # IRIS expects tags as a string, not a list
+
+    # Note: state_id and severity_id are not set during creation
+    # IRIS will set defaults (state_id: 3, severity_id: 4)
+    # These can be updated after case creation if needed
+
+    if case.assignee:
+        # Note: IRIS uses user_id, so we'd need to resolve username to ID
+        # For now, assume assignee can be a username or ID string
+        payload["case_owner"] = case.assignee
+
+    return payload
+
+
+def comment_to_iris_payload(comment: CaseComment) -> Dict[str, Any]:
+    """Convert generic comment to IRIS payload."""
+    return {
+        "comment_content": comment.content,
+    }
+
+
+def observable_type_to_iris_ioc_type_id(observable_type: str) -> int:
+    """
+    Map generic observable type string to IRIS IOC type ID.
+    
+    Common mappings:
+    - ip, ip-any -> 76 (ip-any)
+    - ip-dst -> 77
+    - ip-src -> 79
+    - domain -> 20
+    - url -> 141
+    - hash, md5 -> 90
+    - sha1 -> 111
+    - sha256 -> 113
+    - email -> 22
+    """
+    type_lower = observable_type.lower()
+    
+    # IP addresses
+    if type_lower in ("ip", "ip-any", "ip_address"):
+        return 76  # ip-any
+    elif type_lower == "ip-dst":
+        return 77
+    elif type_lower == "ip-src":
+        return 79
+    
+    # Domains
+    elif type_lower in ("domain", "fqdn", "hostname"):
+        return 20  # domain
+    
+    # URLs
+    elif type_lower in ("url", "uri"):
+        return 141  # url
+    
+    # Hashes
+    elif type_lower in ("hash", "md5"):
+        return 90  # md5
+    elif type_lower == "sha1":
+        return 111
+    elif type_lower == "sha256":
+        return 113
+    
+    # Email
+    elif type_lower in ("email", "email-address"):
+        return 22  # email
+    
+    # Default to "other" if type not recognized
+    return 96  # other
+
+
+def observable_to_iris_payload(observable: CaseObservable) -> Dict[str, Any]:
+    """Convert generic observable to IRIS IOC payload."""
+    # Convert tags list to comma-separated string if needed
+    tags_str = ", ".join(observable.tags) if observable.tags else ""
+    
+    return {
+        "ioc_type_id": observable_type_to_iris_ioc_type_id(observable.type),
+        "ioc_value": observable.value,
+        "ioc_tags": tags_str,  # IRIS may expect string or list - try string first
+        "ioc_description": observable.description or "",
+        "ioc_tlp_id": 2,  # Default to TLP:AMBER (1=WHITE, 2=AMBER, 3=GREEN, 4=RED)
+    }
+
+
+def status_to_iris_status(case_status: CaseStatus) -> IrisCaseStatus:
+    """Map generic CaseStatus to IRIS CaseStatus enum."""
+    mapping = {
+        CaseStatus.OPEN: IrisCaseStatus.OPEN,
+        CaseStatus.IN_PROGRESS: IrisCaseStatus.ONGOING,
+        CaseStatus.CLOSED: IrisCaseStatus.CLOSED,
+    }
+    return mapping.get(case_status, IrisCaseStatus.OPEN)
+
+
+def status_to_iris_status_id(case_status: CaseStatus) -> int:
+    """Map generic CaseStatus to IRIS status ID."""
+    # IRIS status IDs: typically 1=open, 2=ongoing, 3=closed, 4=archived
+    status_id_map = {
+        CaseStatus.OPEN: 1,
+        CaseStatus.IN_PROGRESS: 2,
+        CaseStatus.CLOSED: 3,
+    }
+    return status_id_map.get(case_status, 1)
+
+
+def priority_to_iris_priority(priority: CasePriority) -> IrisCasePriority:
+    """Map generic CasePriority to IRIS CasePriority enum."""
+    mapping = {
+        CasePriority.LOW: IrisCasePriority.LOW,
+        CasePriority.MEDIUM: IrisCasePriority.MEDIUM,
+        CasePriority.HIGH: IrisCasePriority.HIGH,
+        CasePriority.CRITICAL: IrisCasePriority.CRITICAL,
+    }
+    return mapping[priority]
+
+
+def priority_id_to_case_priority(priority_id: Optional[int]) -> CasePriority:
+    """Map IRIS priority ID to generic CasePriority."""
+    if priority_id is None:
+        return CasePriority.MEDIUM
+    
+    # IRIS priority mapping: 4=low, 3=medium, 2=high, 1=critical
+    if priority_id >= 4:
+        return CasePriority.LOW
+    elif priority_id == 3:
+        return CasePriority.MEDIUM
+    elif priority_id == 2:
+        return CasePriority.HIGH
+    else:
+        return CasePriority.CRITICAL
+
+
+def status_id_to_case_status(status_id: Optional[int]) -> CaseStatus:
+    """Map IRIS status ID to generic CaseStatus."""
+    if status_id is None:
+        return CaseStatus.OPEN
+    
+    # IRIS status IDs: typically 1=open, 2=ongoing, 3=closed, 4=archived
+    if status_id == 1:
+        return CaseStatus.OPEN
+    elif status_id == 2:
+        return CaseStatus.IN_PROGRESS
+    else:
+        return CaseStatus.CLOSED
+
+
+# IRIS → Generic
+
+
+def iris_case_to_generic(raw: Dict[str, Any]) -> Case:
+    """Convert IRIS case to generic Case."""
+    iris_case: IrisCase = parse_iris_case(raw)
+
+    priority = priority_id_to_case_priority(iris_case.case_priority_id)
+    status = status_id_to_case_status(iris_case.case_status_id)
+
+    return Case(
+        id=str(iris_case.case_id),
+        title=iris_case.case_name,
+        description=iris_case.case_description or "",
+        status=status,
+        priority=priority,
+        created_at=iris_case.case_open_date,
+        updated_at=iris_case.case_update_date or iris_case.case_open_date,
+        assignee=str(iris_case.case_owner_id) if iris_case.case_owner_id else None,
+        tags=iris_case.case_tags or [],
+        observables=None,
+    )
+
+
+def iris_case_to_summary(raw: Dict[str, Any]) -> CaseSummary:
+    """Convert IRIS case to generic CaseSummary."""
+    iris_case: IrisCase = parse_iris_case(raw)
+
+    priority = priority_id_to_case_priority(iris_case.case_priority_id)
+    status = status_id_to_case_status(iris_case.case_status_id)
+
+    return CaseSummary(
+        id=str(iris_case.case_id),
+        title=iris_case.case_name,
+        status=status,
+        priority=priority,
+        created_at=iris_case.case_open_date,
+        updated_at=iris_case.case_update_date or iris_case.case_open_date,
+        assignee=str(iris_case.case_owner_id) if iris_case.case_owner_id else None,
+    )
+
+
+def iris_comment_to_generic(raw: Dict[str, Any], case_id: str) -> CaseComment:
+    """Convert IRIS comment to generic CaseComment."""
+    from datetime import datetime
+
+    created_at_value = raw.get("comment_date") or raw.get("comment_added")
+    created_at = None
+    if isinstance(created_at_value, (int, float)):
+        created_at = datetime.fromtimestamp(created_at_value)
+    elif isinstance(created_at_value, str):
+        try:
+            created_at = datetime.fromisoformat(created_at_value.replace("Z", "+00:00"))
+        except Exception:
+            pass
+
+    return CaseComment(
+        id=str(raw.get("comment_id", raw.get("id", 0))),
+        case_id=case_id,
+        author=raw.get("comment_user") or raw.get("user_name") or raw.get("user"),
+        content=raw.get("comment_content", raw.get("content", "")),
+        created_at=created_at,
+    )
+
+
+def iris_ioc_to_observable(raw: Dict[str, Any], case_id: str) -> CaseObservable:
+    """Convert IRIS IOC to generic CaseObservable."""
+    iris_ioc = parse_iris_ioc(raw)
+    return CaseObservable(
+        type=iris_ioc.ioc_type,
+        value=iris_ioc.ioc_value,
+        tags=iris_ioc.ioc_tags or [],
+        description=iris_ioc.ioc_description,
+    )

src/integrations/case_management/iris/iris_models.py

@@ -0,0 +1,128 @@
+"""
+IRIS-specific data models.
+
+These dataclasses are close to IRIS'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 IrisCaseStatus(str, Enum):
+    """IRIS case status values."""
+    OPEN = "open"
+    ONGOING = "ongoing"
+    CLOSED = "closed"
+    ARCHIVED = "archived"
+
+
+class IrisCasePriority(str, Enum):
+    """IRIS case priority values."""
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+@dataclass
+class IrisUser:
+    """IRIS user model."""
+    id: int
+    user: str
+    name: Optional[str] = None
+    email: Optional[str] = None
+
+
+@dataclass
+class IrisIOC:
+    """IRIS IOCs (Indicators of Compromise) model."""
+    id: int
+    ioc_type: str  # e.g., "ip", "domain", "hash", etc.
+    ioc_value: str
+    ioc_tags: Optional[List[str]] = None
+    ioc_description: Optional[str] = None
+
+
+@dataclass
+class IrisCase:
+    """IRIS case model."""
+    case_id: int
+    case_name: str
+    case_description: Optional[str]
+    case_priority_id: Optional[int]  # Maps to priority: 4=low, 3=medium, 2=high, 1=critical
+    case_open_date: Optional[datetime]
+    case_update_date: Optional[datetime]
+    case_status_id: Optional[int]  # Maps to status
+    case_owner_id: Optional[int]
+    case_tags: Optional[List[str]] = None
+
+
+def parse_iris_case(raw: Dict[str, Any]) -> IrisCase:
+    """
+    Parse a raw IRIS case dict into an ``IrisCase`` instance.
+    
+    IRIS API uses integer IDs and different field names than TheHive.
+    """
+    # IRIS uses timestamps or ISO format strings
+    open_date_value = raw.get("case_open_date") or raw.get("open_date")
+    open_date: Optional[datetime] = None
+    if isinstance(open_date_value, (int, float)):
+        open_date = datetime.fromtimestamp(open_date_value)
+    elif isinstance(open_date_value, str):
+        try:
+            open_date = datetime.fromisoformat(open_date_value.replace("Z", "+00:00"))
+        except Exception:
+            pass
+    
+    update_date_value = raw.get("case_update_date") or raw.get("update_date")
+    update_date: Optional[datetime] = None
+    if isinstance(update_date_value, (int, float)):
+        update_date = datetime.fromtimestamp(update_date_value)
+    elif isinstance(update_date_value, str):
+        try:
+            update_date = datetime.fromisoformat(update_date_value.replace("Z", "+00:00"))
+        except Exception:
+            pass
+
+    return IrisCase(
+        case_id=int(raw.get("case_id", raw.get("id", 0))),
+        case_name=raw.get("case_name", raw.get("name", "")),
+        case_description=raw.get("case_description", raw.get("description")),
+        case_priority_id=raw.get("case_priority_id", raw.get("priority_id")),
+        case_open_date=open_date,
+        case_update_date=update_date,
+        case_status_id=raw.get("case_status_id", raw.get("status_id")),
+        case_owner_id=raw.get("case_owner_id", raw.get("owner_id")),
+        case_tags=raw.get("case_tags", raw.get("tags")) or [],
+    )
+
+
+def parse_iris_ioc(raw: Dict[str, Any]) -> IrisIOC:
+    """
+    Parse a raw IRIS IOC dict.
+    """
+    return IrisIOC(
+        id=int(raw.get("ioc_id", 0)),
+        ioc_type=raw.get("ioc_type", ""),
+        ioc_value=raw.get("ioc_value", ""),
+        ioc_tags=raw.get("ioc_tags") or [],
+        ioc_description=raw.get("ioc_description"),
+    )
+
+
+def parse_iris_user(raw: Dict[str, Any]) -> IrisUser:
+    """
+    Parse a raw IRIS user dict.
+    """
+    return IrisUser(
+        id=int(raw.get("user_id", 0)),
+        user=raw.get("user", ""),
+        name=raw.get("name"),
+        email=raw.get("email"),
+    )
+

src/integrations/case_management/thehive/__init__.py

@@ -0,0 +1,8 @@
+"""
+TheHive case management integration for SamiGPT.
+
+This package implements the generic ``CaseManagementClient`` interface
+defined in ``src/api/case_management.py`` using TheHive's HTTP API.
+"""
+
+