mirror of
https://github.com/Ed1s0nZ/CyberStrikeAI.git
synced 2026-07-10 22:33:48 +02:00
公明
190 lines
4.1 KiB
Markdown
190 lines
4.1 KiB
Markdown
# MCP 联邦
|
||
|
||
CyberStrikeAI 同时支持内置 MCP 工具、独立 HTTP MCP 服务和外部 MCP 联邦。MCP 是 Agent 调用工具的主要协议层。
|
||
|
||
## 内置 MCP
|
||
|
||
Web 服务内部会创建 MCP Server，并注册：
|
||
|
||
- YAML 命令工具。
|
||
- 内置安全执行工具。
|
||
- 知识库工具。
|
||
- 项目事实工具。
|
||
- C2 工具。
|
||
- WebShell 工具。
|
||
- 批量任务工具。
|
||
- 视觉分析工具。
|
||
|
||
前端和 Agent 通常通过应用内部调用，不需要额外配置。
|
||
|
||
## HTTP MCP 服务
|
||
|
||
配置：
|
||
|
||
```yaml
|
||
mcp:
|
||
enabled: true
|
||
host: 0.0.0.0
|
||
port: 8081
|
||
auth_header: "X-MCP-Token"
|
||
auth_header_value: "random-secret"
|
||
```
|
||
|
||
生产环境必须设置 `auth_header_value`，并限制网络访问。
|
||
|
||
## Web 内 MCP 端点
|
||
|
||
登录后可通过：
|
||
|
||
```text
|
||
POST /api/mcp
|
||
```
|
||
|
||
该端点复用 Web 认证，适合内部页面或受控集成。
|
||
|
||
## 外部 MCP
|
||
|
||
外部 MCP 配置在：
|
||
|
||
```yaml
|
||
external_mcp:
|
||
servers: {}
|
||
```
|
||
|
||
也可以通过 Web 的 MCP 管理页面新增、启动、停止和删除。
|
||
|
||
接口：
|
||
|
||
- `GET /api/external-mcp`
|
||
- `GET /api/external-mcp/stats`
|
||
- `GET /api/external-mcp/:name`
|
||
- `PUT /api/external-mcp/:name`
|
||
- `POST /api/external-mcp/:name/start`
|
||
- `POST /api/external-mcp/:name/stop`
|
||
- `DELETE /api/external-mcp/:name`
|
||
|
||
## stdio
|
||
|
||
stdio MCP 适合本机命令启动的工具服务。
|
||
|
||
关注点：
|
||
|
||
- 命令路径必须存在。
|
||
- 工作目录正确。
|
||
- 环境变量完整。
|
||
- 进程退出会导致工具不可用。
|
||
- 日志中查看启动失败原因。
|
||
|
||
## HTTP / SSE
|
||
|
||
HTTP 或 SSE MCP 适合远端或长期运行服务。
|
||
|
||
关注点：
|
||
|
||
- URL 可达。
|
||
- 认证头正确。
|
||
- TLS 证书可信。
|
||
- 代理和防火墙放行。
|
||
- 服务端协议版本兼容。
|
||
|
||
## 工具暴露策略
|
||
|
||
工具过多会增加上下文成本和误选概率。多代理中可通过：
|
||
|
||
```yaml
|
||
multi_agent:
|
||
eino_middleware:
|
||
tool_search_enable: true
|
||
tool_search_min_tools: 20
|
||
tool_search_always_visible: 12
|
||
tool_search_always_visible_tools:
|
||
- read_file
|
||
- glob
|
||
- grep
|
||
- tool_search
|
||
```
|
||
|
||
让常用工具常驻，其余工具由 `tool_search` 动态解锁。
|
||
|
||
## 安全建议
|
||
|
||
- 外部 MCP 只接入可信服务。
|
||
- 远端 MCP 必须认证。
|
||
- 高风险工具不要常驻上下文。
|
||
- 外部 MCP 的文件系统和命令执行能力要单独评估。
|
||
- 变更外部 MCP 后查看审计日志。
|
||
|
||
## 调试
|
||
|
||
排查顺序：
|
||
|
||
1. `/api/external-mcp/stats` 查看状态。
|
||
2. 检查服务日志。
|
||
3. 单独运行 stdio 命令。
|
||
4. 用 curl 测试 HTTP/SSE 地址。
|
||
5. 检查工具是否被角色或 tool_search 策略隐藏。
|
||
|
||
## MCP 生命周期
|
||
|
||
外部 MCP 的生命周期不是简单的“添加 URL”：
|
||
|
||
1. 注册配置：名称、类型、命令或 URL、环境变量。
|
||
2. 启动连接：stdio 拉起进程，HTTP/SSE 建立客户端。
|
||
3. 拉取工具列表：工具名、描述、schema 进入平台。
|
||
4. 暴露给 Agent：受角色、tool_search、HITL 影响。
|
||
5. 执行工具：参数校验、调用、记录监控。
|
||
6. 连接恢复：进程退出或网络失败后尝试恢复。
|
||
7. 停止/删除：从运行时和配置中移除。
|
||
|
||
排错时要确认卡在哪一步。
|
||
|
||
## 工具命名规范
|
||
|
||
工具名应：
|
||
|
||
- 稳定。
|
||
- 小写或 snake_case。
|
||
- 表达动作和对象。
|
||
- 避免和内置工具重名。
|
||
|
||
不建议：
|
||
|
||
```text
|
||
run
|
||
execute
|
||
scan
|
||
tool1
|
||
```
|
||
|
||
建议：
|
||
|
||
```text
|
||
burp_send_to_repeater
|
||
asset_lookup_domain
|
||
cloud_list_public_buckets
|
||
```
|
||
|
||
好的工具名会提升 tool_search 命中率，也降低误调用。
|
||
|
||
## 外部 MCP 安全审查清单
|
||
|
||
接入前问：
|
||
|
||
- 它能读写本机文件吗？
|
||
- 它能执行命令吗？
|
||
- 它会访问哪些网络？
|
||
- 它是否把请求发给第三方？
|
||
- 它的工具描述是否可信？
|
||
- 它的输出是否可能包含 prompt injection？
|
||
- 它是否需要独立运行用户或容器隔离？
|
||
|
||
只要答案不清楚，就不要放进生产环境常驻工具池。
|
||
|
||
## 源码锚点
|
||
|
||
- 外部 MCP Manager：`internal/mcp/external_manager.go`
|
||
- 连接恢复：`internal/mcp/connection_recovery.go`
|
||
- MCP 工具适配：`internal/einomcp/mcp_tools.go`
|
||
- 外部 MCP Handler：`internal/handler/external_mcp.go`
|
||
- 工具调用通知：`internal/einomcp/tool_invoke_notify.go`
|