# OpenClaw Evaluation 文档审计结果

**审计日期**: 2026-04-25  
**审计对象**:

- `docs/adr/0003-openclaw-comprehensive-evaluation.md`
- `docs/specs/openclaw-evaluation.md`

**总体状态**: 需要修改后再实施  
**审计口径**: 架构一致性、实现可落地性、安全边界、CLI/报告契约、威胁情报可追溯性。

## Findings 摘要

| ID | 严重度 | 位置 | 结论 |
|---|---|---|---|
| OE-AUD-001 | High | ADR:9, Spec:22 | 威胁情报数字缺少来源和统计口径，部分暴露规模与抽样公开来源不一致 |
| OE-AUD-002 | High | ADR:29, Spec:290-306 | 授权文件位置和签名强制性不一致，无法作为合规 gate |
| OE-AUD-003 | Critical | Spec:170-187 | SSH 命令白名单按命令名放行，缺少参数、路径、输出和脱敏约束 |
| OE-AUD-004 | Critical | Spec:57-83, Current code | `Judge` 新接口与当前 `LLMJudge`/`runner` 返回模型不兼容 |
| OE-AUD-005 | High | Spec:100-123, Current code | OpenClaw adapter 示例与当前 `HttpAgentAdapter` 固定 `/chat` 端点冲突 |
| OE-AUD-006 | High | Spec:124-140, Current code | 多轮 `turns` 与当前 `TestCase.attack` 必填模型冲突，缺少迁移校验 |
| OE-AUD-007 | High | Spec:236-239 | fixture server 绑定 `127.0.0.1` 时，服务器端 active test 拓扑未定义 |
| OE-AUD-008 | High | Spec:30, 215-234 | 记忆投毒和多轮测试缺少状态隔离、回滚和清理要求 |
| OE-AUD-009 | Medium | Spec:323-339 | 综合评分按失败数量扣分，容易受用例数量和重复 findings 影响失真 |
| OE-AUD-010 | Medium | Spec:142-168 | 未设计接入 OpenClaw 原生 `security audit --json`，存在重复建设风险 |
| OE-AUD-011 | Medium | Spec:39-51, 397-402 | server-audit 跨 Linux/macOS 但命令和路径偏 Linux，OS 抽象不足 |
| OE-AUD-012 | Medium | ADR:53-57, Spec:371-382 | ADR 估算 3-4 周，规格估算 5.5 周，计划口径冲突 |
| OE-AUD-013 | Medium | Spec:310-321, Current report code | 报告输出缺少统一脱敏与保留策略，可能把响应或 evidence 中的 secret 写入报告 |
| OE-AUD-014 | Low | ADR:59-62, ROADMAP/CLAUDE/CHANGELOG | 影响文档已列出，但缺少同步任务和验收点 |

## 详细发现

### OE-AUD-001: 威胁情报缺少来源和口径

**严重度**: High  
**证据**: ADR 第 9 行写 137+ 安全公告、22 万暴露实例、1,184+ 恶意 skill；规格第 22 行重复引用 137+ 与 1,184+，但没有来源表、统计日期或可信度。

抽样核验显示公开资料中的暴露规模存在多个口径，例如 40,214、63,026、135,000+ 等。22 万这个数字本次未能确认来源。CVE 与 ClawHavoc 数字也需要区分“历史识别”“仍可访问”“受影响版本”“已修复版本”。

**建议**: 在规格新增“威胁情报基线”章节，列出 source、URL、observed_at、claim、confidence、mapped_tests。ADR 只保留摘要和链接。

### OE-AUD-002: 授权 gate 位置和强度不一致

**严重度**: High  
**证据**: ADR 第 29 行要求目标项目目录存在 `AUTHORIZATION.txt`；规格第 290-306 行把 `consent_file` 写成 evaluator 配置里的 `./AUTHORIZATION.txt`，并说签名“可选”。

如果授权文件位置不明确，`server-audit` 可能只验证本地文件而没有目标侧确认。签名可选也削弱了审计留痕的可信度。

