A next-generation Model Context Protocol (MCP) server that hunts for behaviors, not indicators. Built on the philosophy that effective threat hunting focuses on adversary Tactics, Techniques, and Procedures (TTPs) at the top of the Pyramid of Pain—the behaviors that are hardest for attackers to change.
This MCP server is designed around a core principle from the Pyramid of Pain:
▲
╱ ╲
╱ ╲ 🎯 TOUGH
╱ TTPs╲ ← WE FOCUS HERE
╱———————╲
╱ ╲
╱ 🛠️ Tools ╲
╱—————————————╲
╱ ╲
╱ 📊 Host/Network ╲
╱———————————————————╲
╱ ╲
╱ 🌐 Domain Names ╲
╱—————————————————————————╲
╱ ╲
╱ 🔢 IP Addresses ╲
╱———————————————————————————————╲
╱ ╲
╱ #️⃣ Hash Values ╲
╱—————————————————————————————————————╲
Why behavioral hunting?
- Hash values → Adversaries change in seconds
- IP addresses → Adversaries change in minutes
- Domain names → Adversaries change in hours
- Network/Host artifacts → Adversaries change in days
- Tools → Adversaries change in weeks
- TTPs (Behaviors) → Adversaries change in months/years ✅ Hunt for these!
When you hunt for how adversaries behave rather than what specific indicators they use, you create durable detections that survive indicator rotation and force adversaries to fundamentally change their operations.
- TTP-First Approach: All hunts prioritize behavioral patterns over atomic indicators
- MITRE ATT&CK Integration: Deep integration with technique-level behavioral analytics
- Behavior Pattern Library: Pre-built detection logic for common adversary behaviors
- Anti-Evasion Design: Hunt for behaviors that persist across tool/infrastructure changes
- PEAK Methodology: Prepare, Execute, Act with Knowledge - state-of-the-art framework
- SQRRL Framework: Hunting Maturity Model (HMM0-HMM4) progression
- TaHiTI Framework ⭐ NEW: Targeted Hunting integrating Threat Intelligence (3 phases, 6 steps)
- Intelligence-Driven: Hypothesis-driven hunting using behavioral threat intelligence
- Bias Awareness Checks: Heuristic prompts for confirmation, anchoring, and availability biases (rule-based, not ML — intended as analyst checklists, not automated judgment)
- Competing Hypotheses Generator: Generates benign / insider / external / supply-chain alternatives so ACH (Analysis of Competing Hypotheses) is forced before commitment
- Pyramid-of-Pain-weighted Confidence: TTP-level evidence anchors the score; lower-pyramid indicators (hashes, IPs) only add supplemental context and cannot dilute it
- Hunt Stopping Criteria: Coverage / diminishing-returns / time / confidence thresholds to prevent tunnel vision
- Investigation Question Generator: Standard skeptical prompts ("what would disprove this?", "what's missing?") to ensure thorough analysis
- Attack Path Analysis: Identifies critical paths from initial compromise to crown jewels (domain controllers, databases, admin accounts)
- Living-off-the-Land Detection: Behavioral detection of LOLBin abuse via parent-child relationships and command-line patterns
- Pivot Point Identification: Brandes betweenness centrality (via NetworkX) over the attack graph; falls back to BFS shortest-path scoring if NetworkX is unavailable
- Provenance Tracking: Data lineage and ancestry chains for forensic context
- Lateral-Movement & Credential-Access Edge Tagging: SMB/RDP/WinRM connections and lsass-targeted process access are tagged at graph-build time so MITRE TTP extraction (T1021, T1003) works on real path traversals
- Honeytoken Generation: Fake AWS keys, passwords, SSH keys, API tokens with embedded callback markers
- Strategic Placement Helpers: Suggested locations — browser history, .env files, config files, memory dumps
- Decoy System Templates: Configurable fake servers, workstations, databases
- Canary File Generation: Executive documents, credentials, source code with embedded beacons
- Trigger-Based Detection: Designed for high-signal, low-noise alerting — actual signal-to-noise ratio depends on telemetry wiring in your environment
- HEARTH Integration: Access 50+ community-curated threat hunting hypotheses
- Hypothesis-Driven Hunts (Flames): Real-world attack scenarios from practitioners
- Baseline Hunts (Embers): Environmental baselining and exploratory analysis
- Model-Assisted Hunts (Alchemy): ML and algorithmic detection approaches
- AI-Powered Recommendations: Personalized hunt suggestions for your environment
- Tactic Coverage Analysis: Identify gaps across MITRE ATT&CK tactics
- Incident-Based Suggestions: Get relevant hunts based on incident descriptions
- Natural Language Processing: Convert behavioral hunt requests into executable queries (requires
spacy— gracefully disabled if absent) - Atlassian Integration: Confluence and Jira for knowledge management (optional)
- Splunk Integration: TTP-focused hunting queries via the Splunk SDK; connection is lazy (server boots even if Splunk is unreachable) and the entire integration is gated so the module imports without
splunk-sdk/numpy/pandas/sklearninstalled - MITRE ATT&CK Framework: Technique and sub-technique mapping with behavioral hunt queries (Sysmon EID 10 for T1003, behavioral cmd.exe/PowerShell discovery for T1083, etc.)
- Security Controls: JWT auth, encryption, audit logging, rate limiting
- Caching & Performance: Redis-based caching (optional)
✅ Good: Behavioral Patterns (TTPs)
- Process injection techniques (T1055.*) - behavior persists across tools
- LSASS memory access patterns - fundamental credential theft behavior
- Lateral movement via remote services - core post-compromise behavior
- Living-off-the-Land binaries (LOLBins) - detection-evasion behavior
- Parent-child process anomalies - execution pattern behaviors
- Kerberoasting patterns - Active Directory attack behaviors
❌ Avoid: Atomic Indicators (Easy to Change)
- Specific malware hashes - trivial to modify
- Known-bad IP addresses - adversaries rotate rapidly
- C2 domain names - disposable infrastructure
- Specific file paths - easily changed
Example 1: Credential Access Behavior
Hunt for: Any process accessing LSASS memory (T1003.001)
Why: This behavior is required for credential theft, regardless of the tool
Tools that use it: Mimikatz, ProcDump, custom malware
Detection persists: Even when tools change
Example 2: Lateral Movement Behavior
Hunt for: Remote execution patterns via WMI/DCOM/SMB (T1021.*)
Why: Fundamental behavior for spreading through networks
Tools that use it: PsExec, Impacket, WMIC, custom tools
Detection persists: Even with infrastructure/tool rotation
Example 3: Defense Evasion Behavior
Hunt for: Process injection patterns (T1055.*)
Why: Core evasion technique requiring specific OS API calls
Tools that use it: Cobalt Strike, Metasploit, custom loaders
Detection persists: API call patterns remain consistent
New to behavioral hunting? Start with these resources:
- Quick Reference Card - One-page behavioral hunting cheat sheet
- Behavioral Hunting Guide - Complete guide to hunting behaviors vs indicators
- PEAK Hunt Example - Complete example hunt report using PEAK Framework
- HEARTH Community Hunts - 50+ real-world behavioral hunt hypotheses
- PEAK Template - Official PEAK Framework template from THOR Collective
Try these natural language queries focused on behaviors:
# Credential Access Behaviors
"Hunt for any process accessing LSASS memory (T1003.001)"
"Find credential dumping patterns regardless of tool used"
# Lateral Movement Behaviors
"Detect lateral movement via remote execution (T1021.*)"
"Hunt for RDP/WMI/PsExec execution patterns"
# Process Injection Behaviors
"Find process injection into system processes (T1055)"
"Detect CreateRemoteThread patterns across all tools"
# Living-off-the-Land Behaviors
"Hunt for PowerShell download cradles (T1059.001)"
"Detect LOLBin abuse patterns (certutil, bitsadmin, etc.)"
# Command and Control Behaviors
"Find C2 beaconing patterns regardless of infrastructure"
"Detect DNS tunneling behaviors (T1071.004)"Notice: These focus on adversary behaviors that persist across tool/infrastructure changes, not specific IOCs that change hourly.
-
Hunt Frameworks
- PEAK/SQRRL (src/frameworks/hunt_framework.py)
- PEAK methodology implementation
- SQRRL framework components
- Intelligence-driven hunting approach
- TaHiTI (src/frameworks/tahiti.py) ⭐ NEW
- 3-phase methodology (Initialize, Hunt, Finalize)
- 6-step process with continuous threat intelligence integration
- Hunt backlog management and prioritization
- Automated handover to security processes
- PEAK/SQRRL (src/frameworks/hunt_framework.py)
-
Cognitive Module (src/cognitive/hunter_brain.py) ⭐ NEW
- Heuristic checks for confirmation, anchoring, and availability biases (rule-based; not an LLM judge)
- Competing hypotheses generator — synthesizes benign / insider / external / supply-chain alternatives for ACH
- Pyramid-of-Pain-anchored confidence scoring (high-pyramid evidence dominates; low-pyramid evidence cannot dilute)
- Hunt stopping criteria (coverage, diminishing returns, time, confidence)
- Investigation question generator
-
Graph Correlation Engine (src/correlation/graph_engine.py) ⭐ NEW
- Attack graph construction with role promotion (hosts →
domain_controller/database, users →admin_account) so high-value targets are actually identifiable - Living-off-the-Land (LOLBin) detection via parent-child anomalies, suspicious command lines, and chained execution
- Attack path identification with configurable high-value target types
- Pivot point detection via Brandes betweenness centrality (NetworkX); BFS shortest-path fallback when NetworkX is missing
- Provenance tracking and ancestry analysis
- Lateral-movement / credential-access edge tagging based on ports, services, and lsass-targeted ProcessAccess
- Attack graph construction with role promotion (hosts →
-
Deception Manager (src/deception/honeytokens.py) ⭐ NEW
- Honeytoken generation and deployment
- Decoy system management
- Canary file deployment
- High-confidence threat detection
- Deception trigger monitoring and response
-
Integrations
- Atlassian (src/integrations/atlassian.py): Confluence/Jira integration (optional)
- Splunk (src/integrations/splunk.py): Query execution and optional ML analysis (Isolation Forest, DBSCAN, time-series anomaly). Connection is lazy and the entire integration imports cleanly without
splunk-sdk/numpy/pandas/sklearn— features are gated and self-report unavailability when deps are missing.
-
Intelligence Engine
- MITRE ATT&CK (src/intelligence/threat_intel.py)
- MITRE ATT&CK framework
- Pyramid of Pain implementation
- Diamond Model analysis
- Cyber Kill Chain mapping
- HEARTH Integration (src/intelligence/hearth_integration.py) ⭐ NEW
- Community hunt repository access
- Hunt search and recommendation engine
- Tactic coverage analysis
- Incident-based hunt suggestions
- 50+ curated threat hunting hypotheses
- THOR Collective (src/intelligence/thor_collective.py)
- Community threat hunting knowledge
- THRF (Threat Hunting Relevancy Factors)
- Thrunting philosophy integration
- MITRE ATT&CK (src/intelligence/threat_intel.py)
-
NLP Processing (src/nlp/hunt_nlp.py)
- Natural language query processing
- Intent classification
- Entity extraction
- Query generation
- Integration with cognitive capabilities
-
Security Manager (src/security/security_manager.py)
- JWT authentication
- Data encryption
- Audit logging
- Rate limiting
The fastest way to get started with community hunt knowledge:
-
Clone repositories:
git clone https://github.com/THORCollective/threat-hunting-mcp-server cd threat-hunting-mcp-server # Clone HEARTH repository (required for community hunts) git clone https://github.com/THORCollective/HEARTH ../HEARTH
-
Install dependencies:
pip install -r requirements.txt
-
Configure environment (minimal setup):
cp .env.example .env # The .env file is already configured with HEARTH_PATH # You can use it as-is for HEARTH features
-
Connect to Claude Code:
Add to your Claude Code settings (
.claude/config.jsonor settings UI):{ "mcpServers": { "threat-hunting": { "command": "python3", "args": ["-u", "/path/to/threat_hunting_mcp/run_server.py"] } } } -
Start using it:
Open Claude Code and try natural language queries:
- "Show me HEARTH hunts for credential access"
- "Recommend threat hunts for my Windows AD environment"
- "What's the tactic coverage in HEARTH?"
For production deployment features including health monitoring, testing, optimization, and structured logging, see PRODUCTION.md.
Production Features:
- 🏥 Health monitoring with
get_server_health()MCP tool - 🛡️ Input validation and security (Pydantic models)
- ⚡ Token optimization (40-50% reduction)
- ✅ Automated testing (63 tests, 100% pass rate — covers validators, HEARTH integration, server health, splunk query content, graph correlation, and pyramid-of-pain weighting)
- 📊 Structured JSON logging to stderr
- 🔄 Graceful degradation for optional features (Splunk SDK, NumPy/Pandas/scikit-learn, NetworkX, spaCy, Redis are all gated — server boots and degrades cleanly when any are absent)
For complete functionality including Splunk, Atlassian, and ML features:
-
Clone the repository:
git clone https://github.com/THORCollective/threat-hunting-mcp-server cd threat-hunting-mcp-server -
Install base dependencies:
pip install -r requirements.txt
-
Install optional components as needed (all are gated — the server runs without them and reports unavailability via
get_server_health()):# Splunk live querying: pip install splunk-sdk # Math / M-ATH (Isolation Forest, DBSCAN, time-series anomaly): pip install numpy pandas scikit-learn # NLP (natural-language hunt query parsing): pip install spacy python -m spacy download en_core_web_lg
-
Configure environment:
cp .env.example .env # Edit .env with your Splunk/Atlassian credentials
Python version: tested on 3.11–3.13. The optional ML stack pins are kept out of the default
requirements.txtso a fresh install on Python 3.13 doesn't fail on transient compatibility issues — uncomment those lines inrequirements.txt(or install manually as above) when you need them.
Copy .env.example to .env and configure required integrations: Atlassian (URL, username, API token) • Splunk (host, port, auth token) • Security (JWT secret, encryption key) • Redis (connection details, optional).
See PRODUCTION.md for detailed configuration examples, security hardening, and deployment best practices.
python -m src.serverCore Hunting Tools:
hunt_threats(query, framework)- Natural language threat hunting interfaceget_server_health()- Server diagnostics and feature availabilityanalyze_adversary(adversary_id)- Threat actor analysis (e.g., G0016 for APT29)
HEARTH Community Tools:
search_community_hunts(tactic, tags, keyword)- Search 50+ community hunt hypothesesrecommend_hunts(tactics, keywords, environment)- AI-powered hunt recommendationssuggest_hunts_for_incident(description)- Incident-driven hunt suggestions
PEAK Framework Tools:
create_behavioral_hunt(technique_id, hypothesis, ...)- Create PEAK hunt reportssuggest_behavioral_hunt_from_ioc(ioc, ioc_type)- Pivot IOCs to behavioral huntslist_peak_hunts()- List created hunt reports
20+ additional tools available - see full API documentation for complete tool reference with examples.
# Search for credential access hunts
hunts = await search_community_hunts(
tactic="Credential Access",
tags=["lateral_movement"],
limit=5
)# Pivot from IOC to behavioral detection
behavioral_hunt = await suggest_behavioral_hunt_from_ioc(
ioc="192.168.1.100",
ioc_type="ip"
)
# Returns TTP-focused hunt suggestions instead of IOC-based detectionDeveloped by the Dutch Payments Association, TaHiTI (Targeted Hunting integrating Threat Intelligence) provides a standardized methodology combining threat intelligence with hunting practices. The framework features three phases: Initialize (trigger and abstract), Hunt (hypothesis and investigation), and Finalize (validation and handover). Built on intelligence-driven focus with continuous enrichment, risk-based prioritization, and collaborative information sharing.
Simple, practical framework with three phases: Prepare (research and hypotheses), Execute (analyze and investigate), Act with Knowledge (document and detect). Supports three hunt types: Hypothesis-Driven, Baseline, and Model-Assisted (M-ATH).
Features a Hunting Maturity Model (HMM0-HMM4), Hunt Loop (Hypothesis → Investigate → Patterns → Analytics), and Hunt Matrix mapping activities to maturity levels.
See FRAMEWORKS.md for detailed framework documentation, examples, and implementation guidance.
Integrates with HEARTH (Hunting Exchange and Research Threat Hub), an open-source repository of 50+ professionally-curated threat hunting hypotheses. HEARTH uses PEAK framework categories: 🔥 Flames (hypothesis-driven), 🪵 Embers (baseline), 🔮 Alchemy (model-assisted).
Key Features: Search by tactic/technique/tags • AI-powered hunt recommendations • Tactic coverage analysis • Incident-driven hunt suggestions • Real-time community updates
Quick Example:
hunts = await search_community_hunts(tactic="Credential Access", tags=["brute_force"])
recommendations = await recommend_hunts(environment="Windows AD")Resources: Live Database • GitHub Repo • Submit Hunts
Enterprise-grade security features including JWT authentication, AES encryption, comprehensive audit logging, and rate limiting. See SECURITY.md for complete security documentation, hardening guidelines, and responsible disclosure policy.
Key Features: JWT auth • AES encryption • Audit logging • Rate limiting • Input validation • SIEM integration
Contributions are welcome! See CONTRIBUTING.md for development guidelines, project structure, and how to add new features.
This project is licensed under the MIT License - see the LICENSE file for details.
This is a defensive security tool designed for:
- Threat hunting and detection
- Security monitoring and analysis
- Incident response and investigation
- Security research and education
By using this software, you agree to use it only for lawful and authorized security purposes. Always obtain proper authorization before conducting security activities in any environment.
For support and questions:
- Create GitHub issues for bugs
- Check documentation first
- Follow security disclosure policy
- Provide detailed reproduction steps
Note: This is a defensive security tool designed for threat hunting and detection. Use responsibly and in accordance with your organization's security policies.