Files

T

Songhaoz666andClaude Opus 4.8 a289495823 复审整改(PR #24 )：沙箱 fail-closed 隔离门控 + 可回放 DecisionTrace

回应 Fasthei 的 Request changes 两个阻塞项：

1) 安全 / fail-closed 沙箱隔离（原仅靠 ENABLE_QUALITY_EVAL + 运维约定）：
   - 新增第二道显式确认 HEICODE_SANDBOX_ISOLATED（断言运行在隔离 Pod 内）。
   - sandbox.run_tests() 与 quality.evaluate_run_quality() 执行任何代码前调用
     assert_isolated()，未确认即抛 SandboxIsolationError——不写文件、不起子进程。
   - 启动期 assert_quality_eval_safe()：ENABLE_QUALITY_EVAL 开但隔离未确认 → 拒绝启动
     （平台级硬失败，非运维口头约定）。
   - 文档（security-boundary §8.1/§9、CLAUDE.md）与测试同步：test-sandbox/test-quality
     先断言未确认时硬失败，再显式确认后继续。

2) #10 DecisionTrace 可回放（原仅存被选中任务的标量）：
   - Decision 现记录完整重放上下文：整个候选集（每候选 tau/eta/weight/p_norm/dependents）、
     alpha/beta/epsilon、seed、free_slots、total_weight、explore_draw、select_pick、
     select_index、explored 分支。
   - 新增 DecisionEngine.replay_decision(trace)：仅凭一条 trace（无 RNG/活体状态）复现被选任务；
     test-decision-engine 断言「重放==实选」跨 50 次决策（探索+利用）成立。
   - decision-engine.md §3.3 更新为可回放 DecisionTrace。

附：新增 docs/TESTING.md（reviewer 速查：依赖安装 + 每套测试命令，复审者此前因缺 fakeredis
未能跑到断言）。本地 11 项 gate 全绿。

影响范围：Swarm（orchestrator + 测试 + 文档）。不改 Manager↔Swarm 契约；新增开关
HEICODE_SANDBOX_ISOLATED（默认未设=拒绝执行）。仍非验收：gain/Benchmark_Agent 仍 NaN。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-10 13:22:54 +08:00

8.1 KiB

Raw Blame History

安全边界（Secret / Workspace / Tool / Approval / Tenant / Sandbox）

状态：部分已实现，部分待接入（依据 heicode-mananger/docs/heicode.md §六/七、docs/heicode-runtime-auth-newapi-secret-design.md §三/五、docs/integration/heicode-am-contract.md §3.1/§4）。

配套：runtime-contract.md、usage-billing-schema.md。

1. 不可破坏原则

密钥/Token/云凭据/SSH 私钥/数据库密码/NewAPI key 不得进入代码、日志、Markdown、前端响应或 Git。
凭据基线 = Azure Key Vault；引用一律 azkv://<vault>/secrets/<name>，不向后兼容 vault://。
Manager DB 与 Swarm 只保存 secret_ref，真实凭证由 Secret Broker 写入 Key Vault。
子 Agent 不持有长期密钥；只接收角色、资源元数据、AGENT.md 与短期、最小权限、可审计凭证。
高危操作审批只在客户端完成；运行时只校验审批结果，不发起审批。

2. Secret 注入边界

项	标准	本仓状态
`secret_ref` 前缀 `azkv://` 强校验	必须	✅ `swarm_runtime.validate_create_request` 校验 `billing_context.secret_ref` 等为 `azkv://`
拒绝明文密钥进入请求	必须	✅ `_reject_plaintext_secrets`（`metadata`/`resource_grants`/`callback`）
响应/事件/持久化脱敏	必须	✅ `_redact_sensitive` 将明文密钥键（`password`/`token`/`secret`/`private_key`/`access_key` 及 `_token`/`_secret`/`_password`/`_key`）脱敏为 `[redacted]`；保留 `secret_ref`/`credential_ref`/`signing_secret_ref`（安全引用）
`.env`/密钥不入库	必须	✅ `.gitignore` 忽略 `.env`、`secrets/`、`*.pem/key/p12/pfx`、`id_rsa/ed25519`
真实凭证写入 Key Vault（Secret Broker）	Manager 侧	⛔ 非本仓（Manager Secret Broker 负责）
短期凭证派生与注入	客户端审批后	🟡 Swarm 接收 `secret_context`；K8s 派生/注入由 Agent 平台（AM）实现

secret_context（HM 下发，仅引用与审批结果）：

"secret_context": {
  "secret_refs": ["azkv://heicode-kv.vault.azure.net/secrets/res_git_1"],
  "inject_short_lived_credentials": true,
  "approval_id": "approval_123"
}

3. Workspace 隔离

每个任务在独立按任务工作目录执行（agent task_workspace）。
文件写入有路径越界校验（task_executor._resolve_workspace_path，拒绝绝对路径与逃逸 workspace）。
Git 操作在仓库根（repo_root）执行，限定结果分支。
🟡 待接入：跨任务/跨租户的强隔离、只读挂载、allowed_paths 强制（当前由模型提示约束，未做运行时强制）。

4. Tool / MCP 权限边界

当前 Agent 工具能力 = 工作区内文件读写 + Git；无 SK/MCP 工具权限引擎。
🟡 待接入：统一 tool/MCP permission boundary、allowed/denied 工具策略、敏感工具审批联动（sk_tool.* 事件已在 schema 预留）。

5. 审批门（Approval Gate）

