Splunk Mcp Soc

Splunk MCP for SOC Operations

[](https://www.python.org/downloads/) [](LICENSE) [](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 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 ``

1. Install dependencies:

Using pip (recommended): ``bash pip install -r requirements.txt ``

Or with UV: ``bash uv sync ``

Or with Poetry: ``bash poetry install ``

1. 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 ``

1. Test the connection:

``bash python test_connection.py ``

1. 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
• getindexinfo - Get detailed information about a specific index
• indexesandsourcetypes - Comprehensive index and sourcetype mapping
• search_splunk - Execute Splunk search queries with time ranges
• listsavedsearches - View saved searches

KV Store Operations

• listkvstorecollections - List all KV store collections
• createkvstorecollection - Create new collections
• deletekvstorecollection - Remove collections

SOC Investigation Tools

• pivotbyip - Investigate all activity from a specific IP address
• findlateralmovement - Detect lateral movement patterns
• calculatedataexfiltration - Analyze and quantify data exfiltration
• buildattacktimeline - Construct chronological attack timelines
• correlatewithdeeptempo_finding - Cross-reference with DeepTempo findings

Threat Intelligence Integration

• enrichipwiththreatintel - 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
• checkiocreputation - Quick reputation check for any IOC (IP, domain, hash, URL)
• Auto-detects IOC type and provides actionable verdict
• addtothreat_list - Add confirmed IOCs to Splunk threat intelligence
• Supports expiration and automatic cleanup
• getmitreattack_context - Get detailed MITRE ATT&CK technique information
• Maps findings to tactics, techniques, and procedures
• Includes detection methods and mitigations

Automated Response Actions

• blockipaddress - 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
• createincidentticket - Auto-create tickets in ITSM platforms
• ServiceNow, Jira, or native Splunk incident tracking
• Automatic priority and SLA calculation
• sendalertnotification - 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
• identifyrareevents - Find statistically rare occurrences
• Detects new processes, domains, or behaviors
• Useful for zero-day and APT detection
• baselinenormalbehavior - 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
• getfieldsummary - Get detailed information about a specific field
• Deep dive into field values, distribution, and relationships
• Useful for understanding individual field usage
• exportlabelsto_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

1. API Mode:

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

1. 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 | |----------|---------| | [SETUPINSTRUCTIONS.md](SETUPINSTRUCTIONS.md) | Detailed setup guide | | [DEMOTOOLSSPEC.md](DEMOTOOLSSPEC.md) | Complete tool specifications | | [SOCPLAYBOOKS.md](SOCPLAYBOOKS.md) | Investigation workflow examples | | [CONTRIBUTING.md](CONTRIBUTING.md) | Development guidelines | | [DEMOTESTINGGUIDE.md](DEMOTESTINGGUIDE.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 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](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](SETUP_INSTRUCTIONS.md)
2. Review [error logs](splunk_mcp.log)
3. Open an issue on GitHub

---

Built with FastMCP for AI-native security operations 🚀

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DeepTempo
• Source: DeepTempo/splunk-mcp-soc
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.