安全性

agent-browser 包含安全功能，可防范凭据泄露、通过不受信任页面内容进行的提示注入以及未经授权的浏览器操作。

所有安全功能均为可选。默认情况下，agent-browser 对导航、操作或输出不施加任何限制。根据部署需求启用这些功能即可——在您显式激活某个功能前，现有工作流不受影响。

威胁模型

这些功能旨在缓解由基于 LLM 的代理驱动浏览器时可能面临的以下威胁：

• 凭据泄露 —— 存储在身份验证保险库中的密码永远不会包含在 LLM 的上下文中。CLI 本地处理保险库操作；凭据不会经过守护进程的 IPC 通道。
• 通过页面内容进行的提示注入 —— 恶意页面可能嵌入看似工具输出或系统指令的文本。内容边界标记（--content-boundaries）使协调器能够区分受信任的工具输出与不受信任的页面内容。
• 未经授权的导航 / 数据外泄 —— 被攻陷或被操纵的代理可能导航至攻击者控制的域名以窃取数据。域名白名单（--allowed-domains）会阻止对未允许域名的导航、子资源请求、WebSocket 连接、EventSource 流以及 sendBeacon 调用。
• 未经授权的破坏性操作 —— 操作策略（--action-policy）和确认机制（--confirm-actions）可防止代理在未经明确批准的情况下执行危险操作（如 eval、下载、上传）。
• 上下文泛滥 —— 大量页面输出可能会淹没 LLM 的上下文窗口。输出截断（--max-output）可限制页面来源内容的大小。

已知限制

• WebSocket/EventSource 阻断为尽力而为。 该功能通过初始化脚本覆盖浏览器构造函数实现。如果允许 eval 操作类别，页面脚本理论上可以恢复原始构造函数。为获得最大保护，请通过 --action-policy 禁用 eval。
• 远程连接的域名过滤时机问题。 当通过 CDP 或云服务提供商连接到已存在的浏览器时，页面内容可能在域名过滤器安装前已加载。agent-browser 在过滤器生效后将不允许的页面导航至 about:blank，但在此之前加载的资源无法被回溯阻断。
• 内容边界是纵深防御手段。 它依赖于 LLM 和协调器尊重结构化标记。尽管具备足够能力的恶意页面可能尝试模仿边界格式，但由于每个进程的 CSPRNG 随机数，这种预测在实践中不可行。
• 确认超时。 待处理的确认将在 60 秒后自动拒绝。协调器必须在此时限内响应。
• 非终端环境下的自动拒绝。 当设置 --confirm-interactive 但标准输入不是终端（例如管道输入或在自动化流水线中运行）时，操作将自动拒绝，以防止在非交互式环境中意外批准。

身份验证保险库

在本地存储凭据并按名称引用。LLM 永远不会看到密码。

# 保存凭据（若设置了 AGENT_BROWSER_ENCRYPTION_KEY 则加密存储）
# 推荐：通过 stdin 传递密码，避免暴露于 shell 历史记录或进程列表中
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin

# 或直接传入（会显示警告）
agent-browser auth save github --url https://github.com/login --username user --password pass

# 使用保存的凭据登录
agent-browser auth login github

# 列出已保存的配置文件（仅显示名称和 URL，无敏感信息）
agent-browser auth list

# 显示配置文件元数据
agent-browser auth show github

# 删除一个配置文件
agent-browser auth delete github

如果自动检测失败，可指定自定义选择器：

agent-browser auth save myapp \
  --url https://app.example.com/login \
  --username user --password pass \
  --username-selector "#email" \
  --password-selector "#password" \
  --submit-selector "button.login"

配置文件存储在 ~/.agent-browser/auth/ 目录下，始终使用 AES-256-GCM 加密。若未设置 AGENT_BROWSER_ENCRYPTION_KEY，首次使用时将在 ~/.agent-browser/.encryption-key 自动生成密钥。为保证可移植性，请备份此文件或显式设置环境变量。

在 Unix 系统（chmod 600/700）和 Windows 系统（icacls 限制为当前用户）上均强制执行文件权限，防止其他用户读取加密密钥或身份验证配置文件。

内容边界标记

启用 --content-boundaries 后，所有页面来源的输出都会被结构化标记包裹，以便 LLM 区分工具输出与不受信任的页面内容：

