Splunk For SOC Operations

Python 3.10+ License 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 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:

   git clone https://github.com/mando222/splunk-mcp-soc.git
   cd splunk-mcp-soc
   

2. Install dependencies:

   Using pip (recommended):

   pip install -r requirements.txt
   

   Or with UV:

   uv sync
   

   Or with Poetry:

   poetry install
   

3. Configure environment variables:

   Create a .env file:

   SPLUNK_HOST=localhost
   SPLUNK_PORT=8089
   SPLUNK_USERNAME=admin
   SPLUNK_PASSWORD=your-password
   SPLUNK_SCHEME=https
   VERIFY_SSL=false
   

4. Test the connection:

   python test_connection.py
   

5. Run the MCP server:

   # 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:

# 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:

pytest tests/

🐳 Docker Support

Run with Docker Compose

1. SSE Mode (default):

docker compose up -d mcp

2. API Mode:

docker compose run --rm mcp python splunk_mcp.py api

3. STDIO Mode:

docker compose run -i --rm mcp python splunk_mcp.py stdio

Run Tests in Docker

./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):

{
  "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	Detailed setup guide
DEMO_TOOLS_SPEC.md	Complete tool specifications
SOC_PLAYBOOKS.md	Investigation workflow examples
CONTRIBUTING.md	Development guidelines
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 for guidelines.

📝 Credits

This project is built upon 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 - MCP server framework
• Splunk SDK for Python - Splunk API client
• python-decouple - Configuration management

📄 License

Apache License 2.0 - See LICENSE for details.

🐛 Troubleshooting

Connection Issues

# Test Splunk connectivity
python test_connection.py

# Check logs
tail -f splunk_mcp.log

No Data in Splunk

# 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
2. Review error logs
3. Open an issue on GitHub

---

Built with FastMCP for AI-native security operations 🚀