ADR-0002: 工具治理安全模型

• 状态：Accepted
• 日期：2026-04-14
• Owner：colony-harness maintainers

背景

AI Agent 在执行任务时需要调用外部工具（shell 命令、文件读写、网络请求等）。无约束的工具执行存在安全风险：

• 误执行破坏性命令（rm -rf、mkfs）
• 凭证泄露或越权访问
• 缺乏审计轨迹导致事后无法追溯

需要一套默认安全的工具治理模型，在不牺牲灵活性的前提下将风险降至最低。

决策

1. allowlist-first 默认策略：run_command 工具默认使用白名单模式，仅允许 node、pnpm、npm、npx 四个命令。未显式允许的命令一律拒绝。
2. 风险分级体系：所有命令按 high / medium / low 三级分类：
   • high（默认：rm、sudo、mkfs、shutdown、reboot、dd、curl、wget、ssh、scp）：需要显式审批。
   • medium（默认：bash、sh、node、python、pnpm、npm、npx、git）：可通过配置要求审批。
   • low：其余命令。
3. 审批回调机制：HarnessBuilder.toolApproval(callback) 允许接入方自定义审批逻辑。高风险工具（requiresApproval: true）在执行前必须通过回调。
4. 强制审计字段：每次工具执行结果附带 audit 元数据（命令、参数、工作目录、模式、风险等级、时间戳、耗时）。
5. 文件沙箱：read_file / write_file 工具通过 baseDir + 路径遍历检测限制可访问范围。
6. Shell 执行默认禁用：allowShell 默认为 false，防止命令注入。

后果

正向收益：

• 未配置的工具调用默认被拒绝，符合最小权限原则
• 高风险操作必须经过审批，降低误操作和滥用风险
• 审计轨迹支持事后追溯和合规审查
• 接入方可根据业务需求灵活调整策略

成本：

• 默认策略可能过于保守，需要用户显式放宽（这是刻意的设计选择）
• 审批回调需要接入方实现，增加了集成复杂度

变更流程

• 新增默认白名单命令需评估安全影响后方可添加。
• 风险等级调整必须更新本 ADR。
• 新增需要 requiresApproval 的工具必须在工具文档中标注风险等级。