### ADR-0003: OpenClaw 全面安全评估架构

**状态**: 提议（已采纳前四轮审计修订，详见 spec v1.4）
**日期**: 2026-04-25
**参与者**: roger, Claude

## 背景

AgentSec Phase 2 的首要目标是对 OpenClaw（开源个人 AI 助手）完成全面安全评估。2026 年 2-4 月间公开报道显示 OpenClaw 出现规模化的 CVE、互联网暴露实例与 ClawHub 供应链攻击（ClawHavoc）；具体数字随情报更新随时变动，因此本 ADR 不在正文中硬编码具体数字，威胁情报来源、口径、可信度、与测试用例映射统一维护在 [docs/specs/openclaw-evaluation.md §2](../specs/openclaw-evaluation.md) 的"威胁情报基线"章节。

威胁面横跨直接/间接 Prompt Injection、记忆投毒、工具滥用、Agentic Consent Bypass、认证绕过、SSRF、沙箱逃逸、多轮越狱等 10 个远程类别，以及 10 个服务器端 check（1 个 OpenClaw 原生审计接入 + 9 类自有检查：本地主动测试、配置基线、暴露面、日志、文件系统、Skill 静态分析、进程/网络取证、版本/补丁、凭证审计）。

现有 AgentSec 框架仅支持单轮 HTTP adapter + LLM-as-Judge 单评判器，无法覆盖此规模。需要架构升级。

完整设计细节见 [docs/specs/openclaw-evaluation.md](../specs/openclaw-evaluation.md)。

## 决策

1. **引入 Judge 抽象层与 Observation 模型**：在 `src/agentsec/evaluator/base.py` 新增 `Judge` ABC（async `evaluate(test, observation) -> JudgeVerdict`），提供 `LLMJudge`、`DeterministicJudge`、`HybridJudge` 三种实现；runner 负责采集 `Observation`（response、outbound_requests、fixture_events、tool_events、pre/post snapshot）并组装 `TestResult`。`TestCase` YAML 新增 `judge_type`、`assertions`、`turns`、`fixture`、`isolation`、`threat_refs` 字段。

2. **新增 server-audit 子系统**：在 `src/agentsec/audit/` 下实现独立的服务器端审计模块，包含 10 个 Check（1 个 OpenClaw 原生 `security audit --json` 接入 + 9 类自有检查）、IOC 数据库、结构化 SSH 命令策略（argv 列表、参数 schema、路径 allowlist、SFTP 写隔离）、PlatformProfile（Linux/macOS，结构化 argv）、全局 Redactor；通过新 CLI 命令 `agentsec server-audit` 调用。

3. **Adapter 注册表 + path 参数**：将 adapter 选择改为注册表模式；`HttpAgentAdapter` 增加 `path` 参数（默认 `/chat` 保持兼容），`OpenClawGatewayAdapter` 通过传入 `path="/v1/chat/completions"` 实现，避免硬编码端点。`agentsec run --adapter <name>` 支持插件式扩展，为后续 Telegram/Slack/微信/飞书 渠道铺路。

4. **多轮测试 + 隔离策略**：`TestCase.attack` 改为可选，与 `turns` 互斥（`@model_validator` 强校验）；loader 单轮自动转 `turns=[Turn(...)]`。多轮 / 投毒类用例默认走 `disposable` 隔离 profile，pre/post snapshot 入 `Observation`，清理失败时停止后续 destructive 用例。

5. **配置文件驱动综合评估 + 归一化评分**：新增 `agentsec evaluate --config <yaml>` 命令，单次执行远程 + 服务器端评估，输出三份报告 + 结构化 `findings.json` + `audit-log.jsonl` + `threat-intel-snapshot.yaml`。评分采用按类别归一化（远程）和 finding fingerprint 去重（服务器端），避免被用例数量与重复 evidence 放大。

6. **强制授权确认 + 安全边界**：evaluator 侧强制 `AUTHORIZATION.txt`（含 target_host/scope/valid_until/signature 强校验），可选要求 target 侧 marker 文件；SSH 命令策略升级为结构化（命令 + 参数 schema + 路径 allowlist + 输出大小限制 + shell 元字符禁止），所有 evidence 入 report 前过全局 Redactor 脱敏。

## 理由

- **Judge 抽象**：协议级判断（状态码、SSRF 阻断、IOC 匹配）用 LLM 评判既慢又不准；分层后让确定性检查走快路径，LLM 只做语义判断。
- **server-audit 独立模块**：服务器端检查的工作模式（SSH + 命令执行 + 结构化结果）和远程 send/judge 流水线本质不同，混在一起会让 runner 复杂化；独立模块清晰且可单独演进。
- **Adapter 注册表**：用户已明确后续要支持 Telegram/Slack/微信/飞书等多渠道；提前把扩展点做出来，避免后续每加一个渠道都要改 CLI。
- **多轮测试**：记忆投毒和多轮越狱是 P0 类别，单轮架构无法承载，必须现在重构。
- **授权确认**：服务器端审计能 SSH 进入目标机器，误用风险高；强制 `AUTHORIZATION.txt` 是合规与安全的兜底。

## 备选方案

- **方案 B（统一 adapter 抽象，SSH 也作为 adapter）**：体验统一但 SSH 与 HTTP adapter 差异过大，强行统一会让接口失去意义；放弃。
- **方案 C（前期就构建完整的 Profile 体系）**：扩展性强但前期成本高，当前只有 2 个 Profile 时收益不明显；演进式采纳——先做 Adapter 注册表（C 的核心扩展点），完整 Profile 体系留给 v1.x。
- **保留单 Judge（强行用 LLM 判断一切）**：实现简单但准确度无法满足协议级检测；放弃。

## 后果

**正面**
- 一次评估覆盖远程 + 服务器端 + 综合评分，对接 CI 友好。
- Judge 抽象后，新增确定性检查不再受 LLM 配额制约。
- Adapter 注册表让新渠道接入是"加文件"而非"改框架"。
- IOC 数据库与 CVE 数据库可独立更新，威胁情报可持续追加。

**负面 / 权衡**
- v1 改动面较大：`runner.py`、`judge.py`、`cli.py`、`adapters/http.py`、`tests/models.py` 都需要重构；估算约 6 周（详见 spec §10），含 0.5 周规格收敛 + 阶段 A-G 实施。
- 现有测试用例 YAML 需要回填 `judge_type` 字段（默认 `llm` 时无破坏性，但建议显式标注）。
- IOC 数据库初版手工维护，维护成本不低；vNext 小版本需对接自动化 feed。
- 服务器端审计需要 OpenClaw 实例的 SSH 凭证；强制授权文件 + 结构化命令策略 + 全局 Redactor 是合规代价，不可避免。
- 多轮 / 投毒测试要求 OpenClaw 暴露可程序化的 session/profile 隔离接口，否则需要落到 SSH 文件级 snapshot/restore，复杂度提升。

**对其他文档的影响**
- `ROADMAP.md`：Phase 2 内容需细化为 OpenClaw 评估的子任务清单。
- `CLAUDE.md`：需补充 Judge 抽象、server-audit 模块的约定（如 SSH 命令白名单）。
- `CHANGELOG.md`：v0.2.0 发版条目。