高危操作审批只在客户端；Swarm 不发起审批。
Swarm 实现：create 命中高危（risk_level=high 或 requires_user_approval）→ 进入 waiting_approval，发 approval.requested（approval_id/operation/risk_level）；客户端经 Manager 审批后回 POST …/approvals/{approval_id}（approved/rejected）→ 恢复或阻断。
🟡 待接入：审批主体/范围/TTL/credential_ref/lease_id 的逐项校验与到期失效，需与 Manager 审批链对齐。

6. Agent 鉴权与租户隔离

Swarm 模型：Agent 主动出站连编排器 WebSocket（/ws/{agent_id}），不对公网暴露每 Agent 子域名。AM 单 Agent 模型里的「客户端↔agent 直连 + AGENT_ACCESS_TOKEN 本地校验」不适用于 swarm（无直连回路）。
服务间鉴权：HM→Swarm 用 AGENT_RUNTIME_SERVICE_TOKEN（Bearer）；回调 HMAC 签名。
🟡 待接入：多租户运行时隔离（命名空间/网络/配额）由 Agent 平台（AKS Workload Identity）承载，非本仓编排器；归因主轴为 user.id/channelId（见 usage-billing-schema.md），不引入 tenant 概念。

7. 外部 API 与传输

模型调用统一走 HM /v1（OpenAI 兼容），用 HM 现签 OPENAI_API_KEY。
传输：编排器/Agent 接口与回调走 HTTPS / 私网；env 含明文密钥时启动接口必须 HTTPS（heicode-am-contract §4）。
🟡 待接入：统一 external API egress 策略（白名单/出网控制）。

8. 执行沙箱

当前执行单元为进程 / K8s Pod，隔离强度依赖部署（namespace/资源限额）。
🟡 待接入：强化沙箱（seccomp/只读根/网络策略/能力裁剪），由 Infra/Security Team 定义。

8.1 代码测试沙箱（benchmark Group B，`orchestrator/sandbox.py`）

为给「生成代码」算真实 TestPassRate，需执行模型生成的代码。安全模型与边界如下：

OS 级隔离边界 = K8s Pod / 容器（非 root、只读根文件系统、NetworkPolicy 出网拒绝、CPU/内存/pids 限额、seccomp），由部署侧（Manager/release 清单）强制，非本仓可改。按 Owner 裁定，在该隔离 Pod 内运行测试代码可接受。
Pod 内纵深防御（本模块新增）：每次运行用临时工作目录（结束即删）；wall-clock 超时 + 进程组强杀；POSIX 资源限额（CPU 时间 / 地址空间 / 文件大小 / 子进程数，见 SANDBOX_* 环境变量）；环境变量清洗（不向子进程泄漏任何 API Key/Token/云凭据/代理变量，仅放行 PATH/语言区域等白名单）；写入路径越界校验（拒绝绝对路径与 .. 逃逸）；输出截断；计数从 JSON 结果文件读取，不信任 stdout。
Fail-closed 双重门控（PR #24 复审整改）：代码执行不是「一个 env 开关就能开」的默认能力。需要两道独立确认：
1. ENABLE_QUALITY_EVAL=1 —— 打开质量评测功能；
2. HEICODE_SANDBOX_ISOLATED=1 —— 显式断言本进程运行在上述隔离 Pod 内（由 Pod manifest / CI runner 设置）。二者缺一：
- 启动时：若 ENABLE_QUALITY_EVAL 开但隔离未确认，orchestrator 拒绝启动（assert_quality_eval_safe()，main 生命周期）——平台级硬失败，非运维口头约定。
- 运行时：sandbox.run_tests() 与 quality.evaluate_run_quality() 在执行任何代码前调用 assert_isolated()，未确认则 抛 SandboxIsolationError，不写文件、不起子进程。评测仅用 benchmark/fixtures/<id>/ 的留出测试（held-out）作权威评分。
明确不构成：本模块不是独立安全边界，不替代 §8 的强化沙箱（seccomp/只读根/网络策略仍由 Infra/Security 在 Pod 层强制）。HEICODE_SANDBOX_ISOLATED 是「操作者确认隔离已就位」的断言，不自行创造隔离；只允许在真正隔离的 Pod 或 ephemeral CI/test runner 中置 1。后续可演进为专用 sandbox worker/job（复审建议的另一路径）。

9. 覆盖与缺口

边界	状态
`azkv://` `secret_ref` 强校验 / 明文拒绝 / 脱敏 / `.gitignore`	✅ 已实现（本仓）
Workspace 路径越界校验	✅ 已实现
审批状态机（waiting_approval + approvals 回执）	✅ 已实现（逐项校验待加强）
短期凭证派生注入、Workload Identity	🟡 AM/K8s 侧
Tool/MCP 权限引擎	🔴 未实现
allowed_paths 运行时强制、强隔离	🔴 未实现
代码测试沙箱（Pod 内纵深防御 + 环境清洗 + 超时/限额；fail-closed 双门控 `ENABLE_QUALITY_EVAL` + `HEICODE_SANDBOX_ISOLATED`，启动/运行时硬失败）	✅ 已实现（本仓，§8.1）；OS 级隔离仍依赖 Pod
强化执行沙箱（seccomp/只读根/网络策略/能力裁剪，Pod 层）	🔴 未实现（Infra/Security）
租户隔离	⛔ 不在本仓（归因按 user/channelId）

10. 待对齐对象

Security / Governance Team（tool/MCP 边界、沙箱、审批逐项校验）、Infra Team（Workload Identity、租户隔离、egress 策略）。

8.1 KiB Raw Blame History Unescape Escape