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

src/api/siem.py

@@ -0,0 +1,308 @@
+"""
+Generic SIEM API for SamiGPT.
+
+This module defines vendor-neutral DTOs and the ``SIEMClient`` interface
+that orchestrator code and LLM tools will use for searching security events
+and retrieving reports about files, IPs, and related entities.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional, Protocol
+
+from ..core.dto import BaseDTO
+
+
+class Severity(str, Enum):
+    """
+    Generic severity levels for SIEM alerts/events.
+    """
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class AlertStatus(str, Enum):
+    """
+    Generic status for SIEM alerts.
+    """
+
+    OPEN = "open"
+    IN_PROGRESS = "in_progress"
+    CLOSED = "closed"
+    SUPPRESSED = "suppressed"
+
+
+class SourceType(str, Enum):
+    """
+    High-level source type for events.
+    """
+
+    ENDPOINT = "endpoint"
+    NETWORK = "network"
+    AUTH = "auth"
+    CLOUD = "cloud"
+    OTHER = "other"
+
+
+@dataclass
+class SiemEvent(BaseDTO):
+    """
+    Generic SIEM event.
+    """
+
+    id: str
+    timestamp: datetime
+    source_type: SourceType
+    message: str
+    host: Optional[str] = None
+    username: Optional[str] = None
+    ip: Optional[str] = None
+    process_name: Optional[str] = None
+    file_hash: Optional[str] = None
+    raw: Optional[dict] = None
+
+
+@dataclass
+class SiemAlert(BaseDTO):
+    """
+    Generic SIEM alert.
+    """
+
+    id: str
+    created_at: datetime
+    severity: Severity
+    status: AlertStatus
+    title: str
+    description: Optional[str] = None
+    related_entities: Optional[List[str]] = None
+    raw: Optional[dict] = None
+
+
+@dataclass
+class QueryResult(BaseDTO):
+    """
+    Container for results of a security event search.
+    """
+
+    query: str
+    events: List[SiemEvent]
+    total_count: int
+
+
+@dataclass
+class FileReport(BaseDTO):
+    """
+    Aggregated report about a file (by hash).
+    """
+
+    file_hash: str
+    first_seen: Optional[datetime] = None
+    last_seen: Optional[datetime] = None
+    detection_count: int = 0
+    affected_hosts: Optional[List[str]] = None
+    raw: Optional[dict] = None
+
+
+@dataclass
+class FileBehaviorSummary(BaseDTO):
+    """
+    High-level behavior summary for a file.
+    """
+
+    file_hash: str
+    process_trees: Optional[List[dict]] = None
+    network_activity: Optional[List[dict]] = None
+    persistence_mechanisms: Optional[List[str]] = None
+    notes: Optional[str] = None
+
+
+@dataclass
+class IpAddressReport(BaseDTO):
+    """
+    Aggregated report for an IP address.
+    """
+
+    ip: str
+    reputation: Optional[str] = None
+    geo: Optional[dict] = None
+    related_alerts: Optional[List[str]] = None
+    raw: Optional[dict] = None
+
+
+@dataclass
+class RelatedEntities(BaseDTO):
+    """
+    Entities related to a specific indicator (e.g. file hash).
+    """
+
+    indicator: str
+    hosts: Optional[List[str]] = None
+    users: Optional[List[str]] = None
+    processes: Optional[List[str]] = None
+    alerts: Optional[List[str]] = None
+
+
+class SIEMClient(Protocol):
+    """
+    Vendor-neutral interface for SIEM operations.
+
+    This interface is designed to support the skills described in the README:
+    - search_security_events
+    - get_file_report
+    - get_file_behavior_summary
+    - get_entities_related_to_file
+    - get_ip_address_report
+    - search_user_activity
+    - pivot_on_indicator
+    """
+
+    def search_security_events(
+        self,
+        query: str,
+        limit: int = 100,
+    ) -> QueryResult:
+        """
+        Search security events/logs across environments using a vendor-specific
+        query language or filter, returning a normalized result.
+        """
+
+        ...
+
+    def get_file_report(self, file_hash: str) -> FileReport:
+        ...
+
+    def get_file_behavior_summary(self, file_hash: str) -> FileBehaviorSummary:
+        ...
+
+    def get_entities_related_to_file(self, file_hash: str) -> RelatedEntities:
+        ...
+
+    def get_ip_address_report(self, ip: str) -> IpAddressReport:
+        ...
+
+    def search_user_activity(
+        self,
+        username: str,
+        limit: int = 100,
+    ) -> QueryResult:
+        ...
+
+    def pivot_on_indicator(
+        self,
+        indicator: str,
+        limit: int = 200,
+    ) -> QueryResult:
+        """
+        Given an IOC (hash, IP, domain, etc.), search for related events
+        and return them for further investigation.
+        """
+
+        ...
+
+    def search_kql_query(
+        self,
+        kql_query: str,
+        limit: int = 500,
+        hours_back: Optional[int] = None,
+    ) -> QueryResult:
+        """
+        Execute a KQL (Kusto Query Language) or advanced query for deeper investigations.
+        
+        This method allows for complex queries that may include:
+        - Advanced filtering and aggregation
+        - Time-based analysis
+        - Cross-index searches
+        - Complex joins and correlations
+        
+        Args:
+            kql_query: KQL query string or advanced query DSL
+            limit: Maximum number of events to return (default: 500)
+            hours_back: Optional time window in hours to limit the search
+            
+        Returns:
+            QueryResult containing matching events
+        """
+        ...
+
+    def get_siem_event_by_id(
+        self,
+        event_id: str,
+    ) -> SiemEvent:
+        """
+        Retrieve a specific security event by its ID.
+        
+        Args:
+            event_id: The unique identifier of the event to retrieve.
+            
+        Returns:
+            SiemEvent containing the event details.
+            
+        Raises:
+            IntegrationError: If the event is not found or retrieval fails.
+        """
+        ...
+
+    def close_alert(
+        self,
+        alert_id: str,
+        reason: Optional[str] = None,
+        comment: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Close an alert in the SIEM, typically used for false positives.
+        
+        Args:
+            alert_id: The ID of the alert to close.
+            reason: Optional reason for closing (e.g., "false_positive", "benign_true_positive").
+            comment: Optional comment explaining why the alert is being closed.
+        
+        Returns:
+            Dictionary with success status and alert details.
+        """
+        ...
+
+    def tag_alert(
+        self,
+        alert_id: str,
+        tag: str,
+    ) -> Dict[str, Any]:
+        """
+        Tag an alert with a classification tag (FP, TP, or NMI).
+        
+        Args:
+            alert_id: The ID of the alert to tag.
+            tag: The tag to apply. Must be one of: "FP" (False Positive), 
+                 "TP" (True Positive), or "NMI" (Need More Investigation).
+        
+        Returns:
+            Dictionary with success status and alert details including updated tags.
+        """
+        ...
+
+    def add_alert_note(
+        self,
+        alert_id: str,
+        note: str,
+    ) -> Dict[str, Any]:
+        """
+        Add a note/comment to an alert in the SIEM.
+        
+        This is used to document investigation findings, recommendations,
+        or other relevant information about the alert.
+        
+        Args:
+            alert_id: The ID of the alert to add a note to.
+            note: The note/comment text to add.
+        
+        Returns:
+            Dictionary with success status and alert details including the note.
+        """
+        ...
+
+

