安全#

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

所有安全功能都需要显式启用。默认情况下，agent-browser 不会对导航、操作或输出施加任何限制。请按你的部署需要启用这些功能，在你明确激活之前，现有工作流不会受到影响。

威胁模型#

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

• 凭据泄露 -- 存放在 auth vault 中的密码永远不会进入 LLM 上下文。CLI 在本地处理 vault 操作；凭据不会经过守护进程的 IPC 通道。
• 插件秘密访问：凭据提供器插件在进程外运行，并且只接收结构化的凭据解析请求。核心 agent-browser 负责浏览器自动化、策略检查和对敏感输出的脱敏处理。
• 通过页面内容进行提示注入 -- 恶意页面可能嵌入看起来像工具输出或系统指令的文本。内容边界标记（--content-boundaries）让协调器可以区分可信的工具输出和不可信的页面内容。
• 未经授权的导航 / 数据外泄 -- 被攻陷或被操控的代理可能导航到攻击者控制的域名以外泄数据。域名白名单（--allowed-domains）会阻止对未允许域名的导航、子资源请求、WebSocket 连接、EventSource 流以及 sendBeacon 调用。
• 未经授权的破坏性操作 -- 动作策略（--action-policy）和确认门控（--confirm-actions）可阻止代理在没有明确批准的情况下执行危险操作（eval、下载、上传）。
• 上下文洪泛 -- 大型页面输出可能淹没 LLM 的上下文窗口。输出截断（--max-output）会限制页面来源内容的大小。

已知限制#

• WebSocket/EventSource 阻止是尽力而为。 它通过在 init script 中重写浏览器构造函数来实现。如果允许 eval 动作类别，页面脚本理论上可以恢复原始构造函数。为了获得最大保护，请通过 --action-policy 禁止 eval。
• 远程连接上的域名过滤时机。 当通过 CDP 或云提供商连接到预先存在的浏览器时，页面可能在安装域名过滤器之前就已经加载了内容。agent-browser 会在过滤器生效后把不允许的页面导航到 about:blank，但在此之前加载的资源不会被事后阻止。
• 内容边界属于深度防御。 它们依赖 LLM 和协调器尊重结构化标记。能力足够强的对抗性页面可能尝试模拟边界格式，不过每个进程的 CSPRNG nonce 让这很难被预测。
• 插件是本地可执行文件。 只应安装你信任的维护者提供的凭据插件。agent-browser 会限制发送给插件的数据并支持策略门控，但它不会为任意本地可执行文件提供沙箱。
• 插件配置不是密钥存储。 不要把 vault token 或密码放进插件命令参数。请使用厂商自己的登录/会话机制，或使用 agent-browser 配置之外的环境变量。
• 确认超时。 待处理的确认会在 60 秒后自动拒绝。协调器必须在该时间窗口内响应。
• 非 TTY 自动拒绝。 当设置了 --confirm-interactive 但 stdin 不是终端时（例如管道输入），为了防止在非交互环境中误批准，动作会自动拒绝。

认证 Vault#

将凭据保存在本地，并通过名称引用。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

auth login 会使用 load 生命周期事件进行导航，然后在填充/点击之前等待表单选择器出现。这样在处理延迟加载的 SPA 登录页时更可靠，同时也避免了在有长时间后台请求的页面上卡在 networkidle。

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

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 限制为当前用户）上强制文件权限，以防止其他用户读取加密密钥或 auth 配置文件。

插件#

插件通过 agent-browser.plugin.v1 stdio JSON 协议在进程外运行。请在 agent-browser.json 中配置它们：

有关插件作者协议和实现示例，请参见 Plugins。使用 agent-browser plugin add <ref> 可以自动创建插件配置。

{
  "plugins": [
    {
      "name": "vault",
      "command": "agent-browser-plugin-vault",
      "capabilities": ["credential.read"]
    },
    {
      "name": "cloud-browser",
      "command": "agent-browser-plugin-cloud-browser",
      "capabilities": ["browser.provider"]
    },
    {
      "name": "stealth",
      "command": "agent-browser-plugin-stealth",
      "capabilities": ["launch.mutate"]
    },
    {
      "name": "captcha",
      "command": "agent-browser-plugin-captcha",
      "capabilities": ["command.run", "captcha.solve"]
    }
  ]
}

查看已配置的插件：

agent-browser plugin list
agent-browser plugin show vault

使用插件登录：

agent-browser auth login my-app --credential-provider vault --item "My App"

将插件用作浏览器提供商：

agent-browser --provider cloud-browser open https://example.com

使用通用插件命令：

agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'

凭据插件接收 credential.resolve，并返回用户名、密码，以及可选的 URL 或选择器元数据。浏览器提供商插件接收 browser.launch，并返回一个 CDP WebSocket URL。启动修改器插件接收 launch.mutate，可以在 Chrome 启动前附加本地启动参数、扩展或 init script 源代码。通用命令插件接收传给 plugin run 的请求类型。

plugin run 用于 command.run 和自定义能力。核心能力和协议请求类型会走各自专用的命令路径，因此凭据、浏览器提供商和启动修改器访问都仍然处于正常的策略门控之内。

agent-browser 将浏览器自动化、敏感输出脱敏和策略执行保留在核心中。凭据插件的秘密不会出现在命令参数、仪表盘事件或普通命令输出中。

通过能力动作对插件访问进行门控：

agent-browser --confirm-actions plugin:vault:credential.read auth login my-app --credential-provider vault --item "My App"
agent-browser --confirm-actions plugin:cloud-browser:browser.provider --provider cloud-browser open https://example.com
agent-browser --confirm-actions plugin:stealth:launch.mutate open https://example.com

内容边界标记#

启用 --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
# or
export AGENT_BROWSER_CONTENT_BOUNDARIES=1

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

在 --json 模式下，边界元数据会作为 _boundary 对象注入到 JSON 响应中，包含 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
# or
export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"

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

注意： WebSocket/EventSource 阻止是尽力而为的，它通过 init script 重写浏览器构造函数实现。如果允许 eval 动作类别，页面脚本理论上可以恢复原始构造函数。为了获得最大保护，在使用 --allowed-domains 时，请通过 --action-policy 禁止 eval 类别。

Config file:

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

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

bash

--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
# or
export AGENT_BROWSER_ACTION_POLICY=./policy.json

示例策略（宽松，但有特定拒绝项）：

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

示例策略（严格）：

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

auth vault 操作会把秘密保持在普通命令输出和 LLM 上下文之外。域名白名单限制仍会应用于 auth login 导航。基于插件的登录还会暴露能力动作 plugin:<name>:credential.read，用于策略和确认门控。

动作确认#

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

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

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

对于交互式（human-in-the-loop）确认：

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

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

非 TTY 行为： 当设置了 --confirm-interactive 但 stdin 不是 TTY 时（例如管道输入或在自动化流水线中运行），动作会自动拒绝。这可以防止在非交互环境中误批准。

输出长度限制#

通过截断大型页面输出，防止上下文洪泛：

agent-browser --max-output 50000 get text body
# or
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"
}