hdyrawan/agentic-misp-mcp
GitHub: hdyrawan/agentic-misp-mcp
一个基于MCP协议的MISP威胁情报服务器，让AI agent在严格的只读优先和审批门控安全模型下进行IOC调查与受控写入。
Stars: 0 | Forks: 0
# agentic-misp-mcp
**面向 agent 的 MISP 工作流——在不将你的 MCP server 变成原始 API 代理的前提下，进行调查、扩展、报告以及提议受控写入。**
`agentic-misp-mcp` 是一个 MCP (Model Context Protocol) server，可让 AI agent 安全地处理 [MISP](https://www.misp-project.org/) 威胁情报。它没有暴露整个 MISP API，而是暴露了 **25 个有界、以分析师为导向的工作流**：搜索 IOC、调查其上下文、遍历相关指标、汇总事件、检查 warninglists、查看 feed 运行状况、生成报告，以及准备严格受控的写入提议。
其安全模型非常简单，并在代码中强制执行：
- **读取优先。** 每个调查工具都是只读的；默认禁用写入。
- **审批门控写入。** 这四个写入工具需要写入模式、允许的角色以及明确的审批步骤——在生产模式下，需要一次性的操作员批准请求 ID。
- **审计日志。** 每次工具调用（允许、阻止、失败或出错）都会被写入 JSONL 审计日志中，且参数已进行脱敏处理。
- **脱敏处理。** API key、approval token 和 feed 密钥永远不会出现在响应或日志中。
- **角色策略。** `read_only` / `analyst_write` / `curator` / `admin` 角色限制了任何 agent 会话能够尝试的操作范围。
**兼容性基准：** 已针对 **MISP `2.5.42`** 进行实时验证（最近一次是 `v0.3.0` 版本，14/14 项实时检查通过——参见 [`docs/live-validation-report-v0.3.0.md`](docs/live-validation-report-v0.3.0.md))。其他 MISP 版本未经测试；请参见 [`docs/misp-compatibility.md`](docs/misp-compatibility.md)。
## 这是为谁准备的？
- **SOC 分析师** — 让 agent 调查 IOC，并获得判定结果、置信度、时效性、相关事件以及下一步操作建议，而不是原始的 JSON 数据。
- **威胁情报分析师** — 从实时 MISP 数据中进行追踪、关联，并生成 Markdown/JSON 报告。
- **检测工程师** — 以有界、可预测的输出方式提取可操作的 (`to_ids`) 指标和事件上下文。
- **安全自动化团队** — 将 MISP 接入 agent 工作流，而无需为 agent 提供不受限制的 API key 接口。
- **受监管 / 银行业环境** — 每次调用都会被审计，写入需要带外操作员批准，且写入范围小而明确。
## 它能做什么？
| 工作流 | 涉及的工具 |
| --- | --- |
| IOC 调查 | `search_ioc`, `investigate_ioc`, `check_warninglists`, `pivot_ioc`, `find_related_iocs` |
| 事件搜索与上下文 | `search_events`, `summarize_event`, `explain_event_context`, `extract_event_iocs`, `find_events_by_tag` |
| 目击记录 | `get_ioc_sightings` (读取), `add_sighting_with_approval` (门控写入) |
| Warninglist 检查 | `check_warninglists`，以及 `investigate_ioc` 内部的自动检查 |
| Feed 可观测性（只读） | `list_feeds`, `get_feed_status`, `summarize_feed_health` |
| Markdown / JSON 报告 | `generate_ioc_report`, `generate_event_report`, `generate_markdown_ioc_report`, `generate_markdown_event_report` |
| 审批门控写入 | `submit_ioc_with_approval`, `add_sighting_with_approval`, `tag_event_with_approval`, `publish_event_with_approval` |
| 基于时效性的评分 / 陈旧情报标记 | `investigate_ioc`, `generate_ioc_report`, `pivot_ioc` — 详见 [评分行为](#scoring-behavior) |
## 25 个工具
访问级别：**只读**（从不写入 MISP）、**试运行**（构建可审查的 payload，从不调用 MISP 写入 endpoint）、**审批门控写入**（除非写入模式、角色和审批均允许，否则被阻止）。
### 调查与读取工具
| 工具 | 访问级别 | 功能描述 |
| --- | --- | --- |
| `search_ioc(value, limit)` | 只读 | 查找指标对应的规范化 MISP attribute 匹配项。 |
| `investigate_ioc(value, limit)` | 只读 | 提供判定、置信度、时效性、warninglists、相关事件和下一步操作。 |
| `pivot_ioc(value, limit)` | 只读 | 从一个 IOC 扩展追踪到相关上下文。 |
| `find_related_iocs(value, limit)` | 只读 | 对值得追踪的相关指标进行排名。 |
| `summarize_event(event_id)` | 只读 | 有界的事件摘要（绝非完整的原始事件 JSON）。 |
| `explain_event_context(event_id)` | 只读 | 解释一个事件所代表的含义。 |
| `extract_event_iocs(event_id, limit)` | 只读 | 从事件中提取受支持的 IOC 类型。 |
| `find_events_by_tag(tag, limit)` | 只读 | 查找与特定标签关联的事件。 |
| `search_events(date_from, date_to, published, org, limit)` | 只读 | 通过有界的日期/发布/组织过滤器发现事件。 |
| `get_ioc_sightings(value, limit)` | 只读 | 提供 IOC 的有界目击摘要。 |
| `check_warninglists(value)` | 只读 | 根据 MISP 的 warninglists 检查 IOC。 |
| `get_misp_status()` | 只读 | 查看 MISP 版本及 warninglist 能力状态。 |
### Feed 可观测性
| 工具 | 访问级别 | 功能描述 |
| --- | --- | --- |
| `list_feeds(limit, enabled)` | 只读 | 列出已配置的 feed，包含有界且**已脱敏**的元数据。 |
| `get_feed_status(feed_id)` | 只读 | 查看单个 feed 的脱敏状态及获取/缓存周期。 |
| `summarize_feed_health(limit)` | 只读 | 按运行状况标签（fresh/stale/never-fetched/disabled）对 feed 进行分组。 |
Feed 的启用/禁用/获取/缓存/编辑/删除仍然属于仅供操作员执行的 MISP 管理员操作，并且**不会**作为 MCP 工具暴露出来。请参阅 [`docs/feed-observability.md`](docs/feed-observability.md)。
### 报告
| 工具 | 访问级别 | 功能描述 |
| --- | --- | --- |
| `generate_ioc_report(value)` | 只读 | 生成确定性的结构化 (JSON) IOC 报告。 |
| `generate_event_report(event_id)` | 只读 | 生成确定性的结构化 (JSON) 事件报告。 |
| `generate_markdown_ioc_report(value)` | 只读 | 生成用于记录/升级的 Markdown IOC 报告。 |
| `generate_markdown_event_report(event_id)` | 只读 | 生成 Markdown 事件报告。 |
### 提议（试运行）工具
| 工具 | 访问级别 | 功能描述 |
| --- | --- | --- |
| `propose_event(...)` | 试运行 | 构建并验证创建事件的提议。绝不会写入 MISP。 |
| `propose_attribute(...)` | 试运行 | 构建并验证创建 attribute 的提议。绝不会写入 MISP。 |
### 审批门控写入工具
| 工具 | 访问级别 | 功能描述 |
| --- | --- | --- |
| `submit_ioc_with_approval(...)` | 审批门控写入 | 将一个 attribute 添加到事件中。 |
| `add_sighting_with_approval(...)` | 审批门控写入 | 记录一次目击事件。 |
| `tag_event_with_approval(...)` | 审批门控写入 | 为事件打上标签。 |
| `publish_event_with_approval(...)` | 审批门控写入 | 发布事件（仅限 curator/admin 角色）。 |
写入工具的结果是明确的：`blocked`、`invalid`、`pending_approval`、`executed` 或 `failed`（MISP 本身拒绝了写入）。不存在隐秘的写入操作。详见 [`docs/approval-flow.md`](docs/approval-flow.md)。
## 快速开始
前置条件：Python 3.11+ 和 [`uv`](https://docs.astral.sh/uv/)（或 Docker — 参见 [Docker](#docker)）、一个可访问的 MISP 实例，以及一个 MISP API key。
```
# 1. Clone 和安装
git clone https://github.com/hdyrawan/agentic-misp-mcp.git
cd agentic-misp-mcp
uv sync --extra dev
# 2. 配置（至少需要 MISP_URL 和 MISP_API_KEY）
cp .env.example .env
# 编辑 .env
# 3. 验证配置（不会建立 MISP 连接；API key 会被脱敏处理）
uv run agentic-misp-mcp config-check
# 4. 运行测试套件
uv run --extra dev pytest -q
# 5. 通过 stdio 启动 MCP server（主要支持的 transport）
uv run agentic-misp-mcp --transport stdio
```
然后：
6. **连接 MCP 客户端** — 参见下方的 [MCP 客户端示例](#mcp-client-examples)。
7. **运行首个只读工具** — `get_misp_status` 是一个很好的零风险冒烟测试；它可以确认连通性并报告 MISP 版本。
8. **查看审计输出**：
tail -n 20 logs/audit.jsonl | jq .
对于新操作员来说，一个不错的前五步操作序列，全部为只读：`get_misp_status` →
`check_warninglists` → `investigate_ioc` → `search_events` → `summarize_feed_health`。
### Docker
```
docker build -t agentic-misp-mcp:local .
# 将 env 文件保留在 repository 之外；切勿 commit 真实的 credentials
mkdir -p /path/to/runtime/logs
cp .env.example /path/to/runtime/.env # edit it
docker run --rm --env-file /path/to/runtime/.env \
-v /path/to/runtime/logs:/app/logs \
agentic-misp-mcp:local config-check
docker run --rm -i --env-file /path/to/runtime/.env \
-v /path/to/runtime/logs:/app/logs \
agentic-misp-mcp:local --transport stdio
```
想使用 Compose？请参阅 `docker-compose.example.yml` 和 [`docs/configuration.md`](docs/configuration.md#docker-compose)。
## 配置
所有配置均通过环境变量（或 `.env` 文件）完成。下方的占位符均为虚假示例——切勿提交真实的凭证。
### 必填项
| 变量 | 示例 | 说明 |
| --- | --- | --- |
| `MISP_URL` | `https://misp.example.local` | 你的 MISP 实例的 Base URL。 |
| `MISP_API_KEY` | `your_misp_api_key_here` | 仅运行时使用的自动化密钥。仅从环境中加载；绝不能作为工具参数传递。 |
### 连接与输出界限（可选）
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `MISP_VERIFY_TLS` | `true` | **在生产环境中请保持为 `true`。** `false` 仅适用于带有自签名证书的隔离测试环境——建议改为将内部 CA 添加到信任库中。 |
| `MISP_TIMEOUT_SECONDS` | `30` | HTTP 超时时间，> 0 且 <= 300。 |
| `MISP_DEFAULT_LIMIT` | `20` | 默认结果限制。 |
| `MISP_MAX_LIMIT` | `100` | 可接受的最大结果限制。 |
| `MISP_EVENT_ATTRIBUTE_LIMIT` | `50` | 事件摘要/调查的 attribute 上限。 |
| `MISP_RELATED_EVENT_LIMIT` | `5` | 相关事件扩展上限。 |
| `AGENTIC_MISP_MCP_MAX_RESPONSE_BYTES` | `5242880` | MISP HTTP 响应正文最大大小，在 JSON 解析前强制执行（失败即终止）。 |
### 安全与策略（可选）
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `AGENTIC_MISP_MCP_ROLE` | `read_only` | `read_only`、`analyst_write`、`curator` 或 `admin` — 参见 [`docs/roles.md`](docs/roles.md)。 |
| `AGENTIC_MISP_MCP_ENABLE_WRITE` | `false` | 全局写入模式开关。除非确实需要写入，否则请保持为 `false`。 |
| `AGENTIC_MISP_MCP_REQUIRE_APPROVAL` | `true` | 测试模式开关，要求显式设置 `approved=true`；生产模式则无论何种情况均要求提供 `approval_request_id`。 |
| `AGENTIC_MISP_MCP_APPROVAL_MODE` | `lab` | `lab` = 程序化的 `approved=true` 流程；`production` = 持久化的、经操作员批准的、一次性使用的请求 ID。 |
| `AGENTIC_MISP_MCP_APPROVAL_TOKEN` | 未设置 | 可选的测试共享密钥加固；在审计日志中会被脱敏。这不是生产环境的审批机制。 |
| `AGENTIC_MISP_MCP_APPROVAL_STORE_PATH` | `./approvals.sqlite3` | 用于生产环境审批的 SQLite 存储。agent 绝不能拥有对其进行写入的权限。请妥善持久化保存。 |
| `AGENTIC_MISP_MCP_APPROVAL_TTL_SECONDS` | `900` | 生产环境审批的有效期。 |
| `AGENTIC_MISP_MCP_ALLOWED_ATTRIBUTE_TYPES` | 未设置 | 生产环境护栏：可提交的 attribute 类型的白名单。 |
| `AGENTIC_MISP_MCP_ALLOWED_ATTRIBUTE_CATEGORIES` | 未设置 | 生产环境护栏：attribute 分类的白名单。 |
| `AGENTIC_MISP_MCP_ALLOWED_TAGS` | 未设置 | 生产环境护栏：事件标签的白名单（`*` 后缀 = 前缀匹配）。 |
| `AGENTIC_MISP_MCP_ENABLE_PUBLISH` | `false` | 专用的发布熔断开关发布同样需要 curator/admin 角色和审批。 |
| `AGENTIC_MISP_MCP_AUDIT_LOG_PATH` | `./logs/audit.jsonl` | JSONL 审计日志路径。请持久化保存（在 Docker 下挂载一个数据卷）。 |
| `AGENTIC_MISP_MCP_LOG_LEVEL` | `INFO` | 应用程序日志级别。 |
| `AGENTIC_MISP_MCP_ALLOW_INSECURE_HTTP_BIND` | `false` | 实验性 HTTP 传输除非设置此项，否则拒绝非环回绑定。请保持为 `false`。 |
### 基于时效的评分和 Feed 新鲜度（可选，v0.3.0+）
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `AGENTIC_MISP_MCP_AGE_WEIGHTING` | `true` | 基于时效的 IOC 评分。`false` 可完全复现 v0.2.x 的评分逻辑（无论何种设置，均会输出 `freshness` 块）。 |
| `AGENTIC_MISP_MCP_FRESHNESS_FRESH_DAYS` | `30` | 最新信号时间等于或小于该天数视为 `fresh`。 |
| `AGENTIC_MISP_MCP_FRESHNESS_AGING_DAYS` | `90` | `aging` 的上限。 |
| `AGENTIC_MISP_MCP_FRESHNESS_STALE_DAYS` | `365` | `stale` 的上限；超出则为 `expired`。 |
| `AGENTIC_MISP_MCP_AGE_WEIGHTS` | `1.0,0.75,0.4,0.15` | fresh/aging/stale/expired 的得分乘数，每个介于 0–1 之间。 |
| `AGENTIC_MISP_MCP_FEED_FRESH_DAYS` | `7` | Feed 获取/缓存时间等于或小于该值视为 fresh。 |
| `AGENTIC_MISP_MCP_FEED_STALE_DAYS` | `30` | Feed 获取/缓存时间大于该值视为 stale。 |
完整参考与示例：[`docs/configuration.md`](docs/configuration.md)。在任何生产环境运行之前，还需使用更深度的检查：
```
uv run agentic-misp-mcp config doctor
```
它会验证写入/审批模式的搭配、审批存储和审计日志的权限安全性、白名单覆盖范围等——而不会连接 MISP 或打印出任何机密信息。
## MCP 客户端示例
所有示例均使用 stdio 传输（主要支持的传输方式）和通用路径——请将 `/path/to/agentic-misp-mcp` 替换为你的检出路径（例如 `/home/user/agentic-misp-mcp` 或 `/opt/agentic-misp-mcp`）。
### MCP Inspector（冒烟测试）
```
npx @modelcontextprotocol/inspector \
uv --directory /path/to/agentic-misp-mcp run agentic-misp-mcp --transport stdio
```
无头/CI 模式（无浏览器）：
```
npx -y @modelcontextprotocol/inspector --cli \
uv --directory /path/to/agentic-misp-mcp run agentic-misp-mcp \
--method tools/list
```
在无头主机上，请使用 `--cli` 模式或通过 SSH 转发 Inspector UI 端口：
`ssh -L 6274:localhost:6274 -L 6277:localhost:6277 user@mcp-host.example.local`。
### Claude Code
```
claude mcp add agentic-misp-mcp -s local -- \
uv --directory /path/to/agentic-misp-mcp run agentic-misp-mcp --transport stdio
```
通过 `claude mcp list` 验证（应显示 `✔ Connected`），然后启动一个 **全新的** Claude Code 会话——工具将在 `add` 之后启动的会话中出现。可以使用以下命令移除
`claude mcp remove agentic-misp-mcp -s local`。除非每个团队成员都有相同的路径，否则请避免使用 `-s project`，因为它会原封不动地写入一个共享的 `.mcp.json` 文件。
### Claude Desktop
添加到 `claude_desktop_config.json`：
```
{
"mcpServers": {
"agentic-misp-mcp": {
"command": "uv",
"args": [
"--directory", "/path/to/agentic-misp-mcp",
"run", "agentic-misp-mcp", "--transport", "stdio"
],
"env": {
"MISP_URL": "https://misp.example.local",
"MISP_API_KEY": "your_misp_api_key_here"
}
}
}
}
```
当你的客户端支持时，推荐使用 `--env-file`/操作系统级别的密钥管理，而不是内联密钥，且切勿提交包含真实密钥的客户端配置。
### Hermes Agent
```
hermes mcp add agentic-misp-mcp \
--command uv \
--args --directory /path/to/agentic-misp-mcp run agentic-misp-mcp --transport stdio
```
Hermes 会执行实时的发现握手并提示启用工具——对所有 25 个回答 `y`，或者使用 `select` 来启用只读子集（除了四个 `_with_approval` 和两个 `propose_*` 工具之外的所有内容）。通过 `hermes mcp list` / `hermes mcp test agentic-misp-mcp` 进行验证，然后启动一个新的 Hermes 会话。
### OpenCode（或类似的本地 agent CLI）
```
{
"mcp": {
"agentic-misp-mcp": {
"type": "local",
"command": [
"uv", "--directory", "/path/to/agentic-misp-mcp",
"run", "agentic-misp-mcp", "--transport", "stdio"
],
"environment": {
"MISP_URL": "https://misp.example.local",
"MISP_API_KEY": "your_misp_api_key_here"
}
}
}
}
```
任何能够生成 stdio 子进程的 MCP 客户端的工作方式都是相同的：运行
`uv --directory /path/to/agentic-misp-mcp run agentic-misp-mcp --transport stdio`（或者使用 [Docker](#docker) 中的等效命令
`docker run --rm -i ... --transport stdio`）。
**传输说明：** stdio 是推荐的生产传输方式。HTTP 传输是实验性的，没有内置的认证或 TLS，并且除非设置 `AGENTIC_MISP_MCP_ALLOW_INSECURE_HTTP_BIND=true`，否则拒绝绑定非环回主机；如果必须使用它，请将其置于经过身份验证且能进行 TLS 终止的网关之后。
## 生产检查清单
在将 agent 指向生产环境 MISP 之前：
- [ ] 为此服务器创建一个**专用的最小权限 MISP API key**（而非个人或站点管理员密钥）。
- [ ] 在正常 agent 使用时保持 `AGENTIC_MISP_MCP_ROLE=read_only` 和 `AGENTIC_MISP_MCP_ENABLE_WRITE=false`；仅在工作流确实需要时才启用写入。
- [ ] 如果启用了写入，请使用 `AGENTIC_MISP_MCP_APPROVAL_MODE=production`，并将审批 CLI 和审批数据库保留在 agent 无法触及的范围之外。
- [ ] **持久化审计日志**（`AGENTIC_MISP_MCP_AUDIT_LOG_PATH`；在 Docker 下挂载一个数据卷）。
- [ ] **持久化审批存储库**（`AGENTIC_MISP_MCP_APPROVAL_STORE_PATH`）。
- [ ] 保护 `MISP_API_KEY` — 仅限环境变量/密钥管理器；不要将 `.env` 文件放入 git，也不要放入会被共享的客户端配置中。
- [ ] 保持 `MISP_VERIFY_TLS=true`；通过你的内部 CA 解决证书问题，不要禁用验证。
- [ ] 在每次配置更改后运行 `agentic-misp-mcp config-check` 和 `agentic-misp-mcp config doctor`。
- [ ] 在已部署的版本上运行测试套件（`uv run --extra dev pytest -q`）。
- [ ] 使用 MCP Inspector 进行冒烟测试（`tools/list`，然后是 `get_misp_status`）。
- [ ] 在首批真实工具调用之后审查 `audit.jsonl`，并在此后定期审查（人工审计审查是公认的控制手段——没有内置的告警机制）。
- [ ] 将 feed 管理（启用/获取/缓存）保留在 MCP 之外的 MISP UI/API 中。
更深入的指南：[`docs/production-readiness.md`](docs/production-readiness.md),
[`docs/production-write.md`](docs/production-write.md),
[`docs/rollback.md`](docs/rollback.md)。
## 安全边界
这些是设计层面的边界，在代码中强制执行，并在不同版本中保持一致：
- **无原始 MISP API 代理。** 只存在这 25 个工作流工具；不存在通用的 endpoint 直通工具。
- **禁止 Feed 变更。** 不存在任何用于启用/禁用/获取/缓存/编辑/删除 feed 的工具。Feed 可观测性（`list_feeds`, `get_feed_status`, `summarize_feed_health`）严格限制为只读，并且 URL 以及类似 header/token 的字段均已脱敏。
- **不暴露审批存储。** 没有任何 MCP 工具可以创建、批准、拒绝或读取审批记录；生产审批只能通过操作员 CLI 进行。
- **无未门控的写入。** 每个写入路径都会经过角色策略、写入模式开关和审批门控；结果是显式的（`blocked`/`pending_approval`/`executed`/`failed`）。
- **读取工具中没有任何隐藏的变更。** 读取工具仅调用读取 endpoint。
- **`propose_*` 工具仅用于试运行。** 它们构建并验证 payload；它们从不调用 MISP 写入 endpoint。
- **无密钥透传。** API key、token、密码和 authorization header 绝不会被作为工具参数接受，并在审计日志中进行脱敏。
- 没有执行 shell 命令或不受限制的文件系统工具；没有 user/org/server/settings 管理工具。
请参阅 [`docs/security.md`](docs/security.md) 以了解完整的安全模型和审计语义。
## 评分行为
从 `v0.3.0` 开始，IOC 评分**默认基于时效**。`investigate_ioc`、`generate_ioc_report` 和 `pivot_ioc` 的响应包含一个 `freshness` 块，用于标记判定背后的情报：
| 标签 | 含义（默认值） |
| --- | --- |
| `fresh` | 最新信号 ≤ 30 天。 |
| `aging` | 31–90 天。 |
| `stale` | 91–365 天。 |
| `expired` | 超过 365 天。 |
| `unknown` | 未找到可用的时间戳。 |
这对分数的影响：
- **默认情况下，旧的情报得分较低。** 正向得分因素会根据情报的时效性进行折减（fresh/aging/stale/expired 的默认权重为 `1.0 / 0.75 / 0.4 / 0.15`）。
- **惩罚措施绝不因时效而折减。** Warninglist 命中和良性标签的惩罚无论时间长短，均按全强度施加。
- **过期的情报不能仅凭自身变为 `likely_malicious`** — 仅有过期情报的分数会被限制在该阈值之下，需要新鲜的佐证才能跨越该界限。
- **`AGENTIC_MISP_MCP_AGE_WEIGHTING=false`** 可恢复准确的 v0.2.x 评分逻辑（`freshness` 块仍会被报告）。
这是一种置信度质量的提升，并不能替代分析师的判断：如果一个具有 10 年历史的 OSINT 事件最近被重新发布并获得了 `fresh` 命中，在对其进行阻断或升级处理之前，仍需要结合当前的遥测数据进行人工关联。
## 故障排除
| 症状 | 可能原因 | 修复方法 |
| --- | --- | --- |
| 连接错误，`MISPClientError` | `MISP_URL` 错误，或者服务器运行的位置无法访问 MISP | 验证 URL（协议 + 主机，不带尾部的 API 路径）；从同一主机/容器内测试 `curl https://misp.example.local/servers/getVersion -H "Authorization: "`。 |
| 认证错误，`MISPAuthenticationError` | `MISP_API_KEY` 无效或已被撤销 | 在 MISP 中重新生成自动化密钥；确认环境变量确实已传入进程（`config-check` 会显示是否已设置，且会进行脱敏）。 |
| TLS 验证失败 | 自签名或内部 CA 证书 | 将 CA 添加到系统信任库中。`MISP_VERIFY_TLS=false` 仅能作为隔离测试环境中的应急手段——绝不可用于生产。 |
| MISP 返回权限被拒绝 | API key 对应的 MISP 角色缺乏所需权限 | 授予工作流所需的最低 MISP 权限（例如，用于目击记录的创建权限），保持密钥具有最小权限。 |
| 工具返回 `blocked` | 策略按预期发挥作用：角色或写入模式门控 | 检查 `AGENTIC_MISP_MCP_ROLE` 和 `AGENTIC_MISP_MCP_ENABLE_WRITE`。审计日志会记录 `outcome=blocked` 及其原因。 |
| 写入返回 `pending_approval` | 需要审批（默认行为） | Lab 模式：带上 `approved=true` 重新调用（如果进行了配置，还需加上 `approval_token`）。Production 模式：操作员必须通过 `agentic-misp-mcp approvals ...` 进行审批，且调用时必须提供生成的 `approval_request_id`。 |
| `config-check` 在审计路径上失败 | 审计日志目录缺失或不可写 | 创建目录/修复权限；在 Docker 环境下，在审计路径处挂载一个可写卷。 |
| 重启后审批记录消失 | 审批数据库未持久化 | 将 `AGENTIC_MISP_MCP_APPROVAL_STORE_PATH` 指向持久化存储（Docker：挂载一个数据卷）。 |
| “Response too large” 错误 | MISP 响应超过了 `AGENTIC_MISP_MCP_MAX_RESPONSE_BYTES`（按设计执行失败即终止） | 缩小查询范围（更小的 `limit`，更紧凑的日期范围）。提高上限只能作为最后的手段。 |
| MCP 客户端无法启动服务器 | 客户端配置中的命令/路径错误 | 使用绝对路径（`uv --directory /path/to/agentic-misp-mcp ...`）；先在终端测试完全相同的命令；注册后重启客户端会话。 |
| 导入错误 / 错误的 Python 版本 | 环境错误或 Python < 3.11 | `uv run`（它会锁定项目环境），或者重新运行 `uv sync --extra dev`；检查 `python --version` ≥ 3.11。 |
## 发布状态
- **最新版本：** `v0.3.1` — 基于 `v0.3.0` 的文档/操作员可读性补丁（无 MCP 工具、评分或写入界面的变更）。参见 [`CHANGELOG.md`](CHANGELOG.md)。
- **功能基准：** `v0.3.0` — 基于时效性的评分，六个全新的只读工具（目击、事件搜索、状态、feed 可观测性），读取工具的响应封装。
- **受支持的 MISP 基准：** `2.5.42`，实时验证 14/14 —
[`docs/live-validation-report-v0.3.0.md`](docs/live-validation-report-v0.3.0.md)。
- **最新合并前的审查发现：**
[`docs/review-v0.3.0-findings.md`](docs/review-v0.3.0-findings.md)。
- **工具数量：** 25。**测试数：** 353（模拟 MISP 响应；实时验证是单独的手动步骤）。
- **生产环境声明的范围：** `v0.2.0` 被宣布为 GA **仅针对本项目的 MCP 服务器范围**（服务器行为、MISP API 行为、审批工作流、审计/脱敏、配置安全性）——而不是一个 SIEM/SOAR/SOC 平台声明。`v0.3.x` 扩展了同样的范围。参见
[`docs/ga-production-readiness-plan.md`](docs/ga-production-readiness-plan.md)。
- **已知局限性：** 仅验证了 MISP `2.5.42`；实时的 HTTP `429` 仅包含模拟覆盖（没有在实验室中安全触发的方法）；容器/依赖/机密扫描和已签名的发布工件尚未成为 CI/发布流程的一部分；HTTP 传输是实验性的；历史的 OSINT 命中应与当前的遥测数据进行关联（基于时效的评分只能缓解，不能消除此情况）。
## 开发
```
uv run --extra dev ruff check .
uv run --extra dev ruff format --check .
uv run --extra dev pytest -q
```
等价的 Make 命令：`make lint`、`make format-check`、`make test`、`make check`。
CI 会在 Python 3.11 和 3.12 上运行相同的检查。
## 文档
- [`docs/configuration.md`](docs/configuration.md) — 完整的环境变量参考，
Docker/Compose、客户端配置形式、`config doctor`。
- [`docs/security.md`](docs/security.md) — 安全模型、工具边界、审计语义。
- [`docs/roles.md`](docs/roles.md) — 角色策略矩阵。
- [`docs/approval-flow.md`](docs/approval-flow.md) — lab 和 production 环境的审批流程。
- [`docs/production-write.md`](docs/production-write.md) — 生产环境写入部署指南。
- [`docs/production-readiness.md`](docs/production-readiness.md) — 更广泛的就绪清单
以及它尚需满足的条件。
- [`docs/feed-observability.md`](docs/feed-observability.md) — feed 工具和 feed 安全
边界。
- [`docs/testing.md`](docs/testing.md) — 模拟套件覆盖了哪些内容。
- [`docs/misp-compatibility.md`](docs/misp-compatibility.md) — MISP 版本矩阵。
- [`docs/live-validation-report-v0.3.0.md`](docs/live-validation-report-v0.3.0.md) — 最新的
实时验证证据（早期的报告放在了 `docs/` 中）。
- [`docs/rollback.md`](docs/rollback.md) — 针对错误受控写入操作的回退手册。
## 贡献
欢迎对本项目做出贡献，但请保持项目边界完整：禁止原始 API 代理，禁止密钥透传，禁止未经审计的工具路径，禁止在没有策略和审批门控的情况下执行写入行为。
建议从 `PROJECT_STATE.md`、[`docs/security.md`](docs/security.md) 以及 `src/agentic_misp_mcp/tools/registry.py` 开始。
提交记录应仅归属于其人类作者——无论使用了什么工具辅助编写，都**不要**在代码库的提交中添加 AI 共同作者尾部信息（例如 `Co-Authored-By: `）。
## 许可证
MIT。
标签：AI智能体, LLM, MCP, Unmanaged PE, 威胁情报, 安全运营, 开发者工具, 扫描框架, 请求拦截, 逆向工具