Security Policy / 安全策略

loop-codex 通过 Chrome DevTools Protocol (CDP) 与 Codex Desktop 的 Electron WebContents 通信，安全是最高优先级的架构关注点。本文档定义 loop-codex 的完整安全模型、威胁面覆盖、报告流程和最佳实践。

Supported Versions / 支持的版本

Version / 版本	Supported / 支持状态
0.1.x	✅ Supported
< 0.1.0	❌ Not supported

Security Model Overview / 安全模型概述

loop-codex 采用 默认拒绝 (Default-DENY) 的安全姿态。所有 CDP 命令在发送到 Codex Desktop 之前必须通过 CDPGuard (M13) 的多层安全检查漏斗。

三层安全架构

[Agent 指令]
    │
    v
[DualChannelCoordinator] ─── CDPGuard (唯一入口)
    │                              │
    │                    ┌─────────┴──────────┐
    │                    │  1. L0/L1/L2 方法拦截  │
    │                    │  2. URL 模式校验      │
    │                    │  3. DOM Scope 校验    │
    │                    │  4. 表达式白名单/黑名单  │
    │                    │  5. 速率限制          │
    │                    └─────────┬──────────┘
    │                              │
    v                              v
[CDP WebSocket] ────────── 审计日志 (cdp-session.log)

纵深防御层 (Defense in Depth)

层	名称	机制	拦截等级
1	方法拦截	bannedMethods 映射表，L0/L1/L2 三级分类	L0: 绝对拦截; L1: 拦截+警告; L2: 允许但审计
2	URL 校验	禁止 URL 正则模式匹配（防止导航到恶意地址）	L0
3	DOM Scope	allowed_dom_scope 白名单（限定可访问的 DOM 选择器范围）	L2
4	表达式安全	Runtime.evaluate 表达式白名单 + 黑名单双重验证	L0
5	速率限制	每轮 CDP 命令数上限（防指令风暴/失控）	L2
6	审计日志	所有 CDP 命令执行/拦截均记录到 cdp-session.log (JSONL)	N/A（事后）

CDP 方法三级拦截分类

L0 — 灾难级 (CATASTROPHIC)

这些操作可能导致 Codex Desktop 崩溃、数据丢失或安全沙箱逃逸。所有信任级别下均被硬拦截，无例外。

CDP 方法	风险描述
`Browser.close`	关闭整个浏览器实例，导致 Codex 进程终止
`Target.closeTarget`	关闭标签页/Target，可能丢失未保存数据
`Target.disposeBrowserContext`	销毁浏览器上下文，影响所有关联 Target
`Security.setIgnoreCertificateErrors`	禁用证书错误检查，暴露 MITM 攻击面
`Page.navigate`	仅在目标 URL 命中 banned_url_patterns 时拦截
`Page.setDownloadBehavior`	修改下载行为，可能导致恶意文件自动下载
`Page.setBypassCSP`	绕过内容安全策略 (CSP)
`Network.setBypassServiceWorker`	绕过 Service Worker 安全控制
`Storage.clearDataForOrigin`	清除源数据，不可逆操作
`Runtime.evaluate`	仅在表达式命中黑名单或不在白名单时拦截

L1 — 不可逆级 (IRREVERSIBLE)

这些操作可能修改页面 DOM 状态、注入输入事件或执行脚本，具有不可逆影响。

CDP 方法	风险描述
`DOM.removeNode`	从 DOM 树中删除节点
`DOM.setAttributeValue` / `DOM.setNodeValue`	修改 DOM 节点属性/值
`DOM.setOuterHTML`	替换节点的 outerHTML
`Input.dispatchKeyEvent` / `Input.dispatchMouseEvent`	注入输入事件
`Input.insertText`	向页面注入文本
`Page.reload`	重新加载页面，中断当前操作
`Runtime.runScript` / `Runtime.compileScript`	执行/编译任意脚本
`Debugger.*`	调试器控制（stepInto, stepOver, resume 等）
`CSS.createStyleSheet` / `CSS.addRule` / `CSS.setStyleSheetText`	注入/修改 CSS

L2 — 高风险级 (HIGH_IMPACT)

这些操作本身安全但可能被滥用进行信息窃取，因此 允许执行但记录审计日志。

CDP 方法	风险描述
`Page.captureScreenshot`	截图可能包含敏感信息
`Page.captureSnapshot`	DOM 快照可能暴露用户数据
`DOM.getDocument` / `DOM.getOuterHTML`	获取完整 DOM 结构
`DOM.performSearch` / `DOM.discardSearchResults`	DOM 搜索操作
`Runtime.callFunctionOn` / `Runtime.getProperties`	调用/获取对象属性
`Network.enable` / `Network.setCacheDisabled`	网络监控/缓存控制

Runtime.evaluate 表达式安全策略

