indranilroy99/misp-mcp

用自然语言询问威胁指标，并从 MISP 获取答案。

misp-mcp 将 MISP 连接到任何 [MCP](https://modelcontextprotocol.io) 客户端 （Claude Desktop, Claude Code, Cursor 等）。您只需用自然语言提问， 客户端就会调用 MISP，然后您就能得到答案。无需 MISP UI，也无需手动发起 REST 调用。 包含八个用于读取 MISP 数据的工具和两个用于添加指标（单个+批量）的工具，所有操作都在您自己的 MISP 密钥下进行。 ## 连接到托管服务器 ### 1. 获取您的 MISP 密钥（仅一次） 1. 打开 `https://misp.example.com` 并登录。 2. 右上角菜单 → **My Profile -> Auth Keys -> Add authentication key**。 3. 添加备注 `misp-mcp `，然后**复制密钥** - MISP 只会显示一次。 对于查询操作，只读密钥就足够了。 请妥善保管密钥 - 每次查询都*以您的身份*运行。 ### 2. 连接您的 MCP 客户端 这是一个基于流式 HTTP 的标准远程 MCP 服务器，因此任何支持 MCP 的 客户端都可以工作 - Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, Zed, VS Code (Copilot/MCP), Goose 等。无论是哪种客户端，都需要以下 三个相同的配置： 1. 传输方式：**HTTP**（流式 HTTP / 远程 MCP） 2. URL：`https://misp.example.com/mcp` 3. 两个标头：`X-MISP-Key: YOUR_KEY_HERE` 和 `X-MISP-User: you@example.com` **通用配置** - 大多数客户端会读取类似这样的 JSON 块（键名 因客户端而略有不同 - `mcpServers`, `servers` 或 `mcp.servers`；请查阅您的 客户端文档，但值是相同的）： ``` { "mcpServers": { "misp": { "type": "http", "url": "https://misp.example.com/mcp", "headers": { "X-MISP-Key": "YOUR_KEY_HERE", "X-MISP-User": "you@example.com" } } } } ```

各客户端示例

**Claude Code**（在终端中运行一条命令）： ``` claude mcp add --transport http misp https://misp.example.com/mcp \ --scope user \ --header "X-MISP-Key: YOUR_KEY_HERE" \ --header "X-MISP-User: you@example.com" ``` **Claude Desktop / Cursor / Windsurf** - 将上面的通用 `mcpServers` 块 添加到客户端的 MCP JSON 配置中，然后完全重启应用程序。 **VS Code (Copilot MCP)** - 在 `.vscode/mcp.json` 或用户设置中的 `"servers"` 下： ``` { "servers": { "misp": { "type": "http", "url": "https://misp.example.com/mcp", "headers": { "X-MISP-Key": "YOUR_KEY_HERE", "X-MISP-User": "you@example.com" } } } } ``` **Cline / Continue / Zed / Goose 及其他客户端** - 在各自客户端使用的任何配置格式中，使用相同的 URL， `http` 传输方式以及这两个标头。任何支持通过 HTTP 进行远程 MCP 通信并且可以发送自定义标头的客户端 都可以工作；这两个 `X-MISP-*` 标头是唯一与服务器特定相关的部分。 不支持任何无法发送自定义 HTTP 标头的客户端（因为密钥必须 包含在 `X-MISP-Key` 中）。

### 3. 检查是否正常工作 可达性检查（与客户端无关） - 应该打印 `401`，这证明您可以 访问该 endpoint 并且需要身份验证： ``` curl -s -o /dev/null -w '%{http_code}\n' -X POST https://misp.example.com/mcp ``` 如果您的客户端有列出 MCP 服务器的功能，请确认 `misp` 显示为已连接 （Claude Code：`claude mcp list` → `misp ... ✓ Connected`；其他客户端在 其 MCP/工具面板中显示）。 然后向您的助手提问以下内容 - 如果它们从 MISP 返回答案，就说明配置好了： | 提问内容 | 您应该得到的结果 | |---|---| | `Is MISP healthy?` | 可达，MISP + 服务器版本 | | `Look up 102.130.113.9 in MISP.` | 命中（Tor / DDoS），标记为检测 | | `Look up 45.9.148.99 in MISP.` | “未在 MISP 中发现”（而不是“安全”） | | `Triage these against MISP: 8.8.8.8, evil.com, ` | 针对每个指标的判定结果 | **不工作？** - 询问时出现 401 / 超时 → 您不在您的网络/VPN 中。 - `claude mcp list` 未显示“Connected” → 重新检查密钥和标头。 - 工具丢失、过时，或者助手说“no such tool” → **重新连接**（见下文）。 ### 重新连接 / 重启 MCP 客户端在连接时会缓存工具列表。如果服务器停止 响应、显示错误的工具或已更新，每个客户端的解决方法 都是一样的：**完全退出并重新打开应用程序**（不仅仅是对话或 窗口 - 应用内的 `/mcp` 重新连接或开启新聊天通常是不够的）。如果工具 仍然过时，请从配置中移除 `misp` 服务器，保存，重新打开，将其 重新添加，然后再次重新打开。 在服务器上添加的新工具只有在此完全重启后才会出现。

Claude Code 重新注册

``` claude mcp remove misp claude mcp add --transport http misp https://misp.example.com/mcp \ --scope user \ --header "X-MISP-Key: YOUR_KEY_HERE" \ --header "X-MISP-User: you@example.com" ``` 然后完全退出 Claude Code 并重新打开。使用 `claude mcp list` 检查 → `misp ... ✓ Connected`，并且 `/mcp` 会显示当前的工具。

## 您可以询问的内容 ``` "Look up 102.130.113.9 in MISP." "Triage these 30 IOCs from the report." "What else showed up in the same event as evil[.]com?" "Review the last 30 days of IOC submissions - who added what." "Is MISP healthy? How many feeds are on?" ``` 在后台，客户端会调用某个工具并获取结构化的 JSON，例如对于 查询： ``` { "ioc": "102.130.113.9", "ioc_type": "ipv4", "total_hits": 6, "summary": { "seen_in_misp": true, "event_count": 6, "detection_flagged": true, "max_threat_level": "Medium", "restricted_hits": 0 }, "hits": [ { "event_id": "16989", "event_info": "Tor exit nodes feed", "attribute_type": "ip-dst", "value": "102.130.113.9", "to_ids": true, "restricted": false } ] } ``` ## 工具 | 工具 | | 功能 | |---|---|---| | `misp_lookup_ioc` | 读取 | 查询单个 IPv4/IPv6、域名、URL 或哈希的 Sighting，并给出判定结果 | | `misp_lookup_iocs` | 读取 | 在一次调用中对多个指标进行分类筛选 | | `misp_correlate_ioc` | 读取 | 查找同一事件中的其他指标，用于关联顺藤摸瓜 | | `misp_get_event` | 读取 | 获取单个事件：信息、标签、属性 | | `misp_search_events` | 读取 | 按标题、标签或日期搜索事件 | | `misp_feed_stats` | 读取 | 统计有多少个 feed 存在以及哪些处于开启状态 | | `misp_instance_status` | 读取 | 可达性 + 身份验证检查；当工具失效时首先运行此工具 | | `misp_review_submissions` | 读取 | 审计最近的提交：添加了什么内容、由谁添加、哪些被标记为检测 | | `misp_submit_ioc` | **写入** | 添加新的指标（需要具有写入权限的密钥） | | `misp_submit_iocs` | **写入** | 批量操作：验证 + 添加多个指标（先进行 dry-run 预览） | 以任何您拥有的格式粘贴指标 - 消除危险的格式（如 `1.2.3[.]4`， `hxxp://evil[.]com`）会被自动清理。私有/保留 IP 将被 拒绝（不可路由，无法识别外部威胁）。 ## 安全 - **您的密钥就是授权凭证。** MISP 在每次调用时都会对其进行检查，并将 操作归因于您。只读密钥无法写入；只有具有写入权限的密钥（ 安全团队）才能添加指标。 - **受保护的写入路径。** 提交操作受速率限制，知名 / 第一方 基础架构永远无法被提交，并且提交者是从 MISP 本身读取的 - 而不是由调用者设置的值（因此 `misp_review_submissions` 显示的是*实际上*添加每个 IOC 的人）。 - **MISP 内容是数据，而不是指令。** 不要在未经自行检查的情况下直接提交 从查询中获取的指标。 - **密钥保持私密。** 服务器上没有共享密钥；密钥通过 TLS 包含在标头中进行传输。日志永远不会包含密钥或 IOC 值。 ## 架构（托管） ``` MCP client (Claude / Cursor / …, on your network / VPN) │ │ HTTPS + header X-MISP-Key: ▼ Route 53 misp.example.com │ ▼ Application Load Balancer TLS termination · office/VPN CIDRs only │ ├─ path /mcp* ─────► misp-mcp (Docker container, :8080) ─┐ │ │ internal └─ everything else ──► MISP core (Docker, :443) ◄───────────┘ docker net, │ misp-mcp calls MISP ▼ with your key RDS (MySQL) misp-mcp and MISP run as separate containers on the same EC2 host. No shared key on the server - every request carries the caller's own MISP key, which MISP validates and attributes to that user. ``` - TLS 在 ALB 处终止；misp-mcp 在其背后的 `:8080` 端口上提供纯 HTTP 服务。 - ALB 仅将 `/mcp*` 路由到 misp-mcp；所有其他路径仍然指向 MISP，因此 MISP 不受影响。 - misp-mcp 通过内部 Docker 网络访问 MISP（无 hairpin 环回），并且不持有 任何自己的凭证。 ## 自行运行（本地或自托管） 大多数人直接使用上面的托管服务器即可。如果要运行您自己的： - **本地**（在您的 MCP 客户端，您自己的 MISP 中）：安装并添加 `misp-mcp` 二进制文件 - 请参阅 [ONBOARDING.md](ONBOARDING.md)。 - **为团队自托管**（TLS 背后的 HTTP 服务器）：[DEPLOY.md](DEPLOY.md)。 - **在云上**（AWS / GCP / Azure）：[CLOUD.md](CLOUD.md)。 自动本地设置： ``` git clone https://github.com/indranilroy99/misp-mcp.git cd misp-mcp ./install.sh ```

所有设置

| 设置 | 模式 | 默认值 | 含义 | |---|---|---|---| | `MISP_URL` | 两者 | 必填 | MISP 基础 URL | | `MISP_API_KEY` | 本地 | 必填 | 您的密钥（本地模式） | | `MCP_TRANSPORT` | 两者 | `stdio` | 本地使用 `stdio`，托管使用 `http` | | `MCP_HOST` | 托管 | `127.0.0.1` | 绑定地址 | | `MCP_PORT` | 托管 | `8080` | 端口 | | `MISP_VERIFY_TLS` | 两者 | `true` | 仅针对自签名实验室设置为 `false` | | `MISP_MCP_SHOW_RESTRICTED` | 两者 | `true` | `false` 开启服务器端 TLP 隐藏 | | `MISP_SUBMISSION_EVENT_ID` | 两者 | 写入必填 | `misp_submit_ioc` 写入的目标事件 | | `MISP_MCP_PROTECTED_DOMAINS` | 两者 | 空 | 您自己的永远无法被提交的域名 | | `MISP_MCP_SUBMIT_RATE` | 两者 | `20` | 每个密钥每分钟的最大提交数 | | `MISP_MCP_TLS_CERT` / `MISP_MCP_TLS_KEY` | 托管 | 无 | 直接提供 HTTPS 服务 | | `MISP_MCP_ALLOW_INSECURE_BIND` | 托管 | `false` | 允许公共纯 HTTP 绑定（在代理上使用 TLS） |

开发

``` python3 -m venv .venv .venv/bin/pip install -e '.[dev]' .venv/bin/python -m pytest tests/ -q # 51 tests ``` ``` misp_mcp/ server.py the 10 tools and the MCP server client.py talks to the MISP REST API (read + write) config.py reads settings from the environment http_app.py hosted mode: header auth + web server context.py carries your identity through one request validators.py cleans, checks, and safelists indicators ``` 依赖项固定在 `pyproject.toml` 中：`mcp`, `httpx`, `pydantic`, `uvicorn`, `starlette`。

安全报告与许可

私下报告漏洞 - 请参阅 [SECURITY.md](SECURITY.md)。在 Apache-2.0 ([LICENSE](LICENSE)) 下授权。欢迎做出贡献 - 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。