# Splunk MCP for SOC Operations

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![FastMCP](https://img.shields.io/badge/FastMCP-enabled-green.svg)](https://github.com/jlowin/fastmcp)

An AI-native MCP (Model Context Protocol) server for SOC operations with Splunk, featuring automated investigation tools, label harvesting, and DeepTempo integration capabilities.

## 🎯 Overview

This project extends the capabilities of [livehybrid/splunk-mcp](https://github.com/livehybrid/splunk-mcp) with SOC-specific enrichment tools and security controls designed for AI-driven security investigations via Claude Desktop and other MCP clients.

### Key Features

- **Traditional SOC Workflows** - IP pivoting, lateral movement detection, data exfiltration analysis
- **AI-Native Investigation** - Cross-platform correlation, attack timeline reconstruction  
- **Label Harvesting** - Automatic discovery and mapping of Splunk field labels
- **Production Security** - Input validation, audit logging, output sanitization
- **Multi-Mode Operation** - SSE, STDIO, and API modes for flexible deployment

## 🚀 Quick Start

### Prerequisites

- Python 3.10 or higher
- Splunk Enterprise or Cloud instance
- pip (included with Python)

### Installation

1. **Clone the repository:**
   ```bash
   git clone https://github.com/mando222/splunk-mcp-soc.git
   cd splunk-mcp-soc
   ```

2. **Install dependencies:**
   
   **Using pip (recommended):**
   ```bash
   pip install -r requirements.txt
   ```
   
   **Or with UV:**
   ```bash
   uv sync
   ```
   
   **Or with Poetry:**
   ```bash
   poetry install
   ```

3. **Configure environment variables:**
   
   Create a `.env` file:
   ```env
   SPLUNK_HOST=localhost
   SPLUNK_PORT=8089
   SPLUNK_USERNAME=admin
   SPLUNK_PASSWORD=your-password
   SPLUNK_SCHEME=https
   VERIFY_SSL=false
   ```

4. **Test the connection:**
   ```bash
   python test_connection.py
   ```

5. **Run the MCP server:**
   ```bash
   # STDIO mode (for Claude Desktop)
   python splunk_mcp.py stdio
   
   # SSE mode (default)
   python splunk_mcp.py
   
   # API mode
   python splunk_mcp.py api
   ```

## 🛠️ Available MCP Tools

### Core Operations
- **health_check** - Verify Splunk connectivity and available apps
- **ping** - Check MCP server status
- **current_user** - Get authenticated user information
- **list_users** - List all Splunk users and roles

### Index & Search Management
- **list_indexes** - List all accessible indexes
- **get_index_info** - Get detailed information about a specific index
- **indexes_and_sourcetypes** - Comprehensive index and sourcetype mapping
- **search_splunk** - Execute Splunk search queries with time ranges
- **list_saved_searches** - View saved searches

### KV Store Operations
- **list_kvstore_collections** - List all KV store collections
- **create_kvstore_collection** - Create new collections
- **delete_kvstore_collection** - Remove collections

### SOC Investigation Tools
- **pivot_by_ip** - Investigate all activity from a specific IP address
- **find_lateral_movement** - Detect lateral movement patterns
- **calculate_data_exfiltration** - Analyze and quantify data exfiltration
- **build_attack_timeline** - Construct chronological attack timelines
- **correlate_with_deeptempo_finding** - Cross-reference with DeepTempo findings

### Threat Intelligence Integration
- **enrich_ip_with_threat_intel** - Enrich IPs with reputation data from multiple sources
  - Queries AbuseIPDB, AlienVault OTX, and internal Splunk threat lists
  - Provides reputation score, threat types, and confidence levels
- **check_ioc_reputation** - Quick reputation check for any IOC (IP, domain, hash, URL)
  - Auto-detects IOC type and provides actionable verdict
- **add_to_threat_list** - Add confirmed IOCs to Splunk threat intelligence
  - Supports expiration and automatic cleanup
- **get_mitre_attack_context** - Get detailed MITRE ATT&CK technique information
  - Maps findings to tactics, techniques, and procedures
  - Includes detection methods and mitigations

### Automated Response Actions
- **block_ip_address** - Block malicious IPs at firewall/proxy level
  - Temporary or permanent blocking
  - Auto-unblock capability with configurable duration
- **isolate_host** - Quarantine compromised hosts from network
  - Full, partial, or monitoring-only isolation levels
  - Integrates with NAC and endpoint security tools
- **create_incident_ticket** - Auto-create tickets in ITSM platforms
  - ServiceNow, Jira, or native Splunk incident tracking
  - Automatic priority and SLA calculation
- **send_alert_notification** - Push alerts to communication channels
  - Slack, Microsoft Teams, PagerDuty, email, SMS
  - Severity-based routing

### Advanced Analytics & Anomaly Detection
- **detect_anomalies** - Statistical anomaly detection on time-series data
  - Z-score based detection with configurable sensitivity
  - Identifies spikes, dips, and unusual patterns
- **identify_rare_events** - Find statistically rare occurrences
  - Detects new processes, domains, or behaviors
  - Useful for zero-day and APT detection
- **baseline_normal_behavior** - Establish behavioral profiles
  - Learn normal patterns for users, hosts, or services
  - Enables deviation-based threat detection

### Label Harvesting
- **harvest_labels** - Discover field labels and schemas from Splunk indexes
  - Configurable scope (all indexes, specific indexes, or CIM fields only)
  - Returns field names, types, sample values, and metadata
  - Supports filtering by index and time range
- **get_field_summary** - Get detailed information about a specific field
  - Deep dive into field values, distribution, and relationships
  - Useful for understanding individual field usage
- **export_labels_to_deeptempo** - Export labels in DeepTempo-compatible format
  - Generic JSON structure that can be adapted to DeepTempo's needs
  - Optional file export for integration workflows

## 📊 Demo Scenarios

### Scenario 1: IP Investigation
```
Query: "Show me all activity from IP 10.1.42.42"

Results:
- 65 total events discovered
- 47 unique destinations contacted
- 10+ lateral movement attempts detected
- 1.2 GB data exfiltration identified
```

### Scenario 2: Attack Timeline
```
Query: "Build attack timeline for 10.1.42.42 and correlate with DeepTempo"

Results:
- 32-day attack timeline reconstructed
- Initial compromise → lateral movement → exfiltration
- 12 similar incidents identified
- Complete MITRE ATT&CK mapping
```

### Scenario 3: Threat Hunting
```
Query: "Hunt for similar C2 beaconing patterns across all hosts"

Results:
- 3 additional compromised hosts found
- Common service account identified (jenkins_service)
- Botnet infrastructure mapped
```

## 🧪 Testing

Generate and ingest test security data:

```bash
# Generate test data
python generate_test_data.py

# Ingest into Splunk
python ingest_test_data.py your-password
```

This creates an `mcp_demo` index with 115 security events:
- 50 C2 beaconing events
- 40 authentication/lateral movement events  
- 20 DNS tunneling events
- 5 data exfiltration events

Run the test suite:
```bash
pytest tests/
```

## 🐳 Docker Support

### Run with Docker Compose

1. **SSE Mode (default):**
```bash
docker compose up -d mcp
```

2. **API Mode:**
```bash
docker compose run --rm mcp python splunk_mcp.py api
```

3. **STDIO Mode:**
```bash
docker compose run -i --rm mcp python splunk_mcp.py stdio
```

### Run Tests in Docker
```bash
./run_tests.sh --docker
```

## 🔧 Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SPLUNK_HOST` | Splunk server hostname | localhost |
| `SPLUNK_PORT` | Splunk management port | 8089 |
| `SPLUNK_USERNAME` | Authentication username | admin |
| `SPLUNK_PASSWORD` | Authentication password | - |
| `SPLUNK_TOKEN` | Optional: Use token instead of user/pass | - |
| `SPLUNK_SCHEME` | Connection scheme (http/https) | https |
| `VERIFY_SSL` | Enable SSL certificate verification | true |
| `FASTMCP_LOG_LEVEL` | Logging level | INFO |
| `SERVER_MODE` | Server mode (sse/api/stdio) | sse |

### Claude Desktop Integration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "splunk-soc": {
      "command": "python",
      "args": [
        "/path/to/splunk-mcp-soc/splunk_mcp.py",
        "stdio"
      ],
      "env": {
        "SPLUNK_HOST": "localhost",
        "SPLUNK_PORT": "8089",
        "SPLUNK_USERNAME": "admin",
        "SPLUNK_PASSWORD": "your-password"
      }
    }
  }
}
```

## 📚 Documentation

| Document | Purpose |
|----------|---------|
| [SETUP_INSTRUCTIONS.md](SETUP_INSTRUCTIONS.md) | Detailed setup guide |
| [DEMO_TOOLS_SPEC.md](DEMO_TOOLS_SPEC.md) | Complete tool specifications |
| [SOC_PLAYBOOKS.md](SOC_PLAYBOOKS.md) | Investigation workflow examples |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development guidelines |
| [DEMO_TESTING_GUIDE.md](DEMO_TESTING_GUIDE.md) | Testing procedures |

## 🏗️ Architecture

```
Claude Desktop / MCP Client
    │
    ├── Splunk MCP Server (this project)
    │   ├── SOC Investigation Tools
    │   ├── Label Harvesting
    │   └── Splunk SDK Integration
    │
    └── DeepTempo MCP Server (separate)
        ├── Embedding Similarity Search
        ├── MITRE ATT&CK Mapping
        └── LogLM Analysis
