kb-browser

<p align="center"> <img src="assets/banner.png" alt="kb — CLI 浏览器" width="760"> </p> <p align="center"> <b>一款您可以从命令行完全操作浏览器。</b> 基于 Playwright + Chromium (CDP) 构建。 </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3ddc97.svg" alt="MIT 许可证"></a> <img src="https://img.shields.io/badge/node-%E2%89%A518-3ddc97.svg" alt="Node >= 18"> <img src="https://img.shields.io/badge/Playwright-Chromium-2a3244.svg" alt="Playwright + Chromium"> <img src="https://img.shields.io/badge/MCP-24%20tools-2a3244.svg" alt="MCP · 24 工具"> </p> 日本語版は [README.ja.md](README.ja.md) を参照してください。 GUI 浏览器提供的所有功能 — 页面渲染、Cookie 管理、开发者工具操作（网络 / 控制台 / 元素）— 都作为 `kb` 命令提供。内置 FoxyProxy 样式的代理配置文件，具有**无需重启的切换**和每个主机的路由规则。设计用于通过 Bash 或 MCP 由 AI 代理（Claude Code 等）驱动，同时窗口是您可以在任何时候手动使用的真实 Chrome。 > **两种工作流程：** > - **由 AI 代理驱动** — Claude Code 和其他代理通过 **MCP（24 工具）** 或 **Bash** 操作 kb（每个命令都支持 `--json`）。无障碍快照 + `--ref` 环路针对可靠、低令牌自动化进行调优，驻留守护进程在几十毫秒内返回每个步骤。 > - **安全研究和漏洞悬赏**（仅限授权测试）— 会话共享 HTTP、实时网络检查/模拟、生 `eval` 在经过身份验证的 SPA 上、代理链接到 Burp/Caido、两个帐户 IDOR 通过配置文件，以及屏蔽的、可共享的证据包。参见 [安全研究和漏洞悬赏](#security-research--bug-bounty-recon)。 ## 功能 - **守护进程架构** — 浏览器保持驻留；每个 CLI 命令都在几十毫秒内返回 - **真实 Chrome** — 使用您已安装的 Chrome/Edge（DRM 有效），回退到捆绑的 Chromium；使用 `--channel` 显式选择，覆盖用户代理与 `--ua`，或使用 `--stealth` 以授权测试的常规（非自动化）浏览器呈现 - **附加到正在运行的浏览器** — `kb daemon start --cdp http://127.0.0.1:9222` 连接到使用 `--remote-debugging-port` 启动的 Chrome/Edge，并重用其已登录状态 - **Chrome 扩展** — `kb daemon start --extensions <dir,...>` 加载解包的扩展（`on` 启用已在配置文件中安装的扩展，`off` 关闭）。参见 [Chrome 扩展](#chrome-extensions) - **代理优化** — `kb snapshot` 返回具有元素引用的无障碍树；`kb click --ref e12` 可靠地操作它们（包括在 iframe 内），而过时的引用在重新渲染后会自动**重新解析**到具有相同角色/名称的元素。长输出（文本 / HTML / 快照）默认限制为 20,000 个字符，并使用 `--offset` 分页。`kb eval` 接受 `await` 和多行代码 - **从终端使用开发者工具** — 网络日志/响应正文（`kb net body`）/ 完整头部（`kb net headers`）/ 请求阻止/响应模拟（包括用错误响应覆盖实时端点）/ HAR 记录/控制台/ DOM 检查 - **迷你 REST 客户端** — `kb request` 直接访问 API 而无需打开页面；与浏览器共享 Cookie 和代理设置（调用经过身份验证的 API 原样） - **代理配置文件** — 保存 `host:port`（+auth）为命名配置文件，立即切换，无需重启浏览器，通过特定代理路由特定主机（FoxyProxy 样式规则），内置中继处理 SOCKS5 认证（中继本身受令牌保护） - **有头/无头/配置文件切换** — 标签页和 Cookie 生存 - **持久登录** — 登录一次，配置文件在会话之间保持状态；`kb login` 将手动登录流程封装在一个命令中，`kb storage dump / restore` 导出到文件 - **操作记录** — 默认记录命令、网络和控制台；`kb log export` 生成自包含包（报告 + 再现步骤 + 独立 curl + 截图），默认屏蔽敏感值 - **人在环路中** — 代理自动执行，您接管登录/CAPTCHA，`kb wait` 检测您何时完成 - **MCP 服务器** — `kb-mcp` 暴露 24 个工具（截图作为图像返回） - **所有命令均支持 `--json`** — 用于脚本和代理的机器可读输出 ## 安装 ```bash npm install npm run build npm link # 使 kb / kb-mcp 在全局范围内可用 ``` 浏览器二进制文件自动选择：已安装的 Chrome → Edge → Playwright 捆绑的 Chromium（仅当您需要捆绑的 Chromium 时运行 `npx playwright install chromium`）。 ## 快速入门 ```bash kb open example.com # 守护进程（浏览器）自动启动 kb text # 读取页面文本 kb snapshot # 页面结构，带有元素引用 kb click --ref e6 # 可靠地点击引用 kb screenshot -o s.png kb daemon stop # 退出浏览器 ``` 默认情况下为有头（可见窗口）。Cookie 和登录状态保存在 `~/.kb/profiles/` 下。 ## 命令 | 类别 | 命令 | |---|---| | 守护进程 | `kb daemon start [--headless] [--profile <n>] [--channel chrome\|msedge\|chromium] [--ua <s>] [--stealth] [--extensions <dirs\|on\|off>] [--cdp <url>] / stop / status` | | 页面 | `kb open <url> [-n] [--wait idle]` / `kb tabs [close/switch <id>]` / `kb text` / `kb html` / `kb snapshot` / `kb screenshot [<sel>\|--ref e12] [-f] [--timeout <sec>]`（支持元素级）/ `kb pdf`（仅限无头） | | 导航 | `kb back` / `kb forward` / `kb reload` / `kb scroll [--to <sel>/--bottom]` | | 交互 | `kb click` / `kb fill` / `kb select [--label]` / `kb check` / `kb uncheck` / `kb hover` / `kb upload <sel> <local file path...>` / `kb press <key>` / `kb eval <js> [--file f.js]`（接受 `await` 和多行代码；返回最后一个表达式）— 通过 CSS 选择器、 `--ref e12`（来自快照）或 `--frame <sel>`（在 iframe 内）定位 | | 对话框 | `kb dialog [show]` / `kb dialog accept [text]` / `kb dialog dismiss` / `kb dialog policy [hold\|accept\|dismiss]`（保持 `alert`/`confirm`/`prompt`，然后响应；默认保持） | | HTTP | `kb request <url> [-X POST] [-H "Name: value"] [-d body \| --data-file f] [-o file] [--no-follow \| --follow-verbose]`（独立于页面；与浏览器共享 Cookie 和代理） | | 登录 | `kb login [url] [--until <glob>] [--save <file>]`（手动登录 → 状态自动保存到配置文件） | | Cookie / 会话 | `kb cookies [list/get/set/rm/clear/export/import]` / `kb storage dump/restore` | | 下载 | `kb downloads [list/clear]`（自动保存在 `~/.kb/downloads/` 下） | | 网络 | `kb net log [-f] [--filter re] [--responses]` / `kb net body <seq>`（响应正文）/ `kb net headers <seq>`（完整头部）/ `kb net block <glob>` / `kb net mock <glob> [--body f\|--text s] [--status n]` / `kb net unroute <id>\|--all` / `kb net har start/stop` | | 控制台 | `kb console [-f]` | | 记录 | `kb log [list]` / `kb log start [--name n] [--shots] / stop / status` / `kb log show/steps [--no-mask]` / `kb log export [-o dir]` / `kb log replay [n] [--dry-run]` / `kb log rm <n>` | | DOM | `kb dom query <sel> [--html] [--attr name] [--frame <sel>]`（回退到同名 DOM 属性 — 属性不存在时的值 / checked 等） | | 代理 | `kb proxy add/rm/list/use/off/status/test` / `kb proxy rule add/rm/list` | | 模式/配置文件 | `kb mode headed\|headless` / `kb profile list/use <n>`（标签页和 Cookie 恢复） | | 认证 | `kb auth set <user> <pass>` / `kb auth clear`（针对目标站点的 HTTP 基本认证） | | 等待 | `kb wait [--url <glob>] [--selector <sel>] [--idle] [--any]`（默认情况下多个条件 AND；`--any` 表示 OR） | | 模拟 | `kb emulate ua/viewport/tz/geo/net/reset`（网络：离线/慢 3g/快速 3g） | 所有命令都支持 `--json`。长输出默认截断为 20,000 个字符；使用 `--offset <n>` 获取下一个块，或使用 `--max-chars 0` 获取所有内容。 ## JS 对话框（alert / confirm / prompt） 打开 `confirm` / `alert` / `prompt` 的页面也支持。kb **保持** 对话框打开并等待响应（默认 `hold`），因此操作结果带有 `dialog`： ```bash kb click "#delete" # → 点击 → 确认对话框 "你确定吗？" 正在等待响应（标签页 1）。 # 使用 kb dialog accept / kb dialog dismiss 响应。 kb dialog # 检查待处理对话框 kb dialog accept # 确定（确认 → true，提示 → 默认值） kb dialog accept "Alice" # 用文本回答提示，然后确定 kb dialog dismiss # 取消 ``` 当对话框待处理时，该标签页上的其他操作（`snapshot` / `text` / `click` ...）受到保护，并提示您先响应。在有头模式下，本地对话框在屏幕上显示，因此您可以直接在窗口中单击确定 / 取消 — kb 自动清除其待处理状态。 要自动响应而不是保持： ```bash kb dialog policy accept # 自动确定每个对话框（无显示） kb dialog policy dismiss # 自动取消每个对话框（旧行为） kb dialog policy hold # 返回默认值（保持并等待） ``` > 以前 Playwright 默认立即关闭对话框，使触发 `confirm` 的按钮看起来像它们“没有做任何事情”。`hold` 修复了这个问题 — 对话框显示给人类，您选择响应。 ## 保持登录 **登录一次。** kb 使用持久化配置文件启动浏览器（`~/.kb/profiles/`），因此 Cookie 和 localStorage 在守护进程重启后存活。对于到服务的初始登录，请使用 `kb login`: ```bash kb login github.com # 切换到有头，打开页面 → 登录 → 按 Enter kb login myapp.example.com --until "**/dashboard**" # 通过 URL 自动检测完成（代理友好） kb login github.com --save gh-state.json # 还将状态备份到文件 ``` 后续会话已经登录 — 无需执行任何操作。保存的 `--save` 文件可以使用 `kb storage restore <file>` 将状态转移到另一个配置文件或机器。 注意：纯粹依赖会话 Cookie（无过期时间）的站点会在浏览器重启时注销，与普通浏览器相同。`kb storage dump / restore` 也涵盖这种情况。`storage dump` 导出 **所有 Cookie，包括 HttpOnly** 以及 localStorage（Playwright storageState 格式）。 要同时使用两个帐户，请使用自己的 `KB_HOME` 运行第二个守护进程（一个守护进程 = 一个配置文件）： ```bash KB_HOME=~/.kb-alt kb daemon start --profile account2 # 作为独立守护进程运行 ``` ## 附加到正在运行的浏览器 连接到使用 `--remote-debugging-port` 启动的 Chrome / Edge，而不是启动新的浏览器 — 其已登录状态、扩展和设置原样保留： ```bash # 1. 使用启用 CDP 的目标浏览器启动（专用配置文件） chrome --remote-debugging-port=9222 --user-data-dir="%LOCALAPPDATA%\kb-attach" # 2. 将 kb 附加到它 kb daemon start --cdp http://127.0.0.1:9222 kb tabs # 现有标签页原样可见 kb open myapp.example.com # 从这里一切正常 kb daemon stop # 仅断开连接；目标浏览器保持打开 ``` 限制： - **Chrome 136+ 禁用日常默认配置文件的远程调试**（安全更改）。使用专用 `--user-data-dir` 启动，如上所示，并在那里登录到您的服务一次 — 状态粘贴到该配置文件。 - 由于 kb 无法更改目标浏览器启动方式，`kb mode` / `kb profile` / `kb auth` 和 kb 的代理配置文件切换在附加时不可用（它们返回清晰的错误）。 - 其他所有操作 — 打开 / 点击 / 快照 / 评估 / 截图 / 网络日志 / 网络正文 / Cookie / 存储 — 均有效。 ## Chrome 扩展 Playwright 默认禁用扩展（`--disable-extensions`）；`--extensions` 提升： ```bash kb daemon start --extensions "C:\dev\my-extension" # 加载解包的扩展（以逗号分隔） kb daemon start --extensions on # 仅启用（使用已在配置文件中安装的扩展） kb daemon start --extensions off # 返回禁用（默认） ``` - **解包扩展** — 指向包含 `manifest.json` 的目录（不支持 `.crx` 文件）。方便您自己扩展的开发和测试。 - **商店扩展** — 以 `--extensions on` 启动有头模式，并在窗口中使用 Chrome 网上应用商店安装扩展（建议使用 chrome 频道）。它们在配置文件中持续存在，因此后续启动只需 `--extensions on`。 - 与 `--channel` / `--ua` 一样，设置会延续到下一个自动生成；使用 `--extensions off` 重置。 限制： - **解包扩展通过捆绑的 Chromium 加载**（当给出目录时，频道自动选择选择捆绑的 Chromium）。Chrome 137+ 稳定版删除了 `--load-extension` 标志，因此真正的 Chrome 无法加载它们（配置文件中安装的扩展的 `--extensions on` 在任何频道上都有效）。 - 也支持无头（自动选择新的无头模式）。 - 与 `--cdp` （附加）互相排斥 — 附加的浏览器本身安装的扩展原样工作。 ## API 调试 当您的 API 返回意外的结果时，请立即读取正文 — 无需 HAR 记录： ```bash kb net log --filter "api" # 记下每行开头的 #seq kb net body 42 # 打印响应正文（JSON 原样读取） kb net headers 42 # 所有请求/响应头部（Cookie、缓存控制等） ``` 要查看 UI 如何处理错误，请在原位覆盖实时端点： ```bash kb net mock "**/api/users" --status 500 --text '{"error":"internal"}' # 匹配请求现在返回 500 kb reload # 检查错误状态 kb net unroute 1 # 返回正常 ``` 自动为文本类型（JSON / HTML / JS / XML ...）的 XHR / fetch / 文档响应捕获正文。捕获截断为 **每个响应 256 KB**（32 MB / 500 条记录，总计，先进先出）：`--offset` 在捕获的部分内分页，但超过 256 KB 的内容无法恢复 — 如果您需要大响应正文，请使用 `kb request <url> -o <file>` 重新获取。 要直接访问端点，请使用 `kb request`（迷你 REST 客户端）： ```bash kb request localhost:3000/api/users # GET kb request localhost:3000/api/users -X POST -d '{"name":"a"}' # JSON 正文自动获得 Content-Type: application/json kb request api.example.com/v2/me -H "Accept: application/vnd.api+json" -H "X-Api-Version: 2" ``` 显式 `-H` 头部始终优先（仅当 Content-Type 未设置时，JSON 自动检测才生效）。 不需要页面，**Cookie 和代理设置与浏览器共享** — 如果您在浏览器中登录，身份验证 API 直接生效，`Set-Cookie` 响应流回浏览器。保存二进制响应并使用 `-o <file>`。 默认显示响应 **`Set-Cookie` 头部，每个头部一行**（多个 Cookie 保持可解析，而不是折叠成一行），`-i` 打印所有响应头部（MCP：`includeHeaders`）。使用 `--json` 时，`result.setCookies` 将各个 `Set-Cookie` 值作为数组保存（在 `kb log export` 包中像其他敏感头部一样屏蔽）。 ```bash kb request localhost:3000/api/login -X POST -d '{"user":"a"}' # Set-Cookie: sid=… 在正文上方显示 kb request localhost:3000/api/me -i # 所有响应头部 + 单个 Set-Cookie ``` 默认情况下遵循重定向。使用 `--no-follow` 停止在 3xx 处，或 **`--follow-verbose`** 遵循同时打印每个跳转的状态 / `Location` / `Set-Cookie` — 有助于查看链条落在何处以及在重定向过程中设置哪些 Cookie（方法处理与浏览器匹配：303 和 POST-on-301/302 变成 GET；307/308 保留）。使用 `--json` 时，中间跳转在 `result.hops` 中。 ```bash kb request example.com/login --follow-verbose # 302 → 301 → 200，每个跳转都有自己的 Set-Cookie kb request example.com/old-path --no-follow # 显示 3xx 自身而不是最终目标 ``` 操作记录与可分享的捆绑包 守护进程**默认记录操作**（命令、xhr/fetch/document流量、控制台输出）。在一次工作会话后，一个命令生成一个自包含的捆绑包，**任何人无需kb都可以阅读和重现**： ```bash kb log export # 生成./kb-log-<session>/ kb log export -o out --no-mask --allow "^cookie$" --deny "internal\.corp" ``` ``` kb-log-<session>/ ├─ report.md # 编号步骤 + 每步网络/控制台 + 截图（从这里开始） ├─ steps.md # 重现步骤（kb命令列表） ├─ events.jsonl # 屏蔽日志（机器可读） ├─ requests/ # 每个请求作为独立的curl .sh ├─ shots/ # 截图 └─ meta.json # 会话信息 ``` **默认情况下，敏感值被屏蔽** (`[MASKED]`)：填充输入，评估返回值，授权/cookie头部，身体中的密码/token类键，以及**URL查询字符串中的敏感键**（`?api_key=…`，包括位置/引用头部和身体中的URL）。使用显式的`--no-mask`取消屏蔽；使用`--allow` / `--deny`（正则表达式）进行微调。**本地原始日志（`~/.kb/logs/`）永远不会被修改** - 屏蔽仅在导出/显示时应用，因此可以随时重新生成报告。 注意事项：`eval`表达式和`net mock --text`参数会逐字记录（屏蔽目标值，而不是您编写的代码）- 如果您内联了机密，请在使用前使用`--deny <regex>`。**原始日志保留敏感值以明文显示**，因此请始终通过导出共享。旧会话在守护进程启动时自动修剪（默认：保留20个，可通过`KB_LOG_KEEP`配置）。 已知限制：嵌入在**URL路径段**中的值（`/verify/<value>` - 没有键名可以检测）不会自动屏蔽（查询字符串中的嵌套URL会递归屏蔽）。对这些使用`--deny <regex>`。 会话自动按守护进程运行分割，或使用`kb log start --name <n>`显式分割（添加`--shots`在每个操作后自动捕获截图 - 它们出现在report.md中）。使用`kb log show`获取最近事件，使用`kb log steps`获取编号的重现脚本。 记录的操作可以**原样重放**： ```bash kb log replay # 重新运行最新会话的操作（选项卡ID映射到活动选项卡） kb log replay mysession --dry-run # 预览将要运行的内容 kb log replay mysession --from 5 --continue-on-error ``` 由于重放会将选项卡ID重新映射到当前活动选项卡，**跨多个选项卡的录音可能无法完全重现**（单选项卡流程是目标）。 ## 代理配置文件（FoxyProxy风格） ```bash kb proxy add work --type http --host 10.0.0.1 --port 8080 --user u --pass p --bypass "*.internal" kb proxy use work # 立即应用，无需重启浏览器 kb proxy rule add "*.corp.example.com" work # 仅通过工作路由此主机（优先匹配） kb proxy test # 通过外部IP + 延迟验证 kb proxy status # 守护进程实际使用的 ``` 工作原理：Chromium始终指向守护进程内的本地中继代理；切换仅交换中继的上游。因此不需要重启，并且SOCKS5身份验证（Chromium原生不支持）有效 - 中继处理它。中继本身需要每个会话的令牌，因此其他本地进程无法使用它。 常见的上游设置： ```bash # 在企业代理（带有身份验证，内部主机直接） kb proxy addtype http --host proxy.corp.example.com --port 8080 \ --user myuser --pass mypass --bypass,localhost" kb proxy use corp # 通过本地mitm mock服务器开发 kb proxy add local --type http --127.0.0 --port 8081 kb proxy use local # 立即应用，无需重启 kb # 返回直接（的） ``` 当连接失败浏览器显示`ERR_TUNNEL_CONNECTION_FAILED`），` status`列出最近的连接错误（目标主机，，原因），并记录~/.kb/daemon.log## 从AI代理驱动 **从Claude Code开始，MCP是推荐的方式** - 原生工具，无需解析Bash输出： ```bash claude mcp add kb -- kb-mcp ``` 公开`kb_snapshot`、`kb_open`、`kb_text`、`kb_screenshot`（返回图像）、`kb_click`、`kb_fill`、`kb_select`、`kb_eval`、`kb_dialog`（响应confirm/prompt）、`kb_request`、`kb_net_log`、`kb_net_body`、`kb_net_headers`、`kb_proxy_use`等 - 24种工具。 **通过Bash**，所有功能都可用（每个命令都支持`--json`，具有对称的`{ok:true / `{ok:false,error}`）。推荐的循环： ```bash kb open example.com --wait idle # 为SPA使用idle kb snapshot # 使用引用发现元素 kb click --ref e12 # 操作（返回结果URL/标题） kb text # 读取结果 ``` **一次性操作以减少往返**：当目标可以通过文本识别时，请跳过快照 - Playwright的选择器引擎直接工作： ```bash kb click "text=Save" # 文本匹配在一个命令中 kb click "role=button[name='Save']" # 角色 + 可访问名称 ``` 使用引用，如果在重新渲染后引用过期，则自动重新解析为具有相同角色/名称的元素，因此您只在失败时重新快照。 **人在环中**：对于登录或CAPTCHA，用户直接使用窗口；代理在`kb wait --url "**dashboard**"`成功后恢复。流程打包为`kb login`. ## 安全研究和漏洞赏金 reconnaissance kb是一个适用于**授权**安全测试和漏洞赏金reconnaissance的强大驱动器 - 所有操作都通过上述： - **身份验证API测试 / IDOR** - `kb request`共享浏览器的cookie和代理，因此您在登录用户的情况下探测authz保护的端点；使用单独的配置文件（或通过`KB_HOME`的两个守护进程）运行两个帐户以对比对象访问。 - **SPA运行时reconnaissance** - `kb eval`在中运行任意JS并返回原始值（cookie，令牌，客户端路由表）而不进行编辑 - 可用于确认DOM XSS或提取客户端配置。 - **流量检查和篡改** - `kb net log / body / headers`读取捕获的请求和响应；`kb net mock / block`重写它们以探测错误处理和客户端信任。 - **代理链接** - 将kb的上游指向Burp或Caido，并通过可切换的拦截代理路由所有流量- **附加到真正的已登录会话** -p`重用您手动登录的Chrome（SSO / 2FA / passkey），因此无需重新登录即可进行真实身份验证目标。 - **可复制的证据** - `kb log export`生成一个**机密屏蔽**的捆绑包（报告 + 步骤 + 独立curl + 截图），您可以将其附加到报告中。 - **代理驱动， 无头** - 子代理可以并行运行侦察任务，而无需驻留守护进程。 > **只测试您有权测试的内容。** 遵循每个程序的参与规则 - 许多漏洞赏金程序禁止自动扫描，激进的请求速率或逃避其反机器人/ WAF控制。kb是一个驱动器，而不是许可证：请先确认范围和策略。 ## 架构 ``` kb (CLI) ──HTTP+token──▶ 守护进程 ── Playwright 持久上下文 ──▶ Chrome/Edge/Chromium kb-mcp (MCP stdio) ──┘ └─ 本地中继代理（令牌身份验证） ──▶ 上游代理（配置文件/规则） ``` 状态存活在`~/.kb/`（daemon.json / proxies.json / profiles/ / downloads/ / daemon.log）。 ## 开发 ```bash npm test # 构建 + 单元测试（node:test，无浏览器要求） npm run test:e2e # 构建 + 浏览器e2e冒烟测试（在隔离的KB_HOME中启动一个真正的守护进程；如果无浏览器，则自动跳过） npm run test:all # 两者 ``` ## 许可证 MIT