IronClaw 安全与沙箱规则解析Agent OS 的中介边界、零暴露凭证与真实 OS 隔离【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw本指南系统讲解 IronClawReborn作为 Agent OS 的安全与沙箱边界模型从中介即边界的顶层设计、零暴露凭证机制、转换前验证原则、有界资源策略到沙箱不变量以及以 issue #6170 跨租户文件泄露事件为戒确立的按租户真实 OS 隔离进程执行模型。读完本文你将理解 IronClaw 如何让不受信任的输入始终无法获得环境级权限掌握ProcessBackendKind、DeploymentMode、SandboxCommandTransport等核心类型的语义与 fail-closed 推理并学会用文中给出的rg命令在仓库中复核安全边界接线。规则文档定位与适用边界本文依据仓库中的安全规则文档 .claude/rules/safety-and-sandbox.md 展开。该规则是一份带路径作用域的Reborn safety and sandbox rules其生效范围覆盖以下 crate 目录即所有涉及安全边界的代码均须遵守crates/substrates/ironclaw_network/**网络出站crates/substrates/ironclaw_secrets/**密钥存储crates/substrates/ironclaw_safety/**检测与脱敏原语crates/kernel/ironclaw_host_runtime/**宿主运行时crates/kernel/ironclaw_processes/**进程生命周期crates/lanes/ironclaw_sandbox/**沙箱执行通道crates/lanes/ironclaw_wasm/**、crates/lanes/ironclaw_mcp/**crates/product/ironclaw_webui/**crates/contracts/ironclaw_prompt_envelope/**提示词信封这套规则不是孤立的代码审查清单它与仓库中多个契约文档和 crate 互为印证进程生命周期契约见 docs/internal/reborn/contracts/processes.md沙箱通道的实现与约束见 crates/lanes/ironclaw_sandbox/README.md检测与脱敏原语见 crates/substrates/ironclaw_safety/README.md。原则一中介即边界Mediation is the boundary规则的第一条也是最根本的一条不受信任的输入永远不能获得环境级的文件系统、网络、进程、密钥或凭证权限。执行必须跨越四道关卡类型化的宿主 APItyped host APIs——所有能力调用都经过定义在契约层、由内核实现的端口授权authorization——由ironclaw_authorization判定调用者是否有权义务obligations——能力调用需满足的脱敏、限流等附带义务资源预留resource reservation与归属运行时适配器owning runtime adapter——由拥有该能力的运行时负责最终落地。具体到执行路径外部 HTTP 出站必须经过ironclaw_network禁止手工注入凭证或私自构造第二条出站 HTTP 通道。从 crates/contracts/ironclaw_host_api/src/runtime_policy.rs 可以看到网络策略的完整枚举NetworkModeDeny禁止出站、Brokered仅经网络代理、Allowlist仅允许白名单、DirectLogged直连且全量记录、Direct直连不逐请求记录仅限受信任的本地 profile。密钥保持加密且驻留宿主侧运行时代码拿到的是引用或中介后的效果references or mediated effects而不是原始值。这一点与ironclaw_secretscrate 的分工直接对应——规则明确持久化加密密钥材料只能放在 secrets 子系统。换句话说中介mediation是整个安全模型的分界凡是要触碰环境的能力都必须被内核转手一次而不能让 Agent 或扩展直接摸到底层资源。原则二零暴露凭证Zero-exposure credentials零暴露不是指凭证不存在而是指凭证材料永不离开宿主侧加密的密钥材料只持久化在ironclaw_secrets子系统能力capabilities、运行时通道lanes、容器、事件、日志、模型上下文携带的只能是凭证引用或脱敏元数据宿主在最窄的出站边界narrowest egress boundary解析并注入凭证同时从返回的错误、URL、请求头、请求体、保存的进程输出中移除凭证。仓库实现中有一个非常典型的佐证进程执行通道的凭证绑定类型。在 crates/contracts/ironclaw_host_api/src/process.rs 中SandboxCommandCredentialBinding只包含placeholder_env占位符环境变量名和RuntimeCredentialRequirement来自授权能力描述符的凭证要求调用者无法通过这个类型直接提供原始凭证材料CredentialedSandboxCommandRequest的文档注释写得很直白沙箱收到的是随机占位符真实凭证材料留在代理侧The sandbox receives random placeholders; real credential material remains proxy-side。沙箱侧的实现进一步落实了这一设计crates/lanes/ironclaw_sandbox/src/sandbox_process/credential_firewall.rs描述的 W8 凭证防火墙是一个义务暂存关口obligation-staging chokepoint——调用者先暂存一次调用有权获得的凭证消费方只能看到是/否的答案永远无法绕过它自行铸造授权。其失败语义也被刻意设计成两种不同的错误形态防止调用者把二者折叠成一个意外的 fail-open 分支NoGrant连接已建立且已归属、但没有存活授权 → 去掉占位符裸转发让源站自己的 401/403 作决定连接归属失败或查询超时 → 直接拒绝连接绝不转发。此外规则要求进程启动必须使用白名单化/擦洗后的环境allowlisted/scrubbed environment绝不把宿主的完整环境继承进运行时通道或扩展进程。这与沙箱计划typed policies and minimal mounts的要求一脉相承。原则三转换前验证Validate before transformation规则要求每一个入口ingress在存储、提示词构造、URL 解析、凭证注入或派发之前先对原始载荷做验证和边界约束。其核心逻辑是先验证原始数据再做归一化/转换否则归一化会掩盖危险内容。同时要保留信任类别trust class穿过提示词信封prompt envelope与结果处理并对模型可见的输出与用户可见的错误做净化但不丢弃服务端侧的根因。规则给出了完整的入口审查清单Ingress review checklist认证并绑定 actor/tenant 作用域在分配或解析扇出allocation or parsing fan-out之前先对 body/文件/数量/深度设上限在归一化隐藏危险内容之前先验证原始数据附件必须走共享附件边界single landing routine见ironclaw_attachments在提示词构造之前先对信任类别分类拒绝客户端铸造受信任入站请求的企图只持久化验证后的表示并保留净化后的错误根因。URL 抓取是特殊场景先验证并授权原始 URL然后在解析之后、以及每一次重定向目标上重复执行验证、授权与泄漏扫描只有解析后的目标通过检查才允许注入凭证。脱敏义务redaction obligations是验证的延伸。规则明确能力参数、输出、provider 错误、进程结果默认即为敏感在日志、持久化事件追加、投影、SSE/WebSocket 投递、模型可见结果、用户可见错误之前必须应用所属的 Reborn 脱敏义务绝不允许在宿主中介结果之外平行地增加一条未脱敏的可观测路径。实现层面检测与脱敏原语集中在 crates/substrates/ironclaw_safety/README.md 描述的ironclaw_safetycrateSafetyLayer把 sanitizer validator policy engine leak detector 组合成一次调用redact_model_input_text不可失败的模型视图变换能识别常见凭证格式与password: letmein这类弱标记值含单引号/双引号/反引号包裹的完整值还能识别按偏移前缀拼接的字符转储——防止 shell 输出通过在每个字符间插入空白来绕过模型边界宿主路径替换为[REDACTED_HOST_PATH]超出有界解码器的编码 JSON 会 fail closedredact_model_input_url针对 userinfo 与凭证查询参数的 URL 感知脱敏行内data:图片载荷保持逐字节不变。同时该 crate 有两条硬性不变量检测是数据不是权威只分类、不决定谁能调用对不受信任输入做有界、线性时间匹配无回溯正则行为安全发现绝不记录或返回它检测到的原始材料。原则四有界资源Bounded resources用户可控的一切都要求显式上限文件、body、字符串、集合、扇出、队列、缓存、进程输出、并发任务。规则给出的做法包括大内容流式处理Stream large content使用有界队列/信号量bounded queues/semaphores与文档化的淘汰策略documented eviction缓存键必须包含所有影响授权、可见性或存储值的输入。对缓存还有一个必须自问的问题actor、tenant、scope、凭证账户、信任类别、运行时 profile、策略输入是否会改变缓存值如果会它就必须进入缓存键否则缓存必须位于该决策之下。规则进一步要求任何授权敏感的缓存都必须配有跨用户/跨作用域回归测试。原则五沙箱不变量Sandbox invariants规则为沙箱本身定下以下不变量沙箱计划使用类型化策略与最小挂载typed policies and minimal mounts——没有裸的容器 flag、宿主路径、环境继承或密钥材料穿过计划输入容器与外部服务始终视为不受信任Containers and external services remain untrusted安装与凭证执行是两个分离的阶段Install and credentialed execution are separate phases——对应ironclaw_sandbox中 typed install-plan 与 command-plan 的分离运行时通道不能绕过宿主中介的文件系统、网络、密钥、事件、进程或资源服务worker 进程返回的数据不受信任宿主必须验证能力身份与域、绑定到已授权的调用、强制执行服务端嵌套/深度与资源限制、重新应用敏感性与脱敏义务worker 提供的元数据不能授予权限也不能自证安全。针对改动规则要求测试必须覆盖拒绝denial、限额耗尽limit exhaustion、脱敏redaction、作用域隔离scope isolation、取消cancellation、清理cleanup并且要通过生产调用方through the production caller驱动。沙箱策略的改动还需额外测试挂载包含性mount containment、网络允许/拒绝network allow/deny、环境擦洗environment scrubbing、输出限制output limits、进程树取消process-tree cancellation、安装/运行阶段分离install/run phase separation、恶意 worker 元数据malicious worker metadata。原则六进程与 shell 执行——按租户的真实 OS 隔离这是规则中最关键、也最有历史教训的一节。它由issue #6170一个已发布的、经由shell的跨租户文件泄露漏洞直接驱动。规则因此强调三个容易被误解的事实事实一虚拟文件系统不包含子进程。ScopedFilesystem/MountView绑定的是文件系统能力filesystem.read这一虚拟路径抽象而被派生出的 OS 进程builtin.shell、脚本通道看到的是真实内核文件系统会忽略这些挂载。因此绝不能把 scoped/virtual 文件系统当作子进程的容器。这一点在 crates/lanes/ironclaw_sandbox/README.md 中同样被强调a virtual scoped filesystem view does not contain a subprocess。事实二OS 进程唯一真实的容器是它所在的沙箱。任何认证用户数大于一的部署都必须把进程派生路由到沙箱化端口UserSandboxProcessPort由ironclaw_sandbox支撑其挂载从 turn 作用域推导而来绝不走未沙箱化的HostProcessPort原LocalHostProcessPort改名Host命名即边界直接在宿主上运行的进程。HostProcessPort/ProcessBackendKind::LocalHost只允许用于真正的单用户本地部署。事实三部署模式必须反映多用户服务的现实。一个被服务的实例SSO 开启、准入UserId数大于 1、非 loopback 绑定不得解析到LocalSingleUser/ 宿主 shell 语义。#6170 的根因正是HostedSingleTenant组合 profile 声明了LocalSingleUser而健全的解析器忠实地把该 profile 映射成了未沙箱化的宿主 shell。规则因此禁止任何把被服务 profile 映射为宿主进程后端的 profile→mode 映射。Fail closed 兜底没有已验证的租户沙箱 ⇒ 进程/shell 能力被可见性过滤器隐藏、被规划器拒绝ProcessBackendKind::None绝不允许静默降级为宿主进程缺少 Docker/沙箱只能退化为没有 shell绝不能退化为宿主 shell。源码中的类型化支撑上述规则在契约层有完整映射见 crates/contracts/ironclaw_host_api/src/runtime_policy.rsDeploymentModeL66-L75LocalSingleUser个人机器上的单用户可承载Local*profileHostedMultiTenant多租户托管不能暴露宿主文件系统或 shellLocal*profile 会被解析器拒绝EnterpriseDedicated单组织专用基础设施。ProcessBackendKindL413-L429None完全禁用进程效果Docker/Srt/SmolVm容器 / 沙箱运行时 / 轻量 VMLocalHostprovider 宿主 shell仅限本地单用户UserSandboxwire 别名tenant_sandbox已认证租户边界内的每用户沙箱进程OrgDedicatedRunner单组织专用 runner。FilesystemBackendKindL372-L384则定义了文件系统后端的等级ScopedVirtual是安全默认只声明挂载不触及宿主路径HostWorkspace/HostWorkspaceAndHome仅在本地模式有效TenantWorkspace/OrgDedicatedWorkspace分别对应托管与专用场景——文件系统能力的宽度同样受部署模式约束。在 crates/contracts/ironclaw_host_api/src/process.rs 中进程执行被拆成内核决定走哪个端口、通道提供执行 transport两半ironclaw_sandboxruntimes 层实现SandboxCommandTransporttraitironclaw_host_runtimekernel 层把它包装进UserSandboxProcessPort。这样内核消费的契约形状与通道实现解耦且依赖方向保持向下。沙箱通道的真实执行形态从 crates/lanes/ironclaw_sandbox/README.md 可以看到生产接线profileHostedSingleTenantVolumeSandboxed一次builtin.shell调用在每个(tenant, user)一个的持久本地 Docker 容器里通过 Docker Exec 执行RebornSandboxUserKey提供稳定的容器名与 tenant/user 标签同一用户的所有线程收敛到同一容器宿主工作区按用户 scoped 并挂载到/workspaceexec 前 transport 会收养兼容的容器、重启兼容的已停止容器或回收镜像/安全姿态不匹配的容器每用户创建门per-user creation gate收敛并发首次调用active-exec 记账防止空闲清扫器在命令未完成时停止容器托管出站走每用户代理ironsh/iron-proxy边车worker 容器加入隔离网关模式的内部 Docker 网络代理的 DNS 与监听只绑定私有网络地址应用白名单、拒绝私网目的地、保留端到端 TLSSNI 检查、并写入与能力调用关联的请求审计轨迹容器被移除前审计日志会被排干到有界文件保证出站证据不随容器消失空闲清扫器只是窄范围的 provider 资源清理循环不改变ironclaw_processes的运行/生命周期状态——生命周期唯一权威仍是 docs/internal/reborn/contracts/processes.md 定义的ProcessJournalStore。组合解析与跨租户逃逸测试组合层crates/app/ironclaw_composition/src/deployment.rs承载 profile→(DeploymentMode, RuntimeProfile)的解析与测试其中就有ProcessBackendKind::LocalHost/None/UserSandbox的断言用例crates/app/ironclaw_composition/src/builtin_capability_policy.rs 则按后端类型分别构造能力策略。规则为任何触及进程端口、规划器的进程/文件系统后端规则、或 profile→mode 映射的改动设定了验收门槛必须有一个经由调用方驱动的双用户跨租户逃逸测试——用户 B 执行一条 shell 命令测试断言其无法读取用户 A 的文件。仓库中与此呼应的隔离测试广泛存在例如 crates/kernel/ironclaw_host_runtime/tests/memory_prompt_context.rs 中的宿主必须丢弃 provider 的跨租户/跨用户片段只保留作用域内片段断言以及 crates/kernel/ironclaw_host_runtime/tests/first_party_coding_tools.rs 中检查不得逃出沙箱策略到达本地宿主端口的用例。在仓库中复核安全边界规则文档为维护者提供了三条可直接执行的验证命令对应ironclaw_host_runtime、ironclaw_event_log、ironclaw_event_streams、ironclaw_composition、ironclaw_runtime_policy# 1) 复核脱敏边界是否在事件链路中被正确应用 rg -n redact_output|redaction|sanitize crates/kernel/ironclaw_host_runtime crates/events/ironclaw_event_log crates/events/ironclaw_event_streams # 2) 复核进程端口接线沙箱端口 vs 宿主端口、后端类型、部署模式 rg -n HostProcessPort|UserSandboxProcessPort|ProcessBackendKind::LocalHost|DeploymentMode::LocalSingleUser crates/kernel/ironclaw_host_runtime crates/app/ironclaw_composition crates/kernel/ironclaw_runtime_policy第一条命令检查是否存在未经脱敏的平行可观测路径第二条命令检查是否仍存在会把被服务 profile 解析到宿主进程后端的接线。这两条命令正对应 #6170 事故的两个教训可观测路径必须脱敏、进程后端必须与部署模式一致。总结IronClaw 的安全与沙箱规则可以浓缩为一句话一切执行都经过中介一切凭证都不落地一切输入先验证后转换一切资源都有界一切进程都有真实沙箱一切降级都 fail closed。六条原则层层嵌套——中介边界管住谁能碰、零暴露凭证管住碰到的只是引用、转换前验证管住碰之前先检查、有界资源管住能碰多少、沙箱不变量管住在什么容器里碰、按租户 OS 隔离管住多用户下进程真实落在哪。而 #6170 的教训提醒所有 Agent OS 的构建者组合 profile 的声明必须诚实反映部署的现实否则健全的解析器也会把危险映射当作忠实执行。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考