CDP 的 Runtime.evaluate 是在页面上下文中执行任意 JavaScript 的最危险方法之一。loop-codex 采用 白名单+黑名单双重验证：

白名单 (允许的纯读取表达式模式)

document.querySelector(...).(innerText|textContent|innerHTML|value|checked|disabled)
document.querySelector(...).(getAttribute(...)|classList.contains(...))
document.querySelector(...) !== null
document.querySelectorAll(...).length
document.(title|URL|readyState)

黑名单 (禁止的危险模式，优先于白名单)

eval(              Function(          setTimeout(
setInterval(       fetch(             XMLHttpRequest
WebSocket          localStorage.set   sessionStorage.set
document.write     window.open        window.close
import(            require(           location=
document.cookie    postMessage(       constructor(
__proto__          prototype=

校验顺序：黑名单检查（命中则拒绝）→ 白名单检查（命中则允许）→ Default-DENY（未命中则拒绝）。

Threat Surface / 威胁面覆盖

loop-codex 识别并防护以下 6 个威胁面：

ID	威胁面	风险	防护措施
T1	指令注入 — Agent 发送恶意 CDP 命令	高	CDPGuard 方法拦截 + 表达式白名单
T2	URL 重定向 — Page.navigate 到恶意地址	高	bannedUrlPatterns 正则拦截
T3	DOM 信息泄露 — 读取超出 scope 的 DOM 数据	中	allowed_dom_scope 校验
T4	代码执行 — Runtime.evaluate 执行任意 JS	严重	白名单 + 黑名单双重表达式验证
T5	指令风暴/DoS — 大量 CDP 命令耗尽资源	中	速率限制 (maxCommandsPerTurn)
T6	审计逃避 — 绕过审计日志记录	中	CDPGuard 是唯一 CDP 命令入口，所有命令强制审计

Audit Log / 审计日志

所有 CDP 命令执行和拦截均写入 cdp-session.log（JSONL 格式，追加式写入）。

审计日志条目结构

{
  "id": "audit-<timestamp>-<seq>",
  "timestamp": "2026-06-13T00:00:00.000Z",
  "phase": "part_2_2",
  "method": "Page.captureScreenshot",
  "paramsSummary": "{format: \"png\"}",
  "durationMs": 45,
  "success": true,
  "resultSummary": "截图 1920x1080",
  "blocked": false,
  "blockReason": null
}

拦截日志示例

{
  "id": "audit-lm3x2k-0001",
  "timestamp": "2026-06-13T00:00:01.000Z",
  "phase": "part_2_1",
  "method": "Browser.close",
  "paramsSummary": "{}",
  "durationMs": 1,
  "success": false,
  "blocked": true,
  "blockReason": "[L0] 灾难级 CDP 操作被拦截: Browser.close"
}

allowed_dom_scope 配置指南

allowed_dom_scope 是 loop-codex 的 DOM 级别安全护栏（替代 loop-claudecode 的 allowed_file_scope），限定 CDP 可访问的 DOM 范围。

默认配置

{
  "allowed_dom_scope": {
    "pages": [{
      "urlPattern": "*",
      "allowedSelectors": [
        "[role='tab']", "[role='treeitem']", "[role='button']",
        "[role='textbox']", "[role='dialog']",
        ".monaco-editor", ".file-tree", ".output-panel",
        ".terminal-panel", ".problems-panel", ".code-review-panel"
      ],
      "deniedSelectors": ["#__secret__", "[data-testid='hidden']"]
    }],
    "bannedUrlPatterns": [],
    "allowLocalhost": false,
    "maxCdpCommandsPerTurn": 200
  }
}

安全建议

生产环境中将 allowLocalhost 设置为 false
maxCdpCommandsPerTurn 默认 200，可根据实际场景调整（最小 50）
allowedSelectors 仅列出 agent 需要交互的 UI 元素
deniedSelectors 用于明确排除敏感区域

Reporting a Vulnerability / 报告漏洞

If you discover a security vulnerability, please do not open a public issue. Instead, follow the steps below.

如果您发现了安全漏洞，请不要公开提交 Issue。请按照以下步骤操作。

Contact / 联系方式

Email: novelnexusai@outlook.com
GitHub: PerryLink

What to include / 报告内容

When reporting a vulnerability, please provide the following information:

报告漏洞时，请提供以下信息：

Description / 漏洞描述 — A clear description of the vulnerability and its potential impact. 清晰描述漏洞及其潜在影响。
Steps to Reproduce / 复现步骤 — Detailed steps to reproduce the issue. 详细的问题复现步骤。
Affected Versions / 影响版本 — The version(s) of loop-codex where the vulnerability exists. 漏洞存在的 loop-codex 版本号。
Suggested Fix / 修复建议 — (Optional) Any suggestions for fixing the vulnerability. （可选）修复漏洞的建议。

Response Timeline / 响应时间线

Acknowledgment / 确认收到: Within 48 hours / 48 小时内
Initial Assessment / 初步评估: Within 5 business days / 5 个工作日内
Fix Disclosure / 修复披露: Coordinated with reporter / 与报告者协商

Scope / 范围

以下问题属于安全漏洞范围：

CDPGuard 被绕过的利用方式
Runtime.evaluate 表达式白名单遗漏的危险模式
审计日志数据泄露
CDP 命令注入
权限提升或沙箱逃逸

以下问题不属于安全漏洞范围：

需要物理访问的攻击
已公开的 Electron/CDP 协议已知限制
依赖项中的已知 CVE（需单独报告给相应项目）

Security Best Practices / 安全最佳实践

运行时安全

Keep loop-codex and its dependencies up to date. 请保持 loop-codex 及其依赖项为最新版本。
Use the latest Bun runtime version (>=1.2.0) as specified in engines. 请使用 engines 中指定的 Bun 运行时最新版本（>=1.2.0）。
Review CDP (Chrome DevTools Protocol) connection permissions carefully. 请仔细检查 CDP 连接权限。
不要在生产环境中使用 --remote-debugging-port=9222 的默认端口。
限制 CDP 端口仅监听 localhost (127.0.0.1)，不要绑定到 0.0.0.0。
定期审查 cdp-session.log 审计日志中的拦截记录。
在 CI/CD 管道中启用 loop-codex --check 进行安全健康检查。

配置安全

为每个项目定制 allowed_dom_scope，仅开放必要的 DOM 选择器。
将 maxCdpCommandsPerTurn 设置为与 agent 工作负载匹配的最小值。
定期更新 bannedUrlPatterns 以反映最新的威胁情报。
不要在 Runtime.evaluate 表达式中拼接用户输入。

开发安全

所有新增 CDP 方法使用前必须通过 CDPGuard 审查。
禁止在源码中硬编码 CDP WebSocket URL 或敏感配置。
单元测试必须覆盖 CDPGuard 的所有拦截路径（L0/L1/L2 + 表达式白名单/黑名单）。
提交前运行 bun test 确保安全相关测试全部通过。

Dependency Security / 依赖安全

loop-codex 将直接依赖控制在最小范围：

依赖	用途	安全审查
`pixelmatch` (5.3.0)	截图 diff 比较	仅处理图片像素数据，无网络/文件系统访问
`bun-types` (dev)	TypeScript 类型定义	仅开发时使用
`ws` (dev)	Node.js WebSocket fallback	CDP 优先使用 Bun 内建 WebSocket
`chrome-remote-interface` (可选 peer)	Node.js CDP 客户端 fallback	仅作参考实现，非默认依赖

Acknowledgments / 致谢

我们感谢以下安全研究人员和社区成员对 loop-codex 安全的贡献（按时间排序）。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Security Policy / 安全策略

Supported Versions / 支持的版本

Security Model Overview / 安全模型概述

三层安全架构

纵深防御层 (Defense in Depth)

CDP 方法三级拦截分类

L0 — 灾难级 (CATASTROPHIC)

L1 — 不可逆级 (IRREVERSIBLE)

L2 — 高风险级 (HIGH_IMPACT)

Runtime.evaluate 表达式安全策略

白名单 (允许的纯读取表达式模式)

黑名单 (禁止的危险模式，优先于白名单)

Threat Surface / 威胁面覆盖

Audit Log / 审计日志

审计日志条目结构

拦截日志示例

allowed_dom_scope 配置指南

默认配置

安全建议

Reporting a Vulnerability / 报告漏洞

Contact / 联系方式

What to include / 报告内容

Response Timeline / 响应时间线

Scope / 范围

Security Best Practices / 安全最佳实践

运行时安全

配置安全

开发安全

Dependency Security / 依赖安全

Acknowledgments / 致谢

FilesExpand file tree

SECURITY.md

Latest commit

History

SECURITY.md

File metadata and controls

Security Policy / 安全策略

Supported Versions / 支持的版本

Security Model Overview / 安全模型概述

三层安全架构

纵深防御层 (Defense in Depth)

CDP 方法三级拦截分类

L0 — 灾难级 (CATASTROPHIC)

L1 — 不可逆级 (IRREVERSIBLE)

L2 — 高风险级 (HIGH_IMPACT)

Runtime.evaluate 表达式安全策略

白名单 (允许的纯读取表达式模式)

黑名单 (禁止的危险模式，优先于白名单)

Threat Surface / 威胁面覆盖

Audit Log / 审计日志

审计日志条目结构

拦截日志示例

allowed_dom_scope 配置指南

默认配置

安全建议

Reporting a Vulnerability / 报告漏洞

Contact / 联系方式

What to include / 报告内容

Response Timeline / 响应时间线

Scope / 范围

Security Best Practices / 安全最佳实践

运行时安全

配置安全

开发安全

Dependency Security / 依赖安全

Acknowledgments / 致谢