4.6 KiB
4.6 KiB
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 层访问凭证：
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 调用失败率和写入错误率。