增加 SuperAgent MCP 内嵌接口和配置文档
This commit is contained in:
andy
145
docs/project/integrations/superagent-mcp/security-policy.md
Normal file
145
docs/project/integrations/superagent-mcp/security-policy.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# TH Hotel SuperAgent MCP 安全策略
|
||||
|
||||
## 1. 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档版本 | 0.1 |
|
||||
| 日期 | 2026-07-09 |
|
||||
| 状态 | 草案 |
|
||||
| 适用范围 | `server/` 内嵌 SuperAgent MCP endpoint 安全、权限和日志边界 |
|
||||
|
||||
## 2. 安全目标
|
||||
|
||||
内嵌 MCP endpoint 的安全目标是：
|
||||
|
||||
- 让 SuperAgent 通过语义化工具调用业务能力。
|
||||
- 不让 SuperAgent 直接接触后端 HMAC secret。
|
||||
- 不绕过现有后端鉴权、幂等、审计和业务校验。
|
||||
- 不返回附件 URL、原始未清洗 HTML、客户敏感信息或生产 Secret。
|
||||
- 对写操作建立清晰边界。
|
||||
|
||||
## 3. 两层鉴权
|
||||
|
||||
### 3.1 SuperAgent 到 MCP Endpoint
|
||||
|
||||
建议使用 MCP 层访问凭证：
|
||||
|
||||
```text
|
||||
Authorization: Bearer <MCP_AUTH_TOKEN>
|
||||
```
|
||||
|
||||
中文说明：
|
||||
|
||||
- `MCP_AUTH_TOKEN` 用于限制谁可以调用后端内嵌 MCP endpoint。
|
||||
- 该 token 与后端 HMAC secret 不是同一个值。
|
||||
- 该 token 应是高熵随机字符串，不使用手机号、项目名、酒店名、固定短语或可猜测文本。
|
||||
- dev、test、prod 必须使用不同 token，生产 token 建议至少 32 字节随机值。
|
||||
- token 应通过部署平台 Secret 或安全通道交付，不写入仓库。
|
||||
|
||||
### 3.2 MCP Endpoint 到业务 Service
|
||||
|
||||
MCP endpoint 与后端业务 Service 同进程，不再通过 HMAC REST 调用本后端。
|
||||
|
||||
中文说明：
|
||||
|
||||
- REST HMAC 规则继续用于原有 REST API。
|
||||
- MCP endpoint 只校验 MCP Bearer Token。
|
||||
- MCP endpoint 必须通过现有 Service 进入业务逻辑，不能直接访问 Mapper 或数据库。
|
||||
- SuperAgent 不需要知道 REST HMAC 签名串，也不能拿到 REST HMAC secret。
|
||||
|
||||
## 4. Tool 权限边界
|
||||
|
||||
| Tool | 权限级别 | 安全说明 |
|
||||
| --- | --- | --- |
|
||||
| `th_hotel_query_case_context` | 只读 | 不写订单、不写任务、不写 OPERA |
|
||||
| `th_hotel_query_object_detail` | 只读 | 不写订单、不写任务、不写 OPERA |
|
||||
| `th_hotel_list_message_conversation_tasks` | 只读 | 不创建任务、不修改任务 |
|
||||
| `th_hotel_list_message_conversation_messages` | 受控读取 | 读取正文会写后端访问审计 |
|
||||
| `th_hotel_submit_task_results` | 写入 | 写 AI 过渡层、订单、任务和任务卡 |
|
||||
|
||||
写入工具要求：
|
||||
|
||||
- dev/test 可以用于联调。
|
||||
- prod 必须经过上线审批后启用。
|
||||
- 生产建议保留独立开关，例如 `MCP_ENABLE_SUBMIT_TASK_RESULTS=true`。
|
||||
- 日志必须能定位调用方、request id、trace id 和 source message，但不能输出正文和 Secret。
|
||||
|
||||
## 5. 邮件正文和附件边界
|
||||
|
||||
`th_hotel_list_message_conversation_messages` 只允许返回受控正文。
|
||||
|
||||
禁止返回：
|
||||
|
||||
- 原始未清洗 HTML。
|
||||
- 附件 URL。
|
||||
- 内嵌图片 URL。
|
||||
- `attachments`、`inline_images`、`external_url`。
|
||||
- HTML 中的 `href/src` 外链属性。
|
||||
|
||||
如果 SuperAgent 后续需要附件内容，应新增独立的受控附件接口和权限策略，不能复用当前正文工具绕过限制。
|
||||
|
||||
## 6. ID 边界
|
||||
|
||||
SuperAgent 可以使用：
|
||||
|
||||
- `hotel_id`
|
||||
- 外部 `source_message_id`
|
||||
- `external_conversation_id`
|
||||
- 业务 key，例如 `group_code`、`confirmation_number`
|
||||
|
||||
SuperAgent 不应依赖：
|
||||
|
||||
- 内部 SourceMessage Inbox ID。
|
||||
- 数据库主键表达业务含义。
|
||||
- 前端内部路由或展示字段。
|
||||
|
||||
接口响应中如果出现内部 ID，只能用于本系统排查或后续本系统 API 的对象定位，不应当作外部系统稳定业务 ID。
|
||||
|
||||
## 7. 日志与脱敏
|
||||
|
||||
MCP endpoint 日志允许记录：
|
||||
|
||||
- tool 名称。
|
||||
- request id。
|
||||
- trace id。
|
||||
- hotel id。
|
||||
- 外部 source message id。
|
||||
- HTTP 状态码。
|
||||
- 错误码。
|
||||
- 调用耗时。
|
||||
|
||||
禁止记录：
|
||||
|
||||
- REST HMAC secret。
|
||||
- MCP auth token。
|
||||
- 完整 HMAC signature。
|
||||
- 原始邮件正文。
|
||||
- 附件 URL。
|
||||
- 客户证件、支付信息、Token、Cookie。
|
||||
- 未清洗 HTML。
|
||||
|
||||
## 8. 重试策略
|
||||
|
||||
只读工具：
|
||||
|
||||
- MCP endpoint 与业务 Service 同进程，不做 HTTP 重试。
|
||||
- 如果内部 Service 返回受控错误，应原样包装为 tool result。
|
||||
|
||||
写入工具：
|
||||
|
||||
- 默认不自动重试已发送的写请求。
|
||||
- 如果调用方需要重试，必须依赖后端幂等机制和任务结果中的幂等信息。
|
||||
- 对于响应丢失但请求可能已到达后端的场景，应优先查询已有任务或人工排查，避免重复写入。
|
||||
|
||||
## 9. 生产上线前检查
|
||||
|
||||
上线前必须确认：
|
||||
|
||||
- 生产 `MCP_AUTH_TOKEN` 已通过 Secret 注入。
|
||||
- `MCP_MAX_BODY_BYTES` 已确认，默认 10MB。
|
||||
- dev/test 临时 token 没有进入生产。
|
||||
- 日志脱敏规则已经生效。
|
||||
- 写入工具生产开关已经明确。
|
||||
- 所有接口只暴露在 HTTPS 和可信网络边界内。
|
||||
- 监控覆盖 `/mcp` 可用性、tool 调用失败率和写入错误率。
|
||||
Reference in New Issue
Block a user