Songhaoz666andClaude Opus 4.8
54cb327348
- 基准标准 v2.1：SwarmMetrics（15 字段）、τ/η/P_decision/reward 公式、对称 G_E,c（修正 C_base=1.0 退化）、Σλ=1.0 校验；新增基线对比与运行记录 schema；指标覆盖缺口分析；参考系数暂留为元数据（待量化）。 - 主控 Agent 实体（分解 / 评审决策 / 汇总）；事件契约修正（timeline.title、budget.threshold_pct、handoff 角色、task.released）+ 契约校验脚本。 - 实质性 LLM 对等回复（含降级回退）；集成契约（runtime / event / usage / audit / frontend / capability / security）；CLIENT_GUIDE 客户端指南；CI 工作流；治理与交付文档。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5.5 KiB
5.5 KiB
安全边界（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）。
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 定义。
9. 覆盖与缺口
| 边界 | 状态 |
|---|---|
azkv:// secret_ref 强校验 / 明文拒绝 / 脱敏 / .gitignore |
✅ 已实现（本仓） |
| Workspace 路径越界校验 | ✅ 已实现 |
| 审批状态机（waiting_approval + approvals 回执） | ✅ 已实现（逐项校验待加强） |
| 短期凭证派生注入、Workload Identity | 🟡 AM/K8s 侧 |
| Tool/MCP 权限引擎 | 🔴 未实现 |
| allowed_paths 运行时强制、强隔离 | 🔴 未实现 |
| 强化执行沙箱 | 🔴 未实现 |
| 租户隔离 | ⛔ 不在本仓（归因按 user/channelId） |
10. 待对齐对象
Security / Governance Team（tool/MCP 边界、沙箱、审批逐项校验）、Infra Team（Workload Identity、租户隔离、egress 策略）。