claude-flow/browser 安全审计全解ADR-122 七阶段浏览器基座的安全设计与验证【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo导读本文以仓库内claude-flow/browser包的安全审计报告SECURITY_AUDIT.md为核心骨架系统讲解 ADR-122feat/adr-122-browser-beyond-sotaPhases 0–7 引入的浏览器自动化子系统的安全设计与验证方法。你将掌握该包的依赖审查结论、七个阶段各自的威胁模型与防护机制Ed25519 见证签名、Cookie 保险库、会话胶囊、因果恢复存储等、危险模式扫描清单以及如何在源码层面对照验证这些审计结论。该包是 ruflo / claude-flow 生态中 Agent 浏览器自动化能力的基座其安全边界设计对任何构建 AI 浏览器代理的团队都具有直接参考价值。一、审计背景与范围claude-flow/browser3.0.0-alpha.4的安全审计于 2026-05-18 在 Phase 7 结束时自动执行审计范围覆盖 ADR-122 全部七个阶段新增的代码以及既有适配器adapter的暴露面。该包在仓库中的位置是 v3/claude-flow/browser核心职责是把agent-browser的能力接入 claude-flow 集群swarm并围绕浏览器会话这一高危资产构建可验证、可追溯、有策略约束的安全基座。从 package.json 可以看到它是一个 TypeScript ESM 模块运行时要求 Node.js ≥ 18其直接依赖只有三个依赖版本用途agent-browser^0.27.0浏览器自动化执行后端通过 CLI 子进程调用agentic-flow^2.0.13Agent 编排框架间接引入 AgentDB、嵌入等能力zod^3.22.4运行时数据校验所有域模型的 Schema 层审计的核心结论Summary是两句话ADR-122 的工作没有引入任何新的漏洞同时存在经由agentic-flow → agentdb → xenova/transformers、opentelemetry/*、sqlite3传入的传递性transitive漏洞但这些已在 ADR-118AIDefence与 ADR-121embeddings的修复工作中跟踪且没有任何一项会到达本包的运行时表面。二、直接依赖审查三个依赖的三种结论agent-browser^0.27.0—— 干净采用最新的上游版本且通过execFileSync以子进程方式生成不存在 shell 注入向量。这一点在 causal-recovery-store.ts 的classifyBreak()注释中也有印证——它解析的正是agent-browser/ Playwright 的 stderr 模式说明两者之间是进程 文本协议的松耦合边界而不是把用户输入拼进 shell 命令。agentic-flow^2.0.3—— 存在传递性发现问题经由xenova/transformers2.x传入。Xenova 项目已停止维护retirement对应迁移方案在 ADR-121 Phase 4 中跟踪计划迁移到ruvector-onnx-embeddings-wasm。zod^3.22.4—— 干净zod在本包中承担了所有域模型的入口校验本身没有发现安全问题。事实上zod 的 Schema 化正是本包多个阶段安全设计的基础详见下文。三、代码级审查七个阶段的威胁模型与防护机制这是审计报告的主体逐一对应 ADR-122 的七个实现阶段。下面每个阶段都结合仓库源码展开。Phase 1 —— Witness Signer 见证签名器 签名轨迹审计结论使用node:crypto的 Ed25519FIPS 验证路径无第三方加密库canonicalJSON跳过undefined键保证往返确定性有回归测试公钥重建使用静态 SPKI 前缀包裹裸 32 字节 hex不做动态密钥解析签名验证委托给 libcrypto 的verify(null, ...)为常量时间比较。源码印证witness-signer.ts规范的序列化函数canonicalJSON()第 43–51 行递归地对对象键排序并过滤值为undefined的键使得两个结构相等的载荷产生字节级一致的签名输入——否则签名会依赖 JSON 键的插入顺序无法在 JSON 解析往返后幸存。签名前先经过SignedTrajectoryPayloadSchema.parse()校验第 102 行保证绝不产出一个已签名但畸形的信封。验证时公钥重建第 150–153 行使用 RFC 8410 定义的 Ed25519 SPKI DER 前缀0x302a300506032b657003210012 字节拼接 32 字节裸公钥全程没有动态解析任何外部输入的密钥结构。信封本身的 Schema 定义在 signed-trajectory.ts载荷包含envelopeVersion字面量1.0.0、kind字面量browser-trajectory让验证者能拒绝非轨迹容器、trajectoryId、projectId联邦信任边界、publicKey严格 64 位 hex 正则、轨迹本体、截图内容哈希表screenshotHashes、以及可选的因果父轨迹parentTrajectoryId。签名必须是 128 位 hex算法字段限定字面量ed25519。验证函数verifyTrajectory()返回结构化结果而非抛异常第 119–174 行因为 CLI、MCP 工具、联邦对端摄取等调用方经常需要针对失败原因分别处置它分三步Schema 校验 → 信任列表校验若提供trustedPublicKeys→ 签名校验。密钥解析入口resolveWitnessKey()支持从环境变量RUFLO_BROWSER_WITNESS_KEY加载 PEM 私钥或生成临时密钥。Phase 2 —— Causal Recovery Store 因果恢复存储审计结论所有输入都经过SelectorBreakEventSchema的 zod 校验索引按 origin 隔离构造上杜绝跨域泄漏JSON-on-disk 变体使用mkdir({ recursive: true }) 原子写入语义。源码印证causal-recovery.ts causal-recovery-store.tsSelectorBreakEventSchema要求事件必须携带origin如https://example.com并将其作为因果图隔离键——listBreaks()按 origin 过滤getRisk()的风险分breaks.length / attempts也是 originselector 维度计算不存在跨域关联的可能。InMemoryBreakStore与JsonFileBreakStore通过IBreakStore接口解耦后端可在不改变调用方的前提下替换为 AgentDB 因果边 MCP 工具。classifyBreak()第 199–213 行把适配器报错文本映射到八种断链分类element-not-found、navigation-during-action、ref-stale、timeout等且特意把导航类错误判断放在最前避免frame detached被误判为普通 stale-element。文件损坏时load()直接以空状态启动第 171–179 行不会让 Agent 崩溃。Phase 3 —— Cookie Vault 带见证的 Cookie 保险库审计结论AIDefence 扫描门在持久化之前执行PII 内容永远不会到达条目存储sha256Hex(cookie.value)内容哈希校验意味着篡改 value 而不重新签名会被检测到纵深防御上即使签名有效cleanfalse的证明attestation也会被拒绝。源码印证cookie-vault-service.tsstore()第 95–151 行先调用this.scanner.scanContent(input.cookie.value, cookie: input.cookie.name)若扫描不干净则记录一条VaultRefusal审计记录并返回失败不写入任何条目。通过后生成ScanAttestation记录扫描器名称默认aidefence-bundled2.3.0、scannedAt、clean: true、piiCount: 0、threatCount: 0、以及contentHash sha256Hex(cookie.value)。verifyAttestation()第 157–232 行做了四层检查Schema → 信任列表 →拒绝clean: false的证明即使签名合法理由是扫描器根本不该在这种状态下产出已密封信封→内容哈希比对sha256Hex(payload.cookie.value)必须等于 attestation.contentHash防止篡改 value 后忘记更新哈希→ 最终 Ed25519 签名验证。域模型在 cookie-vault.tsScanAttestationSchema明确要求piiCount/threatCount为非负整数contentHash为 64 位 hexVaultRefusalSchema记录了每次被拒写的时间、来源、cookie 名、原因与计数构成完整的审计轨迹。Phase 4 —— Federated MCTS 联邦蒙特卡洛树搜索审计结论来自对端的轨迹信封在贡献任何分数之前必须验证签名失败的对端在本次运行中进入黑名单每次execute()调用前强制按对端预算上限约束本包不做任何到对端 URL 的裸fetch()——PeerAdapter只是接口传输是联邦层ADR-097/104的职责。这一点值得强调安全边界的归属。包内只定义接口与策略预算、信任、验证顺序不自行实现传输从而把对端地址是否可信、连接是否加密这类问题收敛到统一的联邦传输层避免每个功能各自实现一遍网络层导致漏洞发散。Phase 5 —— Action Router / GOAP 预检审计结论纯函数无 I/OURL 安全检查委托给既有的BrowserSecurityScanner由 30 个测试的套件覆盖。BrowserSecurityScanner实现在 security-integration.ts其SecurityConfig提供了一组可配置的安全开关配置项默认值说明enableUrlValidationtrue是否启用 URL 格式与协议校验仅允许http:/https:enablePIIDetectiontrue是否启用 PII 检测enableThreatScanningtrue是否启用钓鱼/威胁扫描blockedDomains[bit.ly,tinyurl.com,goo.gl,t.co]阻止的域名默认含短链服务allowedDomains[]允许列表优先于阻止列表判断maxRedirects5最大重定向次数requireHttpstrue是否强制 HTTPSpiiMaskingEnabledtrue日志/展示时是否掩码 PII扫描器的 PII 模式覆盖 email、phone、SSN、信用卡、API key、password、address、name 八类第 88–97 行威胁检测覆盖 XSS、注入、钓鱼指示词、可疑 TLD.tk/.ml/.ga/.cf/.gq/.xyz/.top/.work/.click、typosquatting 仿冒域名第 402–439 行、IP 直连等。安全性打分calculateSafetyScore按严重度加权low 0.1 / medium 0.25 / high 0.4 / critical 0.6safe阈值是 0.7 且无 critical 级威胁。sanitizeInput()提供 HTML 实体转义、script 标签剥离、事件处理器移除。Phase 6 —— Session Capsule 会话胶囊 风险分类器审计结论ReusePolicy.allowedOrigins/allowedTaskClasses在挂载时强制胶囊不能越过maxReplays上限RiskClassifier的正则全部锚定且有限长无灾难性回溯模式密封前通过scanInlineState()扫描内联状态中的 PII针对此前的字符串展开 bug 有回归测试。源码印证session-capsule.ts session-capsule-service.tsReusePolicySchema定义了复用边界allowedOrigins允许挂载的源、allowedTaskClasses默认[read-only, authenticated-read]、maxReplays最大重放次数0 在有效期内不限、requireFreshMfa每次挂载需新 MFA、allowCrossDevice/allowCrossInstallation默认均关闭。RiskClassSchema定义了七级风险分类read-onlyClass 1、authenticated-readClass 2、draft-writeClass 3可自主执行、以及external-submission/financial/account-mutation/destructiveClass 4–7均需人工审批。AUTONOMOUS_CLASSES只放行前三类作为自主行动门控的依据。OriginPolicySchema要求每源声明requireSecure默认 true等约束ConsentProofSchema承载所有者签名同意的复用策略声明。服务层create()session-capsule-service.ts在密封前对inlineState逐 cookie、逐存储值调用scanInlineState()发现 PII 或威胁即拒绝创建并返回计数——这就是审计中提到的密封前内联状态 PII 扫描。胶囊的状态既可内联inlineStatecookies localStorage sessionStorage IndexedDB 元数据也可外置stateRef指向 file / rvf / s3 的加密 blob 引用 SHA-256 完整性哈希两者互斥。此外witnessChainHead字段构成见证链头每次刷新/轮换密钥时前滚。Phase 7 —— Workflow 编译器 生产级 UCT审计结论纯数据变换无 I/OYAML 序列化器使用最小引号白名单——往返处理已知形状数据时不存在 YAML 注入向量。四、危险模式扫描一份可复用的安全检查清单审计对源码做了自动化危险模式扫描这是任何 AI 自动化包都应复刻的检查项模式发现结论源码中的eval()1 处 ——adapter.eval()包装agent-browser evalCLI 动词✅ 用户驱动无自动执行child_process.exec*所有调用点均为execFileSync无 shell✅ 无 shell 注入向量new Function()0✅用户字符串的动态import()0✅用户输入上的无界正则0全部由BrowserSecurityScanner锚定或限长✅源码中的密钥0 —— 仅process.env.RUFLO_BROWSER_WITNESS_KEY查找✅对不受信任磁盘内容的JSON.parse有因果存储 保险库持久化—— 均包在 try/catch 中遇到损坏输入从空状态重启✅ Fail-safe注意第一行的关键点eval出现不代表不安全关键是谁驱动它。这里唯一的eval是用户主动调用的适配器命令而非对用户输入的无条件执行——审计的正确姿态是发现模式 → 分析调用上下文 → 判定风险等级而不是一刀切禁止。五、已知问题溯源传递性依赖风险的处置策略问题影响面处置xenova/transformers退休经agentic-flow → agentdb传入ADR-121 Phase 4 迁移至ruvector-onnx-embeddings-wasm不阻塞本包发布opentelemetry/*Prometheus 崩溃传递性本包代码不调用该运行时路径sqlite3传递性本包不直接 import sqlite仅作为agentdb的可选对等依赖嵌入从 package.json 可以看到工程层面的配套手段通过overrides字段把opentelemetry/*系列、axios、undici、ws、express-rate-limit、protobufjs等传递性依赖钉在修复了已知 CVE 的最低版本之上如opentelemetry/sdk-node 0.218.0、undici 7.18.0。这是直接依赖干净 传递依赖受控两条腿走路的典型实践。六、发布建议与验证方式审计给出的最终建议是批准claude-flow/browser3.0.0-alpha.4发布 npm。依据是所有新代码路径由 230 个单元测试覆盖无新的直接漏洞传递性发现为既有问题且在其它 ADR 中跟踪。你可以用包自带脚本自行复现验证见 package.json# 类型检查与构建 npm run typecheck npm run build # 单元测试vitest覆盖 signed-trajectory / cookie-vault / session-capsule / # causal-recovery / security-integration / mcts-explorer 等 13 个测试套件 npm test # 端到端浏览器测试 npm run test:e2e # Lint npm run lint对应的测试证据集中在 tests 目录其中与安全直接相关的包括 signed-trajectory.test.ts签名往返与篡改检测、cookie-vault.test.tsPII 拒写与哈希防篡改、session-capsule.test.ts复用策略与重放上限、causal-recovery.test.tsorigin 隔离与风险分、以及 security-integration.test.ts扫描器 30 项测试套件。另外postinstall脚本会自动检测并安装全局agent-browser失败时给出手动安装提示保证运行时后端可用Node.js ≥ 18。七、后续跟进事项审计报告明确了两个待办方向供后续 ADR 追踪Phase 6.5实现 Stagehand / Browserbase / 本地 Chrome 的BrowserExecutionAdapter并对其依赖树重新审计——因为每新增一个执行后端就新增一条依赖与攻击面。Phase 8未来为整个基座编写正式威胁模型文档覆盖 Session Capsule 生命周期、ADR-103 v2 下的见证密钥轮换、以及联邦对端信任列表的传播机制。小结从这份审计可以带走什么这份审计报告与对应源码共同展示了一个 AI 浏览器自动化包的安全基线入口全部 Zod 校验、持久化前置 PII 扫描、所有工件 Ed25519 见证签名、复用策略显式化并强制实施、危险模式逐项扫描并给出调用上下文判定、传递性风险集中跟踪。其中信封 签名 证明attestation的容器模式signed-trajectory.ts、cookie-vault.ts、session-capsule.ts 三处域模型结构一致尤其值得借鉴——它让这份数据被谁扫描过、在何时、内容哈希是什么成为可验证的事实而非调用方的口头承诺。相关的 ADR 决策记录集中在 v3/docs/adr 目录可作为进一步深入研究的入口。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考