claude-code/audit-report-zh.md

# 项目风险审查报告

## 审查思路与重点检查范围

### 审查思路
- 先整体理解项目结构，识别入口、核心服务层、远程/插件/工具执行链路，判断系统边界与高权限路径。
- 再逐层下钻高风险面：鉴权与权限、配置与环境变量、远程会话、MCP/插件扩展、文件读写、外部 API、日志与遥测、异常处理。
- 最后评估工程治理：测试覆盖、依赖与发布材料、模块耦合度、可观测性、容错与限流，以及未来演进阻力。

### 重点检查的文件与模块
- 入口与全局编排：`src/main.tsx`
- 鉴权与会话：`src/utils/auth.ts`、`src/utils/sessionIngressAuth.ts`、`src/services/oauth/*`
- 权限控制：`src/utils/permissions/permissionSetup.ts`、`src/remote/remotePermissionBridge.ts`
- API 与外部调用：`src/services/api/client.ts`、`src/services/api/claude.ts`、`src/services/api/filesApi.ts`、`src/services/api/sessionIngress.ts`
- 远程连接：`src/remote/RemoteSessionManager.ts`、`src/remote/SessionsWebSocket.ts`、`src/server/createDirectConnectSession.ts`
- MCP / 插件：`src/services/mcp/client.ts`、`src/services/mcp/auth.ts`、`src/services/mcp/config.ts`、`src/services/mcp/channelPermissions.ts`、`src/services/mcp/headersHelper.ts`、`src/utils/plugins/pluginLoader.ts`
- 配置与环境：`src/utils/config.ts`、`src/setup.ts`
- 日志与遥测：`src/services/internalLogging.ts`、`src/utils/log.ts`、`src/services/analytics/*`
- 历史与数据落盘：`src/history.ts`
- 测试与工程材料：交付目录中未发现常规测试目录、依赖清单文件、Dockerfile、CI workflow 等工程材料

---

## 1. 执行摘要

- 本次审查基于交付目录中的 `src/` 代码快照完成；仓库根目录仅见 `src/` 与 `src.zip`，未发现 `package.json`、lockfile、Dockerfile、CI workflow 等工程材料，因此依赖、部署、发布链路的结论中有一部分只能标记为“潜在风险”。
- 从安全与治理角度看，项目最突出的问题不在传统 SQL 注入，而在高权限能力边界：远程会话可显式跳过权限确认、MCP `headersHelper` 在非交互场景可执行仓库配置中的 shell、渠道型权限转发明确接受“被攻陷服务可伪造批准”。
- 从稳定性与可维护性角度看，代码存在明显的“大文件核心模块”现象：`src/main.tsx` 4684 行、`src/services/api/claude.ts` 3420 行、`src/services/mcp/client.ts` 3349 行、`src/utils/auth.ts` 2003 行、`src/utils/config.ts` 1818 行、`src/utils/plugins/pluginLoader.ts` 3303 行，架构复杂度和变更风险偏高。
- 从质量保障角度看，本次扫描未在交付快照中发现常规测试文件；同时存在错误语义被吞掉、日志/遥测采集权限上下文、文件 API 内存占用上界偏高等问题，已影响上线评审通过把握度。
- 正向结论：在部分路径中已看到一定治理意识，例如 `zod` 校验已用于 `src/services/api/bootstrap.ts:19`、`src/server/createDirectConnectSession.ts:71`；团队记忆同步具备 secrets 扫描能力 `src/services/teamMemorySync/secretScanner.ts`。但这些措施尚未覆盖最关键的高权限边界。

## 2. 项目总体风险评级

- 评级：高
- 依据：
  - 存在可绕过或弱化权限边界的高风险能力。
  - 存在非交互场景执行配置型 shell 的风险。
  - 存在被明确“接受”的渠道自批准风险。
  - 安全关键模块集中在超大文件中，缺少可见测试资产。
  - 交付快照缺失依赖与部署元数据，无法完成完整供应链审计。

## 3. 关键高风险问题

- 远程直连会话支持 `dangerously_skip_permissions`，客户端直接透传到服务端，属于高权限绕过能力暴露。位置：`src/server/createDirectConnectSession.ts:52`
- MCP `headersHelper` 在非交互模式跳过工作区信任校验，并以 `shell: true` 执行配置内容，存在仓库配置触发命令执行风险。位置：`src/services/mcp/headersHelper.ts:41`、`src/services/mcp/headersHelper.ts:61`
- 渠道权限转发机制文档化接受“allowlisted channel server 被攻陷后可伪造 yes <id> 批准”的风险，属于明确的权限信任边界缺陷。位置：`src/services/mcp/channelPermissions.ts:15`

