ttcd77/agent-browser-runtime
GitHub: ttcd77/agent-browser-runtime
为AI agent提供真实Chrome浏览器环境下的DevTools级网络证据捕获与安全研究能力，通过155个HTTP工具实现自动化的AppSec工作流。
Stars: 0 | Forks: 0
# Agent Browser Runtime
**面向 AI agent 的 DevTools 级浏览器证据运行时。**
为你的 agent 提供一个配备 **155 个 HTTP 工具** 的浏览器 —— 导航、点击，
捕获 F12 Network/Storage/Console/Sources 证据，重放请求，并
收集一键式安全研究包。使用每个 profile 独立启动的
**真实 `chrome.exe`**（无 Playwright 包装器），因此其指纹可以通过
你日常使用的 Chrome 都会触发的反机器人防御。
## 为什么不用 Playwright 或 Chrome DevTools MCP？
| | Playwright | Chrome DevTools MCP | **Agent Browser Runtime** |
|---|---|---|---|
| 浏览器进程 | 内置的 Chromium 并带有自动化标志 | 直接通过 CDP 连接用户的 Chrome | **每个 profile 启动真实 `chrome.exe`（与用户日常使用的 Chrome 是同一个可执行文件）** |
| 指纹 | 可检测（`navigator.webdriver`, `--enable-automation`, Playwright CDP 探测） | 真实 Chrome，无隔离 | **真实 Chrome + 每个 profile 独立的 `--user-data-dir` —— 可通过 DataDome / Akamai 检查** |
| 接口 | 脚本 API（是代码，而非工具） | MCP 工具接口面 | **HTTP 工具（155 个）+ 配套的 CLI heredoc（`attack-harness <<'PY' ... PY`）** |
| 网络证据 | 基础的 HAR | 实时 DevTools | **每个 profile 具备 F12 级别，并在 `~/.agent-browser-runtime/cdp-traffic//` 存有磁盘 body 文件** |
| Profile 隔离 | 手动 | 无 | **`profile_create {name}` 启动隔离的真实 Chrome，并通过模板复制自动安装扩展** |
| 重放 / Intruder / JWT 伪造 | 外部 | 无 | **内置（通过子进程代理到 `helloworld/attack-harness/` 的 Python 原语）** |
| Agent 优先设计 | 否 | 有限 | 门面模式 → 逐层下钻，限制输出，`next` 提示，决策树技能，agent 可写的 `agent-workspace/target-skills/` |
Playwright 是一个你用来编写代码的库。Chrome DevTools MCP 是一个
用于驱动你现有 Chrome 的工具菜单。ABR 是 **HTTP + 配套的 harness CLI** ——
为每个 profile 启动各自独立的真实 Chrome，隔离 cookies/登录/历史记录，
在磁盘上捕获完整的网络 body，并通过同级 helloworld 仓库中的
可组合 Python harness 路由复杂攻击。
## 架构
```
Agent (CLI / HTTP POST)
|
v
Worker :17335 ──── 155 HTTP tools (browser_* / profile_* / attack_intruder_* / etc)
|
+─── spawn-chrome-profile.mjs ──► chrome.exe --user-data-dir=
| --remote-debugging-port=
| (template-copy installs extension)
|
+─── cdp-traffic-capture plugin ──► reads ~/.agent-browser-runtime/browser-profiles.json
| attaches each personal-spawn profile's CDP
| writes bodies under cdp-traffic//
|
Bridge :17337 ──── multi-Chrome routing (list/select/switch_browser by displayName)
| ──── read_page / click_ref (Claude-in-Chrome-style DOM walker)
| ──── per-profile tab isolation
|
v
Chrome extension (in each spawned profile + the user's daily Chrome if installed)
──── chrome.scripting.executeScript for app-layer click/type (SPA-stable)
──── chrome.debugger CDP transit for deep evidence
helloworld/attack-harness/ (sibling repo, complementary harness)
──── Python primitives (raw_http, crypto, oob, subprocess, intruder, diff)
──── `attack-harness <<'PY' ... PY` CLI for composable attack scripts
──── interaction-skills/*.md playbooks (jwt-attacks, oob, smuggling, ...)
──── 14 ABR business tools subprocess-proxy here (single source of truth)
```
多个 Chrome 实例分别通过 `personal_chrome_list_browsers` 以各自独立的
`browserInstanceId` 和 `browserDisplayName` 显示。Agent 通过名称进行路由。
人类日常使用的 Chrome（如果安装了扩展）是这些已启动 profile 中的
一个实例 —— 桥接器确保 agent 的工作使用后台标签页，并且永远不会
抢占焦点。
## 快速开始（30 秒）
### 安装
```
# npm (global)
npm install -g agent-browser-runtime
# 从 source
git clone https://github.com/ttcd77/agent-browser-runtime.git
cd agent-browser-runtime
npm install && npm run build
```
### 启动 worker
**Linux / macOS:**
```
CDP_LAUNCH_BROWSER=1 npm run agent:server
```
**Windows (PowerShell):**
```
$env:CDP_LAUNCH_BROWSER="1"
npm run agent:server
```
### 首次工具调用
```
# Health check
agent-browser doctor
# 打开页面，捕获证据，打印 artifact 路径
agent-browser open https://example.com --profile demo
agent-browser capture start --profile demo --label first
agent-browser inspect network --profile demo
agent-browser pack https://example.com --profile demo
```
现在尝试你自己的 URL：`agent-browser pack https://your-site.com --profile mine`。
## 验收测试套件
要进行本地生产环境检查，请运行：
```
npm run acceptance:strict
```
它会验证面向 agent 的工具契约、Personal Chrome 的安全后台标签页
操作、Agent Browser profile 生命周期、origin-state 预热以及原始 HTTP
冒烟测试覆盖范围。
## 登录时自动启动
| 平台 | 脚本 | 机制 |
|---|---|---|
| Windows | `scripts/install-agent-server-task.ps1` | 计划任务（用户级别） |
| Linux | `scripts/install-systemd-units.sh` | systemd 用户单元 |
| macOS | `scripts/install-launchd-plists.sh` | launchd LaunchAgents |
**Windows:**
```
pwsh -File scripts/install-agent-server-task.ps1
pwsh -File scripts/install-personal-bridge-task.ps1
```
**Linux / macOS:**
```
bash scripts/install-systemd-units.sh # Linux
bash scripts/install-launchd-plists.sh # macOS
# 按照打印的说明启用 units
```
## Personal Chrome（扩展桥接器）
当你需要检查你已经打开的 Chrome 标签页时：
**Linux / macOS:**
```
npm run personal:chrome
```
**Windows (PowerShell):**
```
npm run personal:chrome
```
从 `extension/` 加载已解压的扩展程序，然后：
```
agent-browser backend status --intent personal-current-tab
```
在使用此模式之前，请阅读 `docs/personal-chrome-quickstart.md`。
## 工具（Agent Browser + Personal Chrome，7 个类别）
| 类别 | 数量 | 示例工具 |
|---|---|---|
| 导航与交互 | ~20 | `browser_open`, `browser_click`, `browser_type`, `browser_fill`, `browser_scroll`, `browser_drag`, `browser_wait` |
| 页面观察 | ~10 | `browser_snapshot`, `browser_screenshot`, `browser_text`, `browser_find`, `browser_eval`, `browser_observe` |
| 捕获与流量 | ~25 | `browser_capture`, `profile_traffic_query`, `profile_request_detail`, `profile_export_har`, `cdp_query` |
| 证据与工件 | ~20 | `browser_security_pack`, `browser_inspect`, `browser_evidence_bundle`, `browser_artifact_read`, `browser_auth_boundary` |
| 存储 / cookies | ~15 | `browser_storage_snapshot`, `browser_cookies_get`, `browser_cookies_set`, `browser_cookie_summary`, `browser_indexeddb_read` |
| 重放与攻击 | ~15 | `browser_replay`, `profile_request_replay`, `profile_race_request`, `profile_jwt_forge`, `attack_intruder_*` |
| 健康与路由 | ~10 | `browser_ready`, `browser_backend_status`, `browser_capabilities`, `agent_inspect`, `browser_worker_doctor` |
完整的工具参考：`docs/agent-devtools-api.md`。
F12 到工具的查找映射：`docs/devtools-panel-map.md`。
默认的专业工作流程：
```
browser_open → browser_capture → browser_inspect → browser_security_pack
```
使用 `agent_inspect` 作为 agent 的路由器 —— 它会根据 `focus` 参数（`overview`, `network`, `storage`, `console`,
`dom`, `sources`, `performance`, `evidence`, `debug`）选择正确的证据工具，
而无需 agent 扫描所有工具。
## HTTP API
任何工具都可以通过普通的 HTTP POST 调用：
```
curl -X POST http://127.0.0.1:17335/tool/browser_open \
-H "content-type: application/json" \
-d '{"profile":"researcher","url":"https://example.com"}'
curl -X POST http://127.0.0.1:17335/tool/browser_capture \
-H "content-type: application/json" \
-d '{"profile":"researcher","action":"start","label":"first-capture"}'
curl -X POST http://127.0.0.1:17335/tool/profile_traffic_query \
-H "content-type: application/json" \
-d '{"profile":"researcher","limit":20}'
```
健康检查：
```
curl http://127.0.0.1:17335/health
```
本地仪表板：`http://127.0.0.1:17335/panel`
## 安全性
- 工具返回客观证据 —— 它们不会对漏洞进行分类。
- 使用 `AGENT_BROWSER_RUNTIME_TOKEN` 要求所有工具调用都提供 bearer token。
- 设置 `CDP_BROWSER_HEADLESS=1` 开启无头/CI 模式（AppSec 工作默认使用有头模式）。
- 设置 `CDP_SECURITY_DATA_DIR` 以控制证据的存储位置。
- Artifact 路径会根据白名单进行验证；不存在目录遍历。
- HTTP body 捕获设有上限，以防止存储失控。
- Personal Chrome 模式需要操作员明确授权 —— 绝不会在后台静默附加。
有关 DNS 重绑定（rebinding）防护和完整的边界详细信息：`docs/safety-boundaries.md`。
## 关键环境变量
| 变量 | 默认值 | 用途 |
|---|---|---|
| `CDP_AGENT_SERVER_PORT` | `17335` | Worker HTTP 端口 |
| `CDP_AGENT_PROFILE` | `default` | 省略时使用的默认 profile |
| `CDP_LAUNCH_BROWSER` | 未设置 | 启动时启动 Agent Browser 后端 |
| `CDP_BROWSER_HEADLESS` | 未设置 | 无头模式（CI/测试） |
| `CDP_SECURITY_DATA_DIR` | `~/.agent-browser-runtime` | 证据存储根目录 |
| `CDP_BROWSER_PORT_MODE` | `ephemeral` | `ephemeral` 或 `fixed` CDP 端口 |
| `PERSONAL_CHROME_HTTP_PORT` | `17337` | Personal Chrome 桥接端口 |
| `AGENT_BROWSER_RUNTIME_TOKEN` | 未设置 | 用于 HTTP 认证的 Bearer token |
完整列表：请参阅 `docs/agent-operator-runbook.md` 的 Environment Variables 章节。
## 证据布局
```
~/.agent-browser-runtime/
profiles/
/
events/events.jsonl
traffic/traffic.jsonl
screenshots/*.png
evidence/
```
在审查并清理之前，请勿提交来自真实目标的已捕获证据。
## SDK 集成
```
const baseUrl = "http://127.0.0.1:17335";
async function callTool(name: string, params: unknown) {
const res = await fetch(`${baseUrl}/tool/${name}`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(params),
});
return res.json();
}
await callTool("browser_open", { profile: "researcher", url: "https://example.com" });
await callTool("browser_capture", { profile: "researcher", action: "start" });
const snapshot = await callTool("browser_snapshot", { profile: "researcher" });
```
无需 CDP target ID、标签页 ID 或浏览器端口。通过 profile 名称进行路由。
## 架构参考
有关两种后端、工具系列、安全边界和跨平台支持的完整细分，请参阅 `docs/architecture.md`。
## 故障排除
### "browser CDP endpoint 不可用；没有出现 DevToolsActivePort"
Agent Browser worker 尝试启动 Chrome，但 CDP 端口一直未出现。常见原因：
- **未安装 Playwright 浏览器**：运行一次 `npx playwright install chromium`。
- **端口 17335（worker）或 9222（CDP）被占用**：另一个 worker 可能已经在运行。停止它（使用 `agent-browser doctor` 确认）或将 `CDP_AGENT_SERVER_PORT` 和 `CDP_DEBUG_PORT` 设置为空闲端口。
- **Linux 服务器上无显示设备**：有头模式需要显示器。设置 `CDP_BROWSER_HEADLESS=1` 或使用虚拟帧缓冲区（`xvfb-run`）。
- **防火墙阻止 localhost**：大多数 Linux 容器默认不带防火墙，但可以使用 `ss -tlnp | grep 17335` 进行检查。
### "EADDRINUSE: 地址已被占用 127.0.0.1:17335"
之前的 worker 仍在运行。你可以：
- `pkill -f agent-cdp-server` (Linux/macOS)
- 使用 `netstat -ano | findstr :17335` 找到 PID (Windows) 然后 `taskkill /F /PID `
### Personal Chrome 桥接器提示 "extension not connected"
必须安装 Chrome 扩展并运行 personal 桥接器。请参阅 [`docs/personal-chrome-quickstart.md`](docs/personal-chrome-quickstart.md)。
### npm install 报告 HIGH 严重性警告
`ws` 版本为 8.21.0+（已修复）。如果你看到关于 `vite` 的警告，它们是仅用于开发的间接依赖，不会进入生产环境的 bundle 中。
### 我的证据文件在哪里？
每个 profile 位于 `~/.agent-browser-runtime/profiles//` 下：
- `traffic/` — 请求/响应日志
- `evidence/` — 证据包
- `screenshots/`, `events/` — 页面捕获
使用 `agent-browser doctor` 打印你机器上的确切路径。
### 报告问题
- **Bug**：[GitHub Issues](https://github.com/ttcd77/agent-browser-runtime/issues) 使用 `bug_report` 模板。
- **功能缺失**（工作流缺少工具）：相同的 Issues 页面，使用 `capability_gap` 模板。
- **安全问题**：参阅 [SECURITY.md](SECURITY.md)。
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
标签：AI智能体, IP 地址批量处理, MITM代理, Python脚本, Web开发工具, 数据泄露, 流量抓取, 浏览器自动化, 爬虫框架, 自定义脚本, 逆向工具