iflow-mcp_splunk_splunk-mcp-server 0.1.0__tar.gz

iflow_mcp_splunk_splunk_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,391 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_splunk_splunk-mcp-server
+Version: 0.1.0
+Summary: MCP server for retrieving data from Splunk
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: mcp[cli]>=1.3.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: httpx>=0.25.0
+
+# Splunk MCP Server
+
+An MCP (Model Context Protocol) server for retrieving data from Splunk Enterprise or Splunk Cloud.
+
+## Features
+
+- **FastMCP Framework**: Simplified server implementation
+- **Splunk Integration**: Direct REST API integration (no SDK dependency)
+- **Multiple Transports**: Supports both stdio and SSE
+- **Docker Support**: Ready for containerized deployment
+- **SPL Query Validation**: Built-in guardrails to detect risky, inefficient, or destructive queries
+- **Output Sanitization**: Automatic masking of sensitive data (credit cards, SSNs)
+- **Multiple Output Formats**: JSON, Markdown, CSV, and Summary formats
+- **Essential Tools**:
+  - `validate_spl`: Validate SPL queries for risks and inefficiencies
+  - `search_oneshot`: Run blocking search queries
+  - `search_export`: Stream search results immediately
+  - `get_indexes`: List available Splunk indexes
+  - `get_saved_searches`: List saved searches
+  - `run_saved_search`: Execute saved searches
+  - `get_config`: Get server configuration
+
+## Quick Start
+
+### 1. Setup Environment
+
+```bash
+cd /path/to/splunk-mcp-server/python
+cp .env.example .env
+# Edit .env with your Splunk connection details
+```
+
+### 2. Install Dependencies
+
+```bash
+pip install -e .
+```
+
+### 3. Run the Server
+
+**SSE Mode (default):**
+```bash
+python server.py
+```
+
+**Stdio Mode:**
+Configure via environment or let the client spawn the server.
+
+### 4. Test with Example Clients
+
+```bash
+cd tests
+
+# For SSE transport
+python test_sse_transport.py
+
+# For stdio transport
+python test_stdio_transport.py
+
+# Test SPL validation interactively
+python validate_spl_test.py
+
+# Interactive SPL search
+python splunk_sse_search.py
+
+# Or use the comprehensive test menu
+./testall
+```
+
+## Docker Deployment
+
+```bash
+# Using the dock script for common operations:
+
+# Build and start containers
+./dock rebuild
+
+# Start containers
+./dock up   # or ./dock start
+
+# Stop containers
+./dock down # or ./dock stop
+
+# Restart containers
+./dock restart
+
+# Manual docker commands:
+sudo docker compose build --no-cache
+sudo docker compose up -d
+```
+
+## Client Configuration
+
+### Claude Desktop
+
+**SSE Mode Configuration:**
+
+Edit your Claude Desktop configuration file:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "splunk-mcp": {
+      "url": "http://localhost:8050/sse"
+    }
+  }
+}
+```
+
+**Stdio Mode Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "splunk-mcp": {
+      "command": "python",
+      "args": ["/path/to/splunk-mcp-server/python/server.py"],
+      "env": {
+        "TRANSPORT": "stdio",
+        "SPLUNK_HOST": "your-splunk-host",
+        "SPLUNK_USERNAME": "your-username",
+        "SPLUNK_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+**SSE Mode Configuration:**
+
+Start the server:
+```bash
+cd /path/to/splunk-mcp-server/python
+python server.py
+```
+
+Add to Claude Code:
+```bash
+claude mcp add --transport sse --scope project splunk-mcp-server http://localhost:8050/sse
+```
+
+**Stdio Mode Configuration:**
+
+```bash
+cd /path/to/splunk-mcp-server/python
+claude mcp add splunk-mcp-server -e TRANSPORT=stdio --scope project -e SPLUNK_HOST=your-host -e SPLUNK_USERNAME=your-user -e SPLUNK_PASSWORD=your-pass -- python server.py
+
+# claude mcp remove splunk-mcp-server [--scope project]
+```
+
+## Available Tools
+
+### validate_spl
+Validate an SPL query for potential risks and inefficiencies before execution.
+
+Parameters:
+- `query`: The SPL query to validate
+
+Returns:
+- `risk_score`: Risk score from 0-100
+- `risk_message`: Detailed explanation of risks found with suggestions
+- `risk_tolerance`: Current risk tolerance setting  
+- `would_execute`: Whether this query would execute or be blocked
+- `execution_note`: Clear message about execution status
+
+Example:
+```
+validate_spl("index=* | delete")
+```
+
+### search_oneshot
+Run a blocking search query and return results.
+
+Parameters:
+- `query`: Splunk search query (e.g., "index=main | head 10")
+- `earliest_time`: Start time (default: "-24h")
+- `latest_time`: End time (default: "now")
+- `max_count`: Maximum results (default: 100 or SPL_MAX_EVENTS_COUNT)
+- `output_format`: Format for results - json, markdown/md, csv, or summary (default: "json")
+- `risk_tolerance`: Override risk tolerance level (default: SPL_RISK_TOLERANCE)
+- `sanitize_output`: Override output sanitization (default: SPL_SANITIZE_OUTPUT)
+
+Example:
+```
+search_oneshot("index=_internal | head 5", earliest_time="-1h", output_format="markdown")
+```
+
+### search_export
+Stream search results immediately without creating a job.
+
+Parameters:
+- `query`: Splunk search query
+- `earliest_time`: Start time (default: "-24h")
+- `latest_time`: End time (default: "now")
+- `max_count`: Maximum results (default: 100 or SPL_MAX_EVENTS_COUNT)
+- `output_format`: Format for results - json, markdown/md, csv, or summary (default: "json")
+- `risk_tolerance`: Override risk tolerance level (default: SPL_RISK_TOLERANCE)
+- `sanitize_output`: Override output sanitization (default: SPL_SANITIZE_OUTPUT)
+
+### get_indexes
+List all available Splunk indexes with properties.
+
+### get_saved_searches
+List all saved searches with their queries and descriptions.
+
+### run_saved_search
+Execute a saved search by name.
+
+Parameters:
+- `search_name`: Name of the saved search
+- `trigger_actions`: Whether to trigger actions (default: False)
+
+### get_config
+Get current server configuration (excludes sensitive data).
+
+## Configuration
+
+Edit `.env` file to customize:
+
+```bash
+# Server Configuration
+SERVER_NAME=Splunk MCP
+SERVER_DESCRIPTION=MCP server for retrieving data from Splunk
+HOST=0.0.0.0
+PORT=8050
+TRANSPORT=sse
+LOG_LEVEL=INFO
+
+# Splunk Configuration
+SPLUNK_HOST=localhost
+SPLUNK_PORT=8089
+SPLUNK_USERNAME=admin
+SPLUNK_PASSWORD=changeme
+# Optional: Use token instead of username/password
+SPLUNK_TOKEN=
+# SSL verification
+VERIFY_SSL=false
+
+# Search Configuration
+# Maximum number of events to return from searches (0 = unlimited)
+SPL_MAX_EVENTS_COUNT=100000
+
+# Risk tolerance level for SPL query validation (0 = reject all risky queries, 100 = allow all)
+SPL_RISK_TOLERANCE=75
+
+# Safe time range for searches - queries within this range get no time penalty
+SPL_SAFE_TIMERANGE=24h
+
+# Enable output sanitization to mask sensitive data (credit cards, SSNs)
+SPL_SANITIZE_OUTPUT=false
+```
+
+## Common Splunk Search Patterns
+
+### Get recent errors:
+```
+index=main level=ERROR | head 20
+```
+
+### Get statistics by source:
+```
+index=_internal | stats count by source
+```
+
+### Time-based searches:
+```
+index=main earliest=-1h latest=now | timechart count
+```
+
+### Field extraction:
+```
+index=web_logs | rex field=_raw "status=(?<status_code>\d+)" | stats count by status_code
+```
+
+## SPL Query Validation (Guardrails)
+
+The server includes built-in validation to detect potentially risky or inefficient SPL queries before execution. This helps prevent:
+
+- **Destructive Operations**: Commands like `delete` that permanently remove data
+- **Performance Issues**: Unbounded searches, expensive commands, or missing time ranges
+- **Resource Consumption**: Queries that could overwhelm system resources  
+- **Security Risks**: External script execution or unsafe operations
+
+### Risk Scoring
+
+Each query is analyzed and assigned a risk score from 0-100:
+- **0-30**: Low risk - Query is generally safe
+- **31-60**: Medium risk - Query may have performance implications
+- **61-100**: High risk - Query could be destructive or severely impact performance
+
+### Common Risk Factors
+
+1. **Destructive Commands** (High Risk):
+   - `delete` command (+80 points)
+   - `collect` with `override=true` (+25 points)
+   - `outputlookup` with `override=true` (+20 points)
+
+2. **Time Range Issues**:
+   - All-time searches or missing time constraints (+50 points)
+   - Time ranges exceeding safe threshold (+20 points)
+
+3. **Performance Concerns**:
+   - `index=*` without constraints (+35 points)
+   - Expensive commands like `transaction`, `map`, `join` (+20 points each)
+   - Missing index specification (+20 points)
+   - Subsearches without limits (+20 points)
+
+4. **Security Risks**:
+   - External script execution (+40 points)
+
+### Configuration
+
+Configure validation behavior in your `.env` file:
+- `SPL_RISK_TOLERANCE`: Set threshold for blocking queries (default: 75)
+- `SPL_SAFE_TIMERANGE`: Define safe time range (default: 24h)
+- `SPL_SANITIZE_OUTPUT`: Enable/disable output sanitization
+
+### Output Sanitization
+
+When `SPL_SANITIZE_OUTPUT=true`, the server automatically masks sensitive data:
+- **Credit Cards**: Shows only last 4 digits (e.g., ****-****-****-1234)
+- **Social Security Numbers**: Completely masked (e.g., ***-**-****)
+
+### Testing Validation
+
+Use the interactive validation tool to test queries:
+
+```bash
+cd tests
+python validate_spl_test.py
+```
+
+## Security Notes
+
+- Store credentials securely in `.env` file
+- Use token authentication when possible
+- Enable SSL verification in production (`VERIFY_SSL=true`)
+- Never commit `.env` file to version control
+
+## Troubleshooting
+
+### Connection Issues
+- Verify Splunk is running and accessible
+- Check firewall rules for port 8089
+- Ensure credentials are correct
+- Try disabling SSL verification for testing
+
+### Search Issues
+- Verify user has search permissions
+- Check index access rights
+- Use `| head` to limit results during testing
+- Check Splunk search job limits
+
+## Project Structure
+
+```
+python/
+├── .env.example          # Environment configuration template
+├── server.py             # Main server implementation
+├── splunk_client.py      # Splunk REST API client
+├── helpers.py            # Formatting utilities
+├── guardrails.py         # SPL query validation and sanitization
+├── spl_risk_rules.py     # Configurable risk rules for validation
+├── pyproject.toml        # Python project configuration
+├── Dockerfile            # Docker deployment configuration
+├── docker-compose.yml    # Docker compose configuration
+├── dock                  # Docker management script
+├── README.md             # This file
+└── tests/
+    ├── test_sse_transport.py    # SSE transport tests
+    ├── test_stdio_transport.py  # Stdio transport tests
+    ├── validate_spl_test.py     # Interactive validation tool
+    ├── splunk_sse_search.py     # Interactive search tool
+    ├── testall                  # Comprehensive test menu
+    └── quick_test.py            # Quick smoke test
+```