## 4. 完整风险明细

### 问题 1：远程直连会话可跳过全部权限确认
- 等级：高
- 类别：鉴权与权限控制
- 位置：`src/server/createDirectConnectSession.ts:26`
- 证据：
  - 请求体直接拼入 `dangerously_skip_permissions: true`。`src/server/createDirectConnectSession.ts:52`
  - 客户端无额外服务端能力确认、无二次约束，仅靠调用参数控制。`src/server/createDirectConnectSession.ts:30`
- 影响：
  - 一旦被误用、被脚本化调用或服务端控制面暴露不当，远程会话将失去最后一道人工确认。
  - 对上线环境而言，这是“高危能力默认可被客户端发起”的设计风险，而非普通实现细节。
- 修复建议：
  - 将该能力改为服务端强校验加显式 allowlist，仅对受控环境、受控主体开放。
  - 增加审计日志、双因子确认或短时一次性 capability token。
  - 在协议层区分“调试/实验能力”与“生产能力”，避免同接口透传。

### 问题 2：非交互模式下 `headersHelper` 可执行仓库配置中的 shell
- 等级：高
- 类别：命令执行 / 供应链 / 工作区信任
- 位置：`src/services/mcp/headersHelper.ts:32`
- 证据：
  - 注释明确写明“非交互模式跳过 trust check”。`src/services/mcp/headersHelper.ts:41`
  - 执行使用 `shell: true`。`src/services/mcp/headersHelper.ts:61`
  - 输入来源是 MCP 配置中的 `headersHelper`，属于配置驱动执行。`src/services/mcp/headersHelper.ts:36`
- 影响：
  - 在 CI/CD、自动化、批处理、机器人账号等非交互场景，仓库内 `.mcp.json` 或项目配置可触发命令执行。
  - 这是典型的工程链路风险：不是“外部攻击者输入”，而是“供应链/仓库内容”成为执行入口。
- 修复建议：
  - 非交互模式默认禁用 project/local scope 的 `headersHelper`。
  - 去掉 `shell: true`，改为显式可执行文件加参数数组。
  - 对 helper 路径做 allowlist、签名校验或固定目录校验；在 CI 中要求显式 `--allow-headers-helper`。

### 问题 3：渠道型权限中继接受“被攻陷服务可伪造批准”
- 等级：高
- 类别：权限边界 / 信任边界
- 位置：`src/services/mcp/channelPermissions.ts:15`
- 证据：
  - 注释明确说明：被攻陷的 channel server “CAN fabricate yes <id>”，且被定义为 “Accepted risk”。`src/services/mcp/channelPermissions.ts:17`
  - 客户端 `resolve()` 只按 `requestId` 匹配，不校验用户侧证明。`src/services/mcp/channelPermissions.ts:228`
- 影响：
  - 只要 allowlisted 渠道服务被劫持或滥用，就可绕过真实用户确认，形成高权限操作链。
  - 该问题不是“实现 bug”，而是体系化信任模型缺陷。
- 修复建议：
  - 将批准从“服务端声明”升级为“用户签名确认”或一次性 challenge-response。
  - 把渠道批准降级为“辅助确认”，最终批准仍需本地或受信 UI 完成。
  - 至少对高危工具类别禁用渠道批准。

### 问题 4：内部遥测记录完整权限上下文与容器标识，存在敏感信息外泄面
- 等级：中
- 类别：日志与隐私
- 位置：`src/services/internalLogging.ts:71`
- 证据：
  - 上报事件包含 `toolPermissionContext` 全量序列化。`src/services/internalLogging.ts:84`
  - 同时采集 namespace 与 containerId。`src/services/internalLogging.ts:82`、`src/services/internalLogging.ts:87`
- 影响：
  - 权限规则、工作负载位置、容器标识组合后，可形成高敏内部运维画像。
  - 若后续事件字段扩展不慎，还可能携带策略细节或环境信息，增加横向分析风险。
- 修复建议：
  - 对权限上下文做最小化采集，只保留模式与规则计数，不传完整 JSON。
  - 对 containerId / namespace 做哈希或分级脱敏。
  - 建立“遥测字段白名单评审”机制。