--- AGENT_BROWSER_PAGE_CONTENT nonce=a1b2c3d4 origin=https://example.com ---
[snapshot / text / html / eval output here]
--- END_AGENT_BROWSER_PAGE_CONTENT nonce=a1b2c3d4 ---

nonce 是每次 CLI 进程调用时生成的随机值，使得试图伪造边界的页面内容无法预测。

通过标志或环境变量启用：

agent-browser --content-boundaries snapshot
# 或
export AGENT_BROWSER_CONTENT_BOUNDARIES=1

受影响的输出类型：snapshot, get text, get html, eval, console。

在 --json 模式下，边界元数据会注入到 JSON 响应中，作为 _boundary 对象包含 nonce 和 origin 字段，允许协调器程序化地验证来源：

{
  "success": true,
  "data": { "snapshot": "...", "origin": "https://example.com" },
  "_boundary": { "nonce": "a1b2c3d4e5f6...", "origin": "https://example.com" }
}

域名白名单

限制浏览器可交互的域名，防止重定向攻击和数据外泄：

agent-browser --allowed-domains "example.com,*.example.com,github.com" open https://example.com
# 或
export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"

支持精确匹配（github.com）和通配符前缀（*.example.com，也包括裸域名 example.com）。对未允许域名的页面导航和子资源请求（脚本、图片、fetch、XHR 等）均被阻止，防止数据外泄。通过构造函数级修补，也阻断 WebSocket 与 EventSource 连接。非 http(s) 的子资源（数据 URI、blob）仍允许。当请求被阻止时，命令返回错误。

注意： WebSocket/EventSource 阻断为尽力而为——它通过初始化脚本覆盖浏览器构造函数实现。如果允许 eval 操作类别，页面脚本理论上可恢复原始构造函数。为获得最大保护，请在使用 --allowed-domains 时通过 --action-policy 拒绝 eval 类别。

配置文件示例：

{
  "allowedDomains": ["example.com", "*.example.com", "github.com"]
}

CDN 与第三方资源： 域名过滤器会阻止所有对非允许域名的子资源请求（脚本、样式表、图片、字体、fetch/XHR）。大多数网站从 CDN 域名加载资源。请将这些域名加入白名单，否则页面将无法正常工作。例如：

--allowed-domains "myapp.com,*.myapp.com,cdn.jsdelivr.net,fonts.googleapis.com,fonts.gstatic.com"

操作策略

使用静态策略文件控制操作。策略由守护进程强制执行——被拒绝的操作立即失败。

agent-browser --action-policy ./policy.json open https://example.com
# 或
export AGENT_BROWSER_ACTION_POLICY=./policy.json

示例策略（宽松且特定拒绝）：

{
  "default": "allow",
  "deny": ["eval", "download", "upload"]
}

示例策略（严格限制）：

{
  "default": "deny",
  "allow": ["navigate", "snapshot", "click", "scroll", "wait", "get"]
}

身份验证保险库操作（auth save、auth login、auth list、auth show、auth delete）以及其他内部/元操作绕过操作策略检查，因为它们是可信的本地操作。auth login 导航仍受域名白名单限制。

操作确认

对于需要显式批准的操作，使用 --confirm-actions 指定需确认的类别：

# 协调器模式：返回 confirmation_required 响应
agent-browser --confirm-actions eval,download eval "document.title"

# 然后批准或拒绝：
agent-browser confirm c_8f3a1234
agent-browser deny c_8f3a1234

对于交互式（人工介入）确认：

agent-browser --confirm-actions eval,download --confirm-interactive eval "document.title"
# 提示：是否允许？[y/N]

待处理的确认将在 60 秒后自动拒绝。

非终端行为： 当设置 --confirm-interactive 但标准输入不是终端（例如管道输入或在自动化流水线中运行）时，操作将自动拒绝。这可防止在非交互式环境中意外批准。

输出长度限制

通过截断大页面输出来防止上下文泛滥：

agent-browser --max-output 50000 get text body
# 或
export AGENT_BROWSER_MAX_OUTPUT=50000

受影响的输出类型：snapshot, get text, get html, eval, console。

环境变量

推荐配置

适用于生产环境的 AI 代理部署：

{
  "contentBoundaries": true,
  "maxOutput": 50000,
  "allowedDomains": ["your-app.com", "*.your-app.com"],
  "actionPolicy": "./policy.json"
}