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

src/integrations/siem/elastic/elastic_http.py

@@ -0,0 +1,165 @@
+"""
+Low-level HTTP client for Elasticsearch/Elastic SIEM.
+
+This module is responsible for:
+- authentication (API key or username/password)
+- 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.elastic.http")
+
+
+@dataclass
+class ElasticHttpClient:
+    """
+    Simple HTTP client for Elasticsearch/Elastic SIEM API.
+    
+    Supports both API key and username/password authentication.
+    """
+
+    base_url: str
+    api_key: Optional[str] = None
+    username: Optional[str] = None
+    password: Optional[str] = None
+    timeout_seconds: int = 30
+    verify_ssl: bool = True
+
+    def _headers(self) -> Dict[str, str]:
+        """Build request headers with authentication."""
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        
+        if self.api_key:
+            # Elastic API key format: "ApiKey <base64-encoded-key>"
+            if not self.api_key.startswith("ApiKey "):
+                headers["Authorization"] = f"ApiKey {self.api_key}"
+            else:
+                headers["Authorization"] = self.api_key
+        elif self.username and self.password:
+            # Basic auth
+            import base64
+            credentials = base64.b64encode(f"{self.username}:{self.password}".encode()).decode()
+            headers["Authorization"] = f"Basic {credentials}"
+        
+        return headers
+
+    def _build_url(self, endpoint: str) -> str:
+        """
+        Build a full URL from a base URL and an endpoint.
+        
+        Args:
+            endpoint: API endpoint path (e.g., "/_search" or "_search")
+        
+        Returns:
+            Full URL string
+        """
+        base = self.base_url.rstrip("/")
+        endpoint = endpoint.lstrip("/")
+        
+        return f"{base}/{endpoint}"
+
+    def _handle_elastic_error(self, response: requests.Response) -> None:
+        """
+        Raise IntegrationError if the response indicates an error.
+        
+        Args:
+            response: HTTP response object
+        
+        Raises:
+            IntegrationError: If the response indicates an error
+        """
+        if response.status_code < 400:
+            return
+
+        try:
+            error_data = response.json()
+            error_type = error_data.get("error", {}).get("type", "Unknown")
+            error_reason = error_data.get("error", {}).get("reason", f"HTTP {response.status_code}")
+            full_message = f"{error_type}: {error_reason}"
+        except Exception:
+            full_message = f"HTTP {response.status_code}: {response.text[:200]}"
+
+        raise IntegrationError(f"Elastic 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 Elasticsearch 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"Elastic {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"Elastic response status: {response.status_code}")
+            if response.status_code >= 400:
+                logger.error(f"Elastic API error - Status: {response.status_code}, URL: {url}, Response: {response.text[:500]}")
+
+            self._handle_elastic_error(response)
+
+            if response.status_code == 204:  # No Content
+                return {}
+
+            return response.json()
+
+        except requests.exceptions.Timeout as e:
+            raise IntegrationError(f"Elastic API request timeout: {e}") from e
+        except requests.exceptions.RequestException as e:
+            raise IntegrationError(f"Elastic 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) -> Dict[str, Any]:
+        """POST request."""
+        return self.request("POST", endpoint, json_data=json_data)
+

src/mcp/README.md

@@ -0,0 +1,183 @@
+# SamiGPT MCP Server
+
+This directory contains the Model Context Protocol (MCP) server implementation for SamiGPT, which exposes all investigation and response capabilities as tools that can be used by AI assistants and automation systems.
+
+## Overview
+
+The MCP server enables integration with various LLM clients including:
+- **Cursor IDE** - AI-powered code editor
+- **Claude Desktop** - Anthropic's Claude AI assistant
+- **Open WebUI** - Web-based LLM interface
+- **Cline** - VS Code extension for AI assistance
+- Any MCP-compatible client
+
+## Files
+
+- **`mcp_server.py`**: Main MCP server implementation
+  - Implements JSON-RPC 2.0 over stdio
+  - Handles tool registration and execution
+  - Manages client connections and protocol negotiation
+
+- **`rules_engine.py`**: Rules/workflow engine
+  - Executes automated investigation workflows
+  - Chains together multiple investigation skills
+  - Supports custom rule definitions
+
+- **`TOOLS.md`**: Comprehensive tool documentation
+  - Detailed documentation for all available tools
+  - Usage examples and best practices
+  - Parameter descriptions and return values
+
+## Available Tools
+
+### Case Management Tools (8 tools)
+Tools for managing security incidents and cases:
+- `review_case` - Get complete case details
+- `list_cases` - List cases with optional filters
+- `search_cases` - Advanced case search
+- `add_case_comment` - Add notes to cases
+- `attach_observable_to_case` - Track IOCs
+- `update_case_status` - Update case workflow
+- `assign_case` - Assign to analysts
+- `get_case_timeline` - View case history
+
+### SIEM Tools (7 tools)
+Tools for security event analysis:
+- `search_security_events` - Query security logs
+- `get_file_report` - Analyze files by hash
+- `get_file_behavior_summary` - File behavior analysis
+- `get_entities_related_to_file` - Find related entities
+- `get_ip_address_report` - IP reputation and context
+- `search_user_activity` - User activity investigation
+- `pivot_on_indicator` - IOC-based investigation
+
+### EDR Tools (6 tools)
+Tools for endpoint investigation and response:
+- `get_endpoint_summary` - Endpoint overview
+- `get_detection_details` - Detection analysis
+- `isolate_endpoint` - Network isolation (critical)
+- `release_endpoint_isolation` - Restore connectivity
+- `kill_process_on_endpoint` - Terminate processes (disruptive)
+- `collect_forensic_artifacts` - Evidence collection
+
+### Rules Engine Tools (2 tools)
+Tools for automated workflows:
+- `list_rules` - List available workflows
+- `execute_rule` - Run automated playbooks
+
+## Quick Start
+
+### Running the Server
+
+```bash
+python -m src.mcp.mcp_server
+```
+
+The server communicates via stdio using JSON-RPC 2.0 protocol.
+
+### Configuration
+
+The server automatically loads configuration from `config.json` in the project root. Configure integrations using the web configuration UI:
+
+```bash
+python -m src.web.config_server
+```
+
+### Tool Usage
+
+All tools are documented in **[TOOLS.md](TOOLS.md)** with:
+- Detailed parameter descriptions
+- Return value specifications
+- Usage examples
+- Best practices
+- Workflow examples
+
+## Protocol Support
+
+The server supports MCP protocol versions:
+- `2024-11-05` (default)
+- `2025-06-18` (auto-negotiated with compatible clients)
+
+## Logging
+
+MCP-specific logs are written to `logs/mcp/`:
+- `mcp_all.log` - All MCP activity (DEBUG level)
+- `mcp_requests.log` - Incoming requests
+- `mcp_responses.log` - Outgoing responses
+- `mcp_errors.log` - Errors only
+
+## Integration Examples
+
+### Cursor IDE
+
+See [CURSOR_INTEGRATION.md](../../CURSOR_INTEGRATION.md) for setup instructions.
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "sami-gpt": {
+      "command": "python",
+      "args": ["-m", "src.mcp.mcp_server"],
+      "cwd": "/path/to/SamiGPT"
+    }
+  }
+}
+```
+
+### Open WebUI
+
+Configure via environment variables or UI settings.
+
+## Tool Availability
+
+Tools are conditionally available based on configured integrations:
+
+- **Case Management Tools**: Require TheHive or IRIS configuration
+- **SIEM Tools**: Require Elastic or other SIEM configuration
+- **EDR Tools**: Require EDR platform configuration
+- **Rules Engine Tools**: Always available
+
+Use `list_rules` to discover available automated workflows.
+
+## Security Considerations
+
+⚠️ **Critical Actions**: Some tools perform disruptive operations:
+- `isolate_endpoint` - Disconnects endpoint from network
+- `kill_process_on_endpoint` - Terminates running processes
+
+Always verify parameters before executing critical actions. These operations are logged at WARNING level.
+
+## Development
+
+### Adding New Tools
+
+1. Implement the tool function in the appropriate `tools_*.py` module
+2. Register the tool in `mcp_server.py` using `_register_*_tools()` methods
+3. Add comprehensive documentation to `TOOLS.md`
+4. Update this README if adding a new tool category
+
+### Testing
+
+Test the MCP server manually:
+```bash
+echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | python -m src.mcp.mcp_server
+```
+
+## Documentation
+
+- **[TOOLS.md](TOOLS.md)** - Complete tool documentation
+- **[../CURSOR_INTEGRATION.md](../CURSOR_INTEGRATION.md)** - Cursor setup guide
+- **[../MCP_CLIENT_EXAMPLES.md](../MCP_CLIENT_EXAMPLES.md)** - Client configuration examples
+- **[../README.md](../README.md)** - Main project documentation
+
+## Support
+
+For issues or questions:
+1. Check the logs in `logs/mcp/`
+2. Review tool documentation in `TOOLS.md`
+3. Verify configuration in `config.json`
+4. Check integration-specific documentation
+