### 问题 5：会话日志获取对 401 语义处理不一致，认证错误被吞为 `null`
- 等级：中
- 类别：异常处理 / 稳定性
- 位置：`src/services/api/sessionIngress.ts:420`
- 证据：
  - 401 时先抛出“请重新登录”。`src/services/api/sessionIngress.ts:462`
  - 但外层 `catch` 统一返回 `null`，导致调用方无法区分认证失效与普通拉取失败。`src/services/api/sessionIngress.ts:477`
  - 同文件 `getTeleportEvents()` 对 401 则直接抛错，处理语义不一致。`src/services/api/sessionIngress.ts:355`
- 影响：
  - 调用方可能误判为“无日志”或“暂时失败”，影响故障排查、会话恢复与用户提示准确性。
  - 长期会导致隐性数据一致性问题和运维误导。
- 修复建议：
  - 引入结构化错误类型，明确区分 `auth_expired`、`not_found`、`network_error`。
  - 不要在最外层把所有异常折叠成 `null`。
  - 统一 session ingress 与 teleport 的错误契约。

### 问题 6：Files API 下载/上传采用整块内存缓冲，存在资源峰值风险
- 等级：中
- 类别：性能与稳定性
- 位置：`src/services/api/filesApi.ts:132`
- 证据：
  - 下载使用 `responseType: 'arraybuffer'`，完成后整体转成 `Buffer`。`src/services/api/filesApi.ts:149`、`src/services/api/filesApi.ts:158`
  - 下载并发默认 5。`src/services/api/filesApi.ts:269`、`src/services/api/filesApi.ts:320`
  - 上传先整文件 `readFile` 再做大小判断；单文件上限 500MB。`src/services/api/filesApi.ts:396`、`src/services/api/filesApi.ts:413`
- 影响：
  - 多文件并发时容易造成高内存峰值，影响 CLI 稳定性，极端情况下触发 OOM 或系统抖动。
  - 对大文件、远程环境、低内存容器尤其危险。
- 修复建议：
  - 下载改为流式写盘，上传改为流式 multipart。
  - 在下载侧也做 Content-Length 预检和硬限制。
  - 根据可用内存动态收敛并发，而不是固定 5。

### 问题 7：关键消息输入校验偏弱，存在潜在协议鲁棒性风险
- 等级：中
- 类别：输入输出校验
- 位置：`src/remote/SessionsWebSocket.ts:46`、`src/services/api/filesApi.ts:722`
- 证据：
  - WebSocket 入站消息仅判断“对象且含 string 类型的 `type` 字段”。`src/remote/SessionsWebSocket.ts:46`
  - 注释明确选择“不做 allowlist”。`src/remote/SessionsWebSocket.ts:50`
  - 文件规格解析仅按首个 `:` 和空格拆分，缺少更强 schema 校验。`src/services/api/filesApi.ts:726`
- 影响：
  - 在后端版本漂移、代理异常、被污染的上游输入下，客户端更容易出现误处理或不可预测行为。
  - 当前更偏可用性和兼容性风险，但一旦与高权限动作耦合，安全风险会放大。
- 修复建议：
  - 对 control message / session message 建立 schema 分层校验。
  - 对文件规格使用显式 JSON 或结构化参数，而不是字符串拼接协议。
  - 对未知消息类型记录并隔离，不直接进入主流程。

### 问题 8：测试资产在交付快照中不可见，安全关键路径缺少可验证保障
- 等级：中
- 类别：测试治理
- 位置：`src/` 全局
- 证据：
  - 未发现 `src/**/*.{test,spec}.{ts,tsx,js,jsx}`。
  - 未发现 `src/**/__tests__/**/*`。
  - 但项目包含大量安全关键模块与复杂权限状态机。
- 影响：
  - 上线评审无法确认权限模式、远程会话、MCP、认证刷新、错误恢复等关键行为是否被回归覆盖。
  - 安全修复很容易引入新绕过或新回归。
- 修复建议：
  - 至少补齐 auth、permission、remote session、MCP、files API、error contract 的单测/集成测试。
  - 将“危险模式”“非交互模式”“401/409/404 路径”纳入强制回归集。
  - 若测试位于未提供目录，需补充完整仓库再做正式上线审查。

### 问题 9：配置与环境治理复杂度过高，旧新模型并存
- 等级：中
- 类别：架构与可维护性
- 位置：`src/utils/config.ts:183`、`src/utils/auth.ts:120`、`src/main.tsx`
- 证据：
  - `src/utils/config.ts` 同时保留大量 deprecated/legacy 字段，如 `apiKeyHelper`、`env`、`cachedChangelog`、旧 MCP 字段。`src/utils/config.ts:185`、`src/utils/config.ts:237`
  - 全代码树 `process.env` 命中 1514+ 处，环境变量散布广泛。
  - 核心文件体量极大：`src/main.tsx` 4684 行、`src/services/mcp/client.ts` 3349 行等。
