Hoopshaker/thehive-fastmcp
GitHub: Hoopshaker/thehive-fastmcp
为自托管 TheHive 实例提供高性能 MCP 服务器，使 AI 代理能够安全地管理和查询安全事件工单、告警、IoC 及任务。
Stars: 0 | Forks: 0
# TheHive MCP Server (FastMCP)
本仓库包含一个用于 **TheHive**（安全事件响应与编排平台）的通用且高性能的 MCP (Model Context Protocol) 服务器。
它允许 AI 代理或安全助手（如 Claude Desktop 或其他 MCP 网关）安全地操作和查询 TheHive 中的 **Cases**、**Alerts**、**Observables** (IoCs) 和 **Tasks**。
## ⚙️ 配置
该服务器完全依赖环境变量进行配置：
| 变量 | 描述 | 必需 | 默认值 |
| :--- | :--- | :--- | :--- |
| `THEHIVE_URL` | 您的 TheHive 实例的基础 URL（例如：`https://thehive.your-domain.com`）。 | **是** | - |
| `THEHIVE_API_KEY` | 用户的 API 密钥 (Bearer Token)。 | **是** | - |
| `THEHIVE_VERIFY_SSL` | 启用或禁用 SSL 证书验证。在自托管环境中非常有用。 | 否 | `true` |
| `THEHIVE_ORG` | 目标组织的名称（添加 `X-Organisation` header）。 | 否 | - |
## 🛠️ 使用 Docker
此 MCP 服务器会自动发布到 **GitHub Container Registry (GHCR)**。您可以直接使用它，而无需克隆源代码或自行构建镜像：Docker 会在首次启动时透明地下载一切所需内容。
### 1. 直接在命令行中运行
由于 MCP 协议通过标准输入/输出流 (`stdio`) 工作，您必须在交互模式 (`-i`) 下运行容器，并且不分配伪 TTY（不使用 `-t` 以避免使用 ANSI 转义字符污染流）：
```
docker run -i --rm \
-e THEHIVE_URL="https://thehive.votre-domaine.com" \
-e THEHIVE_API_KEY="VOTRE_CLE_API" \
-e THEHIVE_VERIFY_SSL="false" \
ghcr.io/hoopshaker/thehive-fastmcp:latest
```
### 2. 为 MCP 客户端配置 (Gemini / Claude Desktop)
要将此服务器自动连接到您的 MCP 客户端（如 Gemini MCP 扩展或 Claude Desktop），请将此配置添加到您的配置文件（`gemini-config.json` 或 `claude_desktop_config.json`）中：
```
{
"mcpServers": {
"thehive": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "THEHIVE_URL=https://thehive.votre-domaine.com",
"-e", "THEHIVE_API_KEY=VOTRE_CLE_API",
"-e", "THEHIVE_VERIFY_SSL=false",
"ghcr.io/hoopshaker/thehive-fastmcp:latest"
]
}
}
}
```
### 🔨 本地构建 (可选 / 开发)
如果您希望修改代码或在本地自行构建 Docker 镜像：
1. 从项目根目录开始，构建镜像：
docker build -t thehive-fastmcp .
2. 运行它，将 GHCR 引用替换为您本地的标签：
docker run -i --rm \
-e THEHIVE_URL="https://thehive.your-domain.com" \
-e THEHIVE_API_KEY="YOUR_API_KEY" \
thehive-fastmcp
## 🔧 暴露的工具 (Tools)
连接成功后，MCP 服务器将暴露以下工具：
### 📁 Cases (事件工单)
* `get_case(id_or_name)`：通过 ID（例如：`~1234`）或编号检索工单的完整详情。
* `create_case(title, description, severity, tags, tlp, pap, flag)`：创建一个新的事件工单。
* `search_cases(title, severity, tags, status, limit)`：根据多个条件搜索工单。
### 🚨 Alerts (安全警报)
* `get_alert(alert_id)`：检索警报的完整详情。
* `create_alert(type_name, source, source_ref, title, description, severity, tags, tlp, pap)`：创建来自 SIEM/EDR 的警报。
* `search_alerts(title, severity, tags, status, limit)`：搜索警报。
### 🔍 Observables (IoCs)
* `create_observable(case_id, data_type, data, message, tags, tlp, pap, ioc)`：向工单添加一个 observable（例如：IP、域名、hash）。
* `get_case_observables(case_id, limit)`：列出与工单关联的所有 observable。
### 📋 Tasks & Logs (调查任务)
* `create_task(case_id, title, description, group, assignee)`：在事件工单中添加一个待办任务。
* `get_case_tasks(case_id, limit)`：列出工单中的任务。
* `add_task_log(task_id, message)`：向任务添加进度说明或文本报告。
## 💻 本地开发（不使用 Docker）
如果您希望使用 `uv` 在本地运行或调试服务器：
1. 如果尚未安装，请先安装 `uv`。
2. 创建一个虚拟环境并安装依赖项：
uv sync
3. 导出您的环境变量：
export THEHIVE_URL="https://..."
export THEHIVE_API_KEY="..."
export THEHIVE_VERIFY_SSL="false"
4. 启动 MCP 服务器：
uv run python -m thehive_mcp.server
## 🧨 手动测试 JSON-RPC 协议 (Handshake)
由于 MCP 协议通过标准输入 (`stdin`) 上的 **JSON-RPC 2.0** 消息进行通信，您可以直接在终端中输入 MCP 握手的初始化消息，从而手动测试服务器。
### 第 1 步：启动初始化
服务器启动后，输入以下 JSON-RPC 初始化请求并按 **回车键 (Enter)**：
```
{"jsonrpc": "2.0", "id": 0, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}
```
*服务器将返回一个包含其元数据及其能力的 JSON 数据块。*
### 第 2 步：确认初始化 (Notification)
然后发送此通知（不带 `id`）以完成握手：
```
{"jsonrpc": "2.0", "method": "notifications/initialized"}
```
*服务器现已初始化，并准备好接收命令。*
### 第 3 步：列出可用工具
您现在可以查询工具列表：
```
{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
```
*服务器将返回以 JSON 格式描述的完整 TheHive 工具列表（`get_case`、`create_case` 等）。*
标签：AI智能体, CIDR查询, DLL 劫持, Docker, MCP服务, TheHive, 大语言模型, 安全运营, 安全防御评估, 扫描框架, 请求拦截, 逆向工具