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

src/core/dto.py

@@ -0,0 +1,50 @@
+"""
+Common DTO utilities for SamiGPT.
+
+We use Python dataclasses for DTOs across the generic API layer. This module
+provides a small mixin with helper methods so all DTOs have a consistent
+API (e.g., ``to_dict``).
+
+Design choices:
+- Style: synchronous (no async in DTOs or interfaces).
+- Response pattern: API clients return DTOs (or lists of DTOs) directly,
+  without wrapping everything in a ``result`` + ``metadata`` envelope.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, Type, TypeVar
+
+
+T_BaseDTO = TypeVar("T_BaseDTO", bound="BaseDTO")
+
+
+@dataclass
+class BaseDTO:
+    """
+    Base mixin for DTO dataclasses.
+
+    Inherit from this in DTOs to get a consistent ``to_dict`` method and
+    a simple ``from_dict`` constructor.
+    """
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert this DTO into a plain dict (recursively).
+        """
+
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls: Type[T_BaseDTO], data: Dict[str, Any]) -> T_BaseDTO:
+        """
+        Construct this DTO from a dict of attributes.
+
+        This is a thin wrapper around normal dataclass construction; any
+        extra validation should be implemented by callers as needed.
+        """
+
+        return cls(**data)
+
+

src/core/errors.py

@@ -0,0 +1,36 @@
+"""
+Core error types for SamiGPT.
+
+These exceptions provide a common base for all raised errors across the
+project so that callers (including the orchestrator and web API) can handle
+them in a consistent way.
+"""
+
+from __future__ import annotations
+
+
+class SamiError(Exception):
+    """
+    Base exception for all SamiGPT-specific errors.
+    """
+
+
+class ConfigError(SamiError):
+    """
+    Raised when configuration is missing, invalid, or inconsistent.
+    """
+
+
+class IntegrationError(SamiError):
+    """
+    Raised when an external integration (TheHive, SIEM, EDR, etc.) fails
+    or returns an unexpected response.
+    """
+
+
+class ValidationError(SamiError):
+    """
+    Raised when input data, DTOs, or configuration values fail validation.
+    """
+
+

src/core/logging.py

@@ -0,0 +1,128 @@
+"""
+Shared logging configuration for SamiGPT.
+
+This module centralizes logging setup so that all components
+(core, API layer, integrations, orchestrator, web API) can
+log in a consistent way.
+"""
+
+from __future__ import annotations
+
+import logging
+import logging.handlers
+import os
+from typing import Optional
+
+from .config import LoggingConfig
+
+
+def configure_logging(config: Optional[LoggingConfig] = None) -> None:
+    """
+    Configure application-wide logging.
+
+    This function is idempotent: calling it multiple times will not
+    re-add handlers if they already exist.
+    """
+
+    if config is None:
+        # Fall back to sensible defaults if no config is provided.
+        config = LoggingConfig()
+
+    log_dir = config.log_dir
+    os.makedirs(log_dir, exist_ok=True)
+
+    root_logger = logging.getLogger()
+
+    # Avoid configuring logging twice.
+    if getattr(root_logger, "_sami_logging_configured", False):
+        return
+
+    root_logger.setLevel(config.log_level.upper())
+
+    formatter = logging.Formatter(
+        fmt="%(asctime)s [%(levelname)s] %(name)s [%(message)s]",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    # Error log
+    error_handler = logging.FileHandler(os.path.join(log_dir, "error.log"))
+    error_handler.setLevel(logging.ERROR)
+    error_handler.setFormatter(formatter)
+
+    # Warning log
+    warning_handler = logging.FileHandler(os.path.join(log_dir, "warning.log"))
+    warning_handler.setLevel(logging.WARNING)
+    warning_handler.setFormatter(formatter)
+
+    # Debug log
+    debug_handler = logging.FileHandler(os.path.join(log_dir, "debug.log"))
+    debug_handler.setLevel(logging.DEBUG)
+    debug_handler.setFormatter(formatter)
+
+    # Optional console handler for development.
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(config.log_level.upper())
+    console_handler.setFormatter(formatter)
+
+    root_logger.addHandler(error_handler)
+    root_logger.addHandler(warning_handler)
+    root_logger.addHandler(debug_handler)
+    root_logger.addHandler(console_handler)
+
+    # Mark as configured
+    root_logger._sami_logging_configured = True  # type: ignore[attr-defined]
+
+    # ------------------------------------------------------------------
+    # Dedicated logging for ai_controller components
+    # ------------------------------------------------------------------
+    try:
+        from pathlib import Path
+
+        core_dir = Path(__file__).resolve().parent
+        ai_controller_logs_dir = core_dir.parent / "ai_controller" / "logs"
+        os.makedirs(ai_controller_logs_dir, exist_ok=True)
+
+        ai_logger = logging.getLogger("sami.ai_controller")
+
+        if not getattr(ai_logger, "_sami_ai_controller_logging_configured", False):
+            ai_formatter = logging.Formatter(
+                fmt="%(asctime)s [%(levelname)s] %(name)s [%(message)s]",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+
+            # Error log for ai_controller
+            ai_error_handler = logging.FileHandler(os.path.join(ai_controller_logs_dir, "error.log"))
+            ai_error_handler.setLevel(logging.ERROR)
+            ai_error_handler.setFormatter(ai_formatter)
+
+            # Warning log for ai_controller
+            ai_warning_handler = logging.FileHandler(os.path.join(ai_controller_logs_dir, "warning.log"))
+            ai_warning_handler.setLevel(logging.WARNING)
+            ai_warning_handler.setFormatter(ai_formatter)
+
+            # Debug log for ai_controller (includes info/debug)
+            ai_debug_handler = logging.FileHandler(os.path.join(ai_controller_logs_dir, "debug.log"))
+            ai_debug_handler.setLevel(logging.DEBUG)
+            ai_debug_handler.setFormatter(ai_formatter)
+
+            ai_logger.addHandler(ai_error_handler)
+            ai_logger.addHandler(ai_warning_handler)
+            ai_logger.addHandler(ai_debug_handler)
+
+            # Ensure we still propagate to root so central logs receive entries too
+            ai_logger.propagate = True
+
+            ai_logger._sami_ai_controller_logging_configured = True  # type: ignore[attr-defined]
+    except Exception:
+        # Never let logging configuration crash the app
+        root_logger.exception("Failed to configure dedicated ai_controller logging handlers")
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Convenience helper to get a logger for a given module or subsystem.
+    """
+
+    return logging.getLogger(name)
+
+

src/integrations/__init__.py

@@ -0,0 +1,8 @@
+"""
+Vendor-specific integrations for SamiGPT.
+
+Each subpackage implements one or more of the generic interfaces defined
+under ``src/api`` (e.g., case management, SIEM, EDR).
+"""
+
+

src/integrations/case_management/__init__.py

@@ -0,0 +1,5 @@
+"""
+Case management integrations (e.g., TheHive, ServiceNow, Jira).
+"""
+
+

src/integrations/case_management/iris/__init__.py

@@ -0,0 +1,11 @@
+"""
+IRIS case management integration.
+
+IRIS (https://github.com/dfir-iris/iris) is an open-source incident response platform.
+This module provides integration with IRIS for case management.
+"""
+
+from .iris_client import IRISCaseManagementClient
+
+__all__ = ["IRISCaseManagementClient"]
+