- 影响：
  - dev/test/prod 行为难以形成清晰边界，认知负担大，改动外溢风险高。
  - 未来扩展时，极易出现模式冲突、回归和“修一处坏三处”。
- 修复建议：
  - 建立统一配置 schema 与环境分层，收敛 `process.env` 直接读取入口。
  - 拆分超大文件，按 auth、transport、policy、persistence、telemetry 分层。
  - 制定 deprecated 字段清退计划，冻结新增旧式配置入口。

### 问题 10：依赖与部署审计材料缺失，供应链与可复现性无法确认
- 等级：中
- 类别：依赖治理 / 发布治理
- 位置：仓库根目录
- 证据：
  - 根目录仅见 `src/` 与 `src.zip`。
  - 未发现 `package.json`、lockfile、Dockerfile、workflow 文件。
- 影响：
  - 无法确认依赖版本、许可证、已知漏洞、构建命令、发布路径、环境隔离、镜像基线。
  - 对上线评审来说，这意味着供应链风险未被充分审计。
- 修复建议：
  - 补充完整仓库、依赖清单、锁文件、CI/CD 配置、部署 IaC。
  - 引入 SCA、license scan、SBOM 与可复现构建校验。
  - 将部署配置与运行时配置纳入正式评审基线。

## 5. 系统性治理建议

- 建立高权限能力分级：将 `bypassPermissions`、渠道批准、动态 header helper、远程控制列为 P0 能力，统一走安全设计评审。
- 收敛配置入口：以单一 schema 管理 env、settings、project config、managed config，禁止继续扩散 legacy 字段。
- 强化非交互安全策略：默认禁用仓库配置驱动执行，必须显式白名单开启。
- 统一错误契约：安全相关接口不要再用 `null/false` 混合表达认证失败、业务失败、网络失败。
- 建立测试金线：为 auth、permission、remote、MCP、files、telemetry 定义强制用例和冒烟基线。
- 完整化交付材料：依赖清单、锁文件、CI、部署 IaC、运行手册必须进入上线审查范围。

## 6. 分阶段整改路线图

### 阶段 1（1-2 周）
- 禁用或严控非交互 `headersHelper`
- 为 `dangerously_skip_permissions` 增加服务端强校验和审计
- 修复 session log 401 被吞问题
- 降低 files API 默认并发并增加下载大小保护

### 阶段 2（2-4 周）
- 为远程会话、权限模式、MCP 鉴权、文件传输补齐测试
- 将 WebSocket/control message 改为 schema 校验
- 对 internal telemetry 做字段最小化与脱敏

### 阶段 3（1-2 个版本）
- 拆分 `main.tsx`、`mcp/client.ts`、`auth.ts`、`config.ts`
- 清退 deprecated 配置字段，建立统一 config layer
- 补齐依赖治理、SBOM、SCA、发布与部署审计链路

### 阶段 4（持续）
- 对高权限能力建立 threat modeling、变更评审与回归门禁
- 建立上线前安全检查表与稳定性检查表
- 引入告警、错误预算和运行后复盘闭环

## 7. 管理层摘要

- 该项目当前最值得管理层关注的，不是“代码写得对不对”，而是“高权限能力边界是否可控”。目前答案是不完全可控。
- 如果近期要上线，建议把 `headersHelper` 非交互执行、远程权限绕过、渠道自批准信任模型列为上线阻断项。
- 从交付治理看，当前快照缺失依赖与部署材料，意味着供应链和发布风险没有被完整评审，不能视为“审查已完成”。
- 从中长期看，项目具备产品能力和工程积累，但已出现典型复杂系统信号：超大核心文件、配置分散、旧新并存、测试不可见。若不治理，未来维护成本和变更事故概率会持续上升。
- 建议管理层以“先收权、再补测、后拆分”的顺序推进整改，而不是继续叠加功能。

## 补充说明

- 未在当前 `src/` 快照中发现可确认的生产 secrets、token、password 硬编码；但由于仓库不完整，只能给出“未发现，不代表不存在”的审计结论。
- 未发现直接 SQL/ORM 查询代码，数据库注入类风险在当前扫描范围内不突出。
- 监控与 telemetry 能力是存在的，例如 `src/services/analytics/datadog.ts`；但未见告警规则、仪表盘 IaC、SLO/SLA 材料，因此运维可观测性仍不能算“已闭环”。