threat-hunting-mcp-server - A minimal, modular MCP server that equips your AI

项目说明

Threat Hunting MCP Server

A next-generation Model Context Protocol (MCP) server that hunts for behaviors, not indicators. Built on the philosophy that effecti hunting focuses on ad Tactics, Techniques, and Procedures (TTPs) at the top of the Pyramid of Pain—the behaviors that are hardest for attackers to change.

Philosophy: Hunt Behaviors, Not Indicators

This MCP server is designed around a core principle from the Pyramid of Pain:

Why beha hunting?

When you hunt for *how* ad beha than *what* specific indicators they use, you create durable detections that survi rotation and force ad to fundamentally change their operations.

Features

Beha Hunting Focus

Core Hunting Frameworks

Ad Cogniti ⭐ NEW

Graph-Based Threat Detection ⭐ NEW

Deception Technology Integration ⭐ NEW

Community Knowledge Base ⭐ NEW

Traditional Capabilities

Beha Hunting Examples

What We Hunt For (Top of Pyramid)

✅ Good: Beha Patterns (TTPs)

❌ Avoid: Atomic Indicators (Easy to Change)

Beha Hunt Examples

Example 1: Credential Access Behavior

Example 2: Lateral Mo Behavior

Example 3: Defense E Behavior

Getting Started with Beha Hunting

New to beha hunting? Start with these resources:

1. Quick Reference Card - One-page beha hunting cheat sheet
2. Beha Hunting Guide - Complete guide to hunting behaviors
3. PEAK Hunt Example - Complete example hunt report using PEAK Framework
4. HEARTH Community Hunts - 50+ real-world beha hunt hypotheses
5. PEAK Template - Official PEAK Framework template from THOR Collective

Quick Beha Hunt Examples

Try these natural language queries focused on behaviors:

Notice: These focus on ad behaviors that persist across tool/infrastructure changes, not specific IOCs that change hourly.

---

Architecture

Core Components

1. Hunt Frameworks
- PEAK/SQRRL (src/frameworks/hunt_framework.py)
- PEAK methodology implementation
- SQRRL framework components
- Intelligence-dri 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

2. Cogniti (src/cogniti.py) ⭐ NEW
- Heuristic checks for confirmation, anchoring, and a 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 e dominates; low-pyramid e cannot dilute)
- Hunt stopping criteria (co, diminishing returns, time, confidence)
- In question generator

3. 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
- Li (LOLBin) detection anomalies, suspicious command lines, and chained execution
- Attack path identification with configurable high-value target types
- Pi detection betweenness centrality (NetworkX); BFS shortest-path fallback when NetworkX is missing
- Pro tracking and ancestry analysis
- Lateral-mo / credential-access edge tagging based on ports, services, and lsass-targeted ProcessAccess

4. 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

5. 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 una when deps are missing.

6. 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 co 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

7. NLP Processing (src/nlp/hunt_nlp.py)
- Natural language query processing
- Intent classification
- Entity extraction
- Query generation
- Integration with cogniti

8. Security Manager (src/security/security_manager.py)
- JWT authentication
- Data encryption
- Audit logging
- Rate limiting

Quick Start (HEARTH Integration Only)

The fastest way to get started with community hunt knowledge:

1. Clone repositories:

2. Install dependencies:

3. Configure en (minimal setup):

4. Connect to Claude Code:

Add to your Claude Code settings (.claude/config.json or settings UI):

5. 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 en"
- "What's the tactic co in HEARTH?"

Production Deployment

For production deployment features including health monitoring, testing, optimization, and structured logging, see PRODUCTION.md.

Production Features:

Full Installation

For complete functionality including Splunk, Atlassian, and ML features:

1. Clone the repository:

2. Install base dependencies:

3. Install optional components as needed (all are gated — the server runs without them and reports una via get_ser()):

4. Configure en:

> Python : tested on 3.11–3.13. The optional ML stack pins are kept out of the default requirements.txt so a fresh install on Python 3.13 doesn't fail on transient compatibility issues — uncomment those lines in requirements.txt (or install manually as above) when you need them.

Configuration

Copy .en 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.

Usage

Starting the Server

Key MCP Tools

Core Hunting Tools:

HEARTH Community Tools:

PEAK Framework Tools:

20+ additional tools a - see full API documentation for complete tool reference with examples.

Example: Search Community Hunts

Example: Create Beha Hunt

Hunting Methodologies

TaHiTI Framework ⭐ NEW

De 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 in), and Finalize ( and handover). Built on intelligence-dri with continuous enrichment, risk-based prioritization, and collaborati sharing.

PEAK Framework

Simple, practical framework with three phases: Prepare (research and hypotheses), Execute (analyze and in), Act with Knowledge (document and detect). Supports three hunt types: Hypothesis-Driven, Baseline, and Model-Assisted (M-ATH).

SQRRL Framework

Features a Hunting Maturity Model (HMM0-HMM4), Hunt Loop (Hypothesis → In → Patterns → Analytics), and Hunt Matrix mapping acti to maturity levels.

See FRAMEWORKS.md for detailed framework documentation, examples, and implementation guidance.

HEARTH Community Integration ⭐ NEW

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 co analysis • Incident-driven hunt suggestions • Real-time community updates

Quick Example:

Resources: Li • GitHub Repo • Submit Hunts

Security

Enterprise-grade security features including JWT authentication, AES encryption, comprehensi 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 • SIEM integration

Contributing

Contributions are welcome! See CONTRIBUTING.md for de guidelines, project structure, and how to add new features.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Responsible Use

This is a defensi tool designed for:

By using this software, you agree to use it only for lawful and authorized security purposes. Always obtain proper authorization before conducting security acti in any en.

Support

For support and questions:

---

Note: This is a defensi tool designed for threat hunting and detection. Use responsibly and in accordance with your organization's security policies.

项目信息

开发语言：Python

Star 数：20

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A minimal, modular MCP server that equips your AI with practical capabilities for real-world threat hunting workflows.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。