ms-sentinel-mcp-server

# Microsoft Sentinel MCP Server - LLM Quick Start Guide ## Overview This MCP server provides LLMs with secure, read-only access to Microsoft Sentinel security data through standardized tools and resources. The server acts as a bridge between AI assistants and Azure security infrastructure. ## Core Architecture ### Component Auto-Discovery System The server automatically discovers and registers components from three directories: - `tools/` - Executable functions that interact with Azure APIs - `resources/` - Static content like documentation and templates - `prompts/` - Templates for LLM-driven workflows Each component implements a `register_*` function that's called during server startup. ### Base Tool Pattern All tools inherit from `MCPToolBase` (tools/base.py) which provides: - Azure client authentication and context management - Consistent error handling and logging - Parameter extraction from kwargs - Async execution patterns for blocking API calls ### Context Flow 1. MCP server initializes Azure credentials and workspace context 2. Tools access this context via `self.get_*_client()` methods 3. Blocking Azure SDK calls are wrapped with `run_in_thread()` 4. Results are formatted and returned to the LLM ## Essential Workflow Pattern ### 1. Documentation First Approach Always start by retrieving tool documentation before usage: ``` 1. tool_docs_list - See all available documentation 2. tool_docs_get <path> - Get specific tool documentation 3. Use the tool with proper parameters ``` ### 2. Common Tool Sequences **KQL Query Workflow:** ``` 1. sentinel_logs_tables_list - See available data tables 2. sentinel_logs_table_schema_get - Understand table structure 3. sentinel_query_validate - Validate KQL syntax 4. sentinel_logs_search - Execute query ``` **Security Investigation:** ``` 1. sentinel_incident_details_get - Get incident context 2. sentinel_logs_search - Query related events 3. sentinel_analytics_rule_get - Check detection rules 4. markdown_template_get - Format results ``` ## Tool Categories & Use Cases ### Core Query Tools - `sentinel_logs_search` - Execute KQL queries against workspace data - `sentinel_query_validate` - Validate KQL syntax without execution - `sentinel_logs_search_with_dummy_data` - Test queries with mock data ### Workspace & Tables - `sentinel_workspace_get` - Get workspace information and configuration - `sentinel_logs_tables_list` - List all available data tables - `sentinel_logs_table_schema_get` - Get detailed table schema - `sentinel_logs_table_details_get` - Get table metadata and statistics ### Security Operations - `sentinel_incident_details_get` - Get detailed incident information - `sentinel_analytics_rule_list` - List detection rules - `sentinel_analytics_rule_get` - Get specific rule details - `sentinel_hunting_queries_list` - List threat hunting queries ### Intelligence & Context - `sentinel_domain_whois_get` - Get domain WHOIS information - `sentinel_ip_geodata_get` - Get IP geolocation data - `sentinel_watchlists_list` - List threat intelligence watchlists ### Documentation & Templates - `tool_docs_search` - Search across all documentation - `markdown_templates_list` - List formatting templates - `markdown_template_get` - Get specific template content ## Key Authentication Patterns ### Environment Variables (Priority Order) 1. Service Principal: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID` 2. Azure CLI: `az login` (no additional env vars needed) 3. Required: `AZURE_SUBSCRIPTION_ID`, `AZURE_RESOURCE_GROUP`, `AZURE_WORKSPACE_NAME`, `AZURE_WORKSPACE_ID` ### Context Access in Tools Tools access Azure context via base class methods: ```python # Get authenticated clients logs_client, workspace_id = self.get_logs_client_and_workspace(ctx) security_client = self.get_securityinsight_client(subscription_id) # Get workspace details workspace_name, resource_group, subscription_id = self.get_azure_context(ctx) ``` ## Best Practices for LLMs ### Query Construction - Always validate KQL queries before execution - Use table schemas to understand available fields - Limit query time ranges to avoid timeouts - Format large result sets as summaries, not raw data ### Error Handling - Check tool documentation if parameters are unclear - Validate workspace connectivity with `sentinel_workspace_get` - Use `sentinel_authorization_summary` to check permissions ### Result Formatting - Use markdown templates for consistent output formatting - Structure security findings with proper context - Include disclaimers for security recommendations - Never expose sensitive data (tokens, connection strings) ### Performance Tips - Use `tool_docs_search` instead of reading individual files - Combine related tool calls when possible - Cache workspace/table information for repeated queries - Use dummy data mode for query testing and development ## Common Error Scenarios 1. **Missing Environment Variables**: Check Azure configuration with `sentinel_workspace_get` 2. **Authentication Failures**: Verify `az login` status or service principal setup 3. **Query Timeouts**: Reduce time ranges or add query filters 4. **Permission Errors**: Use `sentinel_authorization_summary` to check RBAC roles 5. **Invalid KQL**: Always use `sentinel_query_validate` before execution ## Security Considerations - Server provides READ-ONLY access to Sentinel data - All operations respect Azure RBAC permissions - Designed for TEST environments, not production - No data modification or configuration changes possible - Sensitive credentials handled securely through Azure SDK patterns This guide provides the essential knowledge for effective LLM interaction with the Microsoft Sentinel MCP Server. For detailed parameter information, always consult the specific tool documentation using the `tool_docs_*` functions.