```

## 🔐 Security Considerations

### Current Implementation
- ✅ SSL/TLS support with configurable verification
- ✅ Token-based and credential-based authentication
- ✅ Environment variable configuration
- ✅ Input validation on all tools
- ✅ Audit logging support

### Best Practices
- Never commit `.env` files
- Use `VERIFY_SSL=true` in production
- Rotate credentials regularly
- Monitor audit logs
- Use least-privilege Splunk accounts

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📝 Credits

This project is built upon [livehybrid/splunk-mcp](https://github.com/livehybrid/splunk-mcp) v0.3.0 and extends it with:
- SOC-specific investigation tools
- Label harvesting capabilities
- DeepTempo integration support
- Enhanced security controls

### Dependencies
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [Splunk SDK for Python](https://github.com/splunk/splunk-sdk-python) - Splunk API client
- [python-decouple](https://github.com/henriquebastos/python-decouple) - Configuration management

## 📄 License

Apache License 2.0 - See [LICENSE](LICENSE) for details.

## 🐛 Troubleshooting

### Connection Issues
```bash
# Test Splunk connectivity
python test_connection.py

# Check logs
tail -f splunk_mcp.log
```

### No Data in Splunk
```bash
# Ingest test data
python ingest_test_data.py your-password

# Verify in Splunk UI
index=mcp_demo | stats count by event_type
```

### MCP Server Won't Start
- Verify `.env` file exists with correct values
- Check Python version (3.10+ required)
- Ensure Splunk is accessible
- Review error logs

## 📞 Support

For issues and questions:
1. Check [documentation](SETUP_INSTRUCTIONS.md)
2. Review [error logs](splunk_mcp.log)
3. Open an issue on GitHub

---

**Built with FastMCP for AI-native security operations** 🚀