**建议**: 统一为 evaluator 侧强制 consent file，并可选要求 target 侧 marker。`target_host`、`scope`、`valid_until` 必须强校验；签名要么强制，要么明确标注为低保证模式。

### OE-AUD-003: SSH 白名单不足以保证只读安全

**严重度**: Critical  
**证据**: 规格第 175-179 行允许 `cat`、`grep`、`find`、`openssl` 等命令；第 180-183 行只用正则禁止部分元字符和危险命令。

命令名白名单不能限制参数能力。`find` 可执行 `-exec` 或删除动作，`grep -R` 和 `cat` 可读取超范围敏感文件，`openssl` 可用于网络连接。正则注释“除引号内”也不是简单正则能可靠实现的行为。

**建议**: 用 `shlex`/结构化命令 AST 校验参数；增加路径 allowlist、禁止参数表、最大输出大小、超时、脱敏规则；所有 evidence 入报告前必须统一 redaction。

### OE-AUD-004: Judge 抽象与当前 runner 不兼容

**严重度**: Critical  
**证据**: 规格第 61-68 行定义 async `Judge.evaluate(...) -> JudgeVerdict`；当前 `src/agentsec/evaluator/judge.py` 的 `LLMJudge.evaluate()` 是同步方法并直接返回 `TestResult`；当前 `src/agentsec/runner.py` 第 23-24 行只传 `response.content` 给 judge。

这会阻塞实现：deterministic/hybrid judge 需要 HTTP raw、headers、fixture events、outbound requests、tool events，而当前 runner 只给字符串。

**建议**: 先引入 `JudgeVerdict` 与 `Observation`；runner 收集 observation 并组装 `TestResult`；LLMJudge 可先保持同步内部实现，但外部接口统一 async。

### OE-AUD-005: OpenClaw adapter 示例与当前 HTTP adapter 冲突

**严重度**: High  
**证据**: 规格第 103-119 行示例只覆写 `_build_request` 与 `_parse_response`；当前 `HttpAgentAdapter.send()` 固定 POST `{base_url}/chat`。OpenClaw 规格要求 `/v1/chat/completions`。规格示例还返回 `AgentResponse(text=...)`，而当前模型字段是 `content`。

**建议**: 规格明确 `HttpAgentAdapter` 增加 `path` 参数，或 `OpenClawGatewayAdapter` 覆写 `send()`；示例统一使用 `AgentResponse(content=..., raw=...)`。

### OE-AUD-006: 多轮 schema 需要 Pydantic 迁移策略

**严重度**: High  
**证据**: 规格第 133-137 行要求 `attack` 与 `turns` 互斥且必有其一；当前 `src/agentsec/tests/models.py` 第 15-25 行将 `attack: str` 定义为必填字段。

如果直接添加 `turns`，多轮 YAML 仍会因为缺少 `attack` 无法加载。

**建议**: 将 `attack` 改为 `str | None`，增加 model validator；loader 将单轮转换为 `turns=[Turn(attack=...)]`，并增加兼容性测试。

### OE-AUD-007: fixture 与 server active test 拓扑未定义

**严重度**: High  
**证据**: 规格第 238 行要求 fixture server 绑定 evaluator 本地 `127.0.0.1:0`；规格第 43 行 server-audit 要在目标机器 localhost 重跑远程 10 类。

当 active test 在目标机器或通过 SSH 隧道执行时，目标机器访问不到 evaluator 的 `127.0.0.1` fixture。间接注入、SSRF 和 outbound assertion 都依赖这个拓扑。

**建议**: 明确三种模式：evaluator-to-target、ssh-port-forward、target-local-fixture。默认应使用 SSH 反向/正向隧道或在 target 侧临时启动 fixture，并写入清理步骤。

### OE-AUD-008: 记忆投毒和多轮攻击缺少隔离清理

**严重度**: High  
**证据**: 规格第 30 行将 MEMORY/SOUL 持久化污染列为 P0；第 215-234 行给出多轮保存记忆示例，但未定义 session namespace、memory reset、pre/post snapshot、清理失败处理。