src/core/__init__.py

@@ -0,0 +1,10 @@
+"""
+Core utilities for SamiGPT.
+
+This package holds:
+- configuration loading (`config.py`)
+- shared error types (`errors.py`)
+- logging helpers (`logging.py`)
+"""
+
+

src/core/config.py

@@ -0,0 +1,242 @@
+"""
+Configuration models and loading logic for SamiGPT.
+
+The goal of this module is to provide a single place where runtime
+configuration (API URLs, auth tokens, timeouts, logging settings, etc.)
+is defined and loaded from the environment.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from typing import Optional
+
+from .errors import ConfigError
+
+
+@dataclass
+class TheHiveConfig:
+    """
+    Configuration for the TheHive case management integration.
+    """
+
+    base_url: str
+    api_key: str
+    timeout_seconds: int = 30
+
+
+@dataclass
+class IrisConfig:
+    """
+    Configuration for the IRIS case management integration.
+    """
+
+    base_url: str
+    api_key: str
+    timeout_seconds: int = 30
+    verify_ssl: bool = True
+
+
+@dataclass
+class ElasticConfig:
+    """
+    Configuration for Elastic (SIEM) integration.
+    """
+
+    base_url: str
+    api_key: Optional[str] = None
+    username: Optional[str] = None
+    password: Optional[str] = None
+    timeout_seconds: int = 30
+    verify_ssl: bool = True
+
+
+@dataclass
+class EDRConfig:
+    """
+    Configuration for EDR integration (generic, can be Velociraptor, CrowdStrike, Elastic Defend, etc.).
+    """
+
+    edr_type: str  # e.g., "velociraptor", "crowdstrike", "elastic_defend"
+    base_url: str
+    api_key: str
+    timeout_seconds: int = 30
+    verify_ssl: bool = True
+    additional_params: Optional[dict] = None
+
+
+@dataclass
+class CTIConfig:
+    """
+    Configuration for CTI (Cyber Threat Intelligence) integration.
+    """
+
+    cti_type: str  # e.g., "local_tip", "opencti"
+    base_url: str
+    api_key: Optional[str] = None  # Required for OpenCTI, optional for local_tip
+    timeout_seconds: int = 30
+    verify_ssl: bool = True
+
+
+@dataclass
+class TrelloConfig:
+    """
+    Configuration for Trello integration.
+    """
+
+    api_key: str
+    api_token: str
+    fine_tuning_board_id: str
+    engineering_board_id: str
+    timeout_seconds: int = 30
+    verify_ssl: bool = True
+
+
+@dataclass
+class ClickUpConfig:
+    """
+    Configuration for ClickUp integration.
+    """
+
+    api_token: str
+    fine_tuning_list_id: str
+    engineering_list_id: str
+    space_id: Optional[str] = None  # Optional space ID for workspace organization
+    timeout_seconds: int = 30
+    verify_ssl: bool = True
+
+
+@dataclass
+class GitHubConfig:
+    """
+    Configuration for GitHub integration.
+    """
+
+    api_token: str
+    fine_tuning_project_id: str
+    engineering_project_id: str
+    timeout_seconds: int = 30
+    verify_ssl: bool = True
+
+
+@dataclass
+class EngConfig:
+    """
+    Configuration for Engineering integrations.
+    """
+
+    trello: Optional[TrelloConfig] = None
+    clickup: Optional[ClickUpConfig] = None
+    github: Optional[GitHubConfig] = None
+    provider: str = "trello"  # "trello", "clickup", or "github" - which provider to use
+
+
+@dataclass
+class LoggingConfig:
+    """
+    Logging-related configuration.
+    """
+
+    log_dir: str = "logs"
+    log_level: str = "INFO"
+
+
+@dataclass
+class WebConfig:
+    """
+    Configuration for the web management interface.
+    """
+
+    admin_secret: str  # Secret/password for accessing the management interface
+    session_secret: Optional[str] = None  # Secret for session signing (auto-generated if not provided)
+
+
+@dataclass
+class SamiConfig:
+    """
+    Top-level configuration for SamiGPT.
+
+    Additional sections (for SIEM, EDR, etc.) can be added here later.
+    """
+
+    thehive: Optional[TheHiveConfig] = None
+    iris: Optional[IrisConfig] = None
+    elastic: Optional[ElasticConfig] = None
+    edr: Optional[EDRConfig] = None
+    cti: Optional[CTIConfig] = None
+    eng: Optional[EngConfig] = None
+    logging: Optional[LoggingConfig] = None
+    web: Optional[WebConfig] = None
+
+
+def _require_env(name: str) -> str:
+    """
+    Read a required environment variable or raise ConfigError if missing.
+    """
+
+    value = os.getenv(name)
+    if not value:
+        raise ConfigError(f"Required environment variable {name!r} is not set")
+    return value
+
+
+def load_config() -> SamiConfig:
+    """
+    Load SamiGPT configuration from environment variables.
+
+    Environment variables:
+        SAMIGPT_THEHIVE_URL: Base URL for TheHive (required if TheHive is used).
+        SAMIGPT_THEHIVE_API_KEY: API key/token for TheHive.
+        SAMIGPT_THEHIVE_TIMEOUT_SECONDS: Request timeout for TheHive (default: 30).
+
+        SAMIGPT_LOG_DIR: Directory for log files (default: "logs").
+        SAMIGPT_LOG_LEVEL: Root log level (default: "INFO").
+
+    If TheHive variables are not set, the configuration will still be returned
+    with `thehive` set to None, allowing you to run without that integration.
+    """
+
+    # Logging config
+    log_dir = os.getenv("SAMIGPT_LOG_DIR", "logs")
+    log_level = os.getenv("SAMIGPT_LOG_LEVEL", "INFO")
+    logging_cfg = LoggingConfig(log_dir=log_dir, log_level=log_level)
+
+    # TheHive config (optional but recommended). If one of the key vars is set,
+    # we require the others to avoid a half-configured integration.
+    thehive_url = os.getenv("SAMIGPT_THEHIVE_URL")
+    thehive_api_key = os.getenv("SAMIGPT_THEHIVE_API_KEY")
+    thehive_timeout_raw = os.getenv("SAMIGPT_THEHIVE_TIMEOUT_SECONDS", "30")
+
+    thehive_cfg: Optional[TheHiveConfig]
+    if thehive_url or thehive_api_key:
+        # If any TheHive-related env var is set, treat TheHive as enabled
+        if not thehive_url:
+            raise ConfigError(
+                "SAMIGPT_THEHIVE_URL must be set when SAMIGPT_THEHIVE_API_KEY is provided"
+            )
+        if not thehive_api_key:
+            raise ConfigError(
+                "SAMIGPT_THEHIVE_API_KEY must be set when SAMIGPT_THEHIVE_URL is provided"
+            )
+        try:
+            timeout_seconds = int(thehive_timeout_raw)
+        except ValueError as exc:
+            raise ConfigError(
+                "SAMIGPT_THEHIVE_TIMEOUT_SECONDS must be an integer"
+            ) from exc
+
+        thehive_cfg = TheHiveConfig(
+            base_url=thehive_url,
+            api_key=thehive_api_key,
+            timeout_seconds=timeout_seconds,
+        )
+    else:
+        thehive_cfg = None
+
+    return SamiConfig(
+        thehive=thehive_cfg,
+        logging=logging_cfg,
+    )
+
+