这类测试会故意尝试持久化污染，若跑在真实实例上可能影响后续测试或生产状态。

**建议**: 为每个测试创建唯一 session namespace；测试前后采集 memory/config snapshot；默认在 disposable profile 上运行持久化类用例；清理失败时报告 `error` 并停止后续 destructive tests。

### OE-AUD-009: 评分模型会被数量放大

**严重度**: Medium  
**证据**: 规格第 327-338 行按每个 failed/finding 扣分，remote 约 135 条用例，server-audit findings 数量未封顶。

不同类别用例数量不同，重复 evidence 也可能生成多条 findings，导致分数不能反映真实风险优先级。

**建议**: 远程按类别先归一化，server-audit 按唯一 finding 指纹去重；引入 `skipped`、`error`、`not_applicable`；报告同时展示分数和置信度。

### OE-AUD-010: 未复用 OpenClaw 原生安全审计

**严重度**: Medium  
**证据**: 规格第 142-168 行设计全新 server-audit checks，但没有提到 OpenClaw 官方已有 `openclaw security audit --json`。

原生审计包含配置、危险 flag、权限、SecretRef 等项目。完全绕开会增加维护成本，也可能漏掉官方新增检查。

**建议**: 将 native audit ingestion 作为 server-audit 第一个 check，解析 JSON 并映射为 AgentSec `Finding`；AgentSec 自有 checks 专注补充远程攻击、IOC、日志和取证。

### OE-AUD-011: OS 抽象不足

**严重度**: Medium  
**证据**: 规格第 397-402 行声明支持 Linux/macOS，不支持 Windows；但检查项里使用 `ss`、`systemd`、Linux 风格路径，同时又提到 `launchd`。

**建议**: 增加 `PlatformProfile`，为 Linux/macOS 分别定义命令、路径、服务管理、日志位置和权限解释。不可用检查返回 `not_applicable`，不是失败。

### OE-AUD-012: 工期估算冲突

**严重度**: Medium  
**证据**: ADR 第 54 行估算 3-4 周；规格第 382 行总计 5.5 周。

**建议**: ADR 改为引用规格估算，或写“初步估算，详见规格”。规格建议更新为 6 周左右，并把规格收敛作为阶段 0。

### OE-AUD-013: 报告和审计日志缺少脱敏策略

**严重度**: Medium  
**证据**: 规格第 314-320 行输出 `findings.json` 与 `audit-log.jsonl`；当前 Markdown report 会写入 agent response 摘要。文档没有说明 token、API key、SSH key、cookie、session transcript 如何脱敏。

**建议**: 增加全局 `Redactor`，覆盖 response、raw JSON、SSH output、log snippets、fixture events。审计日志保存命令和元数据，默认不保存完整敏感输出。

### OE-AUD-014: 关联文档影响缺少执行任务

**严重度**: Low  
**证据**: ADR 第 59-62 行列出 `ROADMAP.md`、`CLAUDE.md`、`CHANGELOG.md` 影响；当前 `ROADMAP.md` Phase 2 仍是 Adapter 生态，和 OpenClaw 综合评估目标不一致。

**建议**: 在规格任务拆分里增加“文档同步”验收项：ROADMAP 调整 Phase 2，CLAUDE 更新新架构约定，CHANGELOG 在 v0.2.0 落地时补条目。

## 审计结论

当前文档适合作为 OpenClaw 综合评估的方向草案，但不适合直接进入实现。建议先处理 Critical 与 High findings，再按升级报告中的阶段 0-A-B 顺序推进。

最小可实施闭环是：

1. 固定核心模型和 adapter contract。
2. 完成授权、脱敏和 SSH policy。
3. 实现 OpenClaw remote 评估和少量 P0 deterministic assertions。
4. 接入 OpenClaw 原生 `security audit --json`。
5. 再扩展 9 类 server checks 与完整测试矩阵。
