Short-Arm-Ape/dsh-intranet-browser

dsh-intranet-browser
绕过 @yeesy369/dsh-browser-playwright 的 SSRF 保护

中文

概述

本插件修改自 @yeesy369/dsh-browser-playwright（上游源码仓库：xylt369/dsh-browser），并保持对服务定义包 @yeesy369/dsh-browser 的相同运行时依赖。

本插件将 ⚠️绕过 原插件的 SSRF 保护（url-guard.ts），以便 DeepSeek Harness 打开本地和局域网页面进行调试。它将调用一个独立的 Playwright 实例（独立服务名、独立配置文件目录、独立窗口）。

出于安全考虑，每次 intranet_ 工具调用都需要用户批准（默认 approvalMode: 'per-call'），并且云元数据端点默认保持封锁。

与原插件的关系

| 包名    | 原插件 browser-playwright | 本插件 intranet-browser                               |
| --------------- | ----------------------------- | ------------------------------------------------------------ |
| 服务名    | ctx.browser                 | intranet-browser（独立实例）                       |
| SSRF 保护 | 严格的 url-guard，未改动   | 已绕过（保留元数据封锁）                           |
| 浏览器窗口  | 自有 Edge 配置文件              | 另一个配置文件（默认 ~/.dsh/intranet-edge-profile） |
| 工具名      | browser_                   | intranet_                                                 |
| 批准        | 通过 web-permission          | 内置 ctx.approval 门控（每次调用）                     |

两个浏览器可以并行运行。

依赖与适配版本

| 名称 | 角色 | 版本 |
|---------|---------|---------|
| xylt369/dsh-browser | 上游源码仓库（改编自 @yeesy369/dsh-browser-playwright） | 0.8.1 |
| @yeesy369/dsh-browser | 运行时依赖（dependencies：服务定义类型） | ^0.6.0 |
| DeepSeek Harness | 目标宿主（dsh CLI） | 0.1.0-rc.7 / 0.1.1-rc.2 |

兼容性矩阵

| dsh 版本 | 状态 | 备注 |
|---|---|---|
| 0.1.0-rc.7 | ✅ 已验证 | 对等版本范围 >=0.1.0-rc.7 <0.2.0 覆盖它。设置中的 expose 选项在 rc.7 中已移除；插件不再传递它。 |
| 0.1.1-rc.2 | ✅ 已验证 | devDependencies 固定为 rc.2，因此类型契约针对该版本线进行检查。 |

开发与快速开始

1. 前置条件

- DeepSeek Harness CLI (dsh)：npm i -g @deepseek-ai/dsh
- Node.js ≥ 18 和 pnpm（npm i -g pnpm）

2. 构建包

在[此包的绝对路径]下执行：
pnpm install
pnpm build      # tsc → lib/，然后客户端打包 → lib/client.js
pnpm typecheck
pnpm test

单元测试覆盖 URL 策略（元数据块、文件/凭据/协议检查）和审批门控决策逻辑；真实浏览器行为可参照 browser-playwright 的 e2e 模式进行验证。

3. 手动安装到 DeepSeek Harness（web 配置文件）

该包从其本地路径安装——无需 npm 发布。

Windows 一键安装：
powershell -ExecutionPolicy Bypass -File scripts/install.ps1

macOS / Linux 一键安装：
bash scripts/install.sh

或手动操作（脚本正是执行此操作）：
dsh plugin --profile web add [absolute path to this package]

如果有正在运行的 DeepSeek Harness 实例，请重启它。

AI 调用 intranet_open；会出现审批提示（默认每次调用都提示）；只有在你批准后才会进行导航。然后继续使用 intranet_snapshot / intranet_click / intranet_screenshot 进行调试……

卸载

dsh plugin --profile web remove @short-arm-ape/dsh-intranet-browser

工具

| 工具 | 用途 |
| --- | --- |
| intranet_open | 打开 http(s)（可选 file）URL；允许 localhost/LAN/私有地址 |
| intranet_snapshot | 当前页面的无障碍快照（带引用） |
| intranet_screenshot | 截图作为持久图像附件（可供视觉模型使用）；可选 fullPage |
| intranet_click / intranet_type / intranet_fill / intranet_press | 页面交互 |
| intranet_scroll / intranet_wait | 滚动和有界等待（maxWaitMs） |
| intranet_back / intranet_forward | 历史导航 |
| intranet_list_tabs / intranet_open_tab / intranet_switch_tab / intranet_close_tab | 多标签页管理（标签页按 harness 会话隔离） |
| intranet_evaluate | 在页面中运行原始 JS——仅在 evaluate: true 时注册（默认关闭；需要重启） |
| intranet_close | 关闭内网浏览器窗口（释放配置文件锁） |
| intranet_arm / intranet_disarm | 仅在 approvalMode: 'arm' 下有意义：批准一次以激活/停用（在 per-call 下为空操作） |

配置

$DSH_HOME/settings.yaml（热重载；也可在设置 → 插件配置 → 内网浏览器下编辑 approvalMode / approvalScope / blockMetadata / blockedHostnames / windowVisibility / stealth；其余保留在 YAML 中）：

intranet-browser:
approvalMode: per-call     # per-call（默认，每次提示）| arm（intranet_arm 后不再提示）
approvalScope: all         # all（默认，每次调用都提示）| navigation（只读调用自由运行）
blockMetadata: true        # 继续阻止云元数据（169.254.169.254 / metadata.google.internal / instance-data …）
blockedHostnames: []       # 额外始终屏蔽的主机名/IP（已规范化：末尾点、IPv4 映射的 IPv6、整数 IP）
allowFile: false           # 允许 file:// URL
windowVisibility: visible  # visible（默认）/ hidden / headless — 在下次浏览器启动时生效
stealth: true              # 轻量级反检测
channel: null              # chrome / msedge，省略时自动检测
profileDir: ~/.dsh/intranet-edge-profile
maxWaitMs: 60000           # intranet_wait 上限
navigationTimeoutMs: 60000 # intranet_open / intranet_back / intranet_forward 超时
interactionTimeoutMs: 30000 # intranet_click / intranet_fill / intranet_press 超时
evaluate: false            # 暴露 intranet_evaluate（高风险）；在插件加载时注册，重启以切换

语义与限制

- 仅剩的检查是：scheme 必须是 http(s)（当 allowFile 为真时还包括 file）、不得内嵌凭据（user:pass@），以及默认的元数据黑名单。私有 IP / 回环 / DNS 解析筛查已移除 —— 这正是重点。
- 元数据黑名单在两个层面强制执行：初始导航 URL（在 goto 之前）以及浏览器上下文的每个请求（通过路由处理器）—— 重定向目标、XHR/fetch、iframe 及其他子资源均被覆盖，因此已批准的页面无法通过 302 或脚本方式访问元数据端点。黑名单匹配规范化后的主机名：末尾点、IPv4 映射的 IPv6 以及整数/十六进制/八进制 IP 变体均已处理；厂商端点（Azure metadata.azure.internal、腾讯 metadata.tencentyun.com、阿里云 100.100.100.200 等）均已包含。
- 审批是最后一道关卡：在 tools/pre-execute 瀑布流中，任何受门控的 intranet_ 调用若未获批准即被拒绝（故障关闭）。当没有审批服务或没有 agent 时，调用也会失败。拒绝和审批服务错误会被记录（[intranet-browser]）。
- approvalScope: navigation 允许只读调用（intranet_snapshot / intranet_screenshot / intranet_scroll / intranet_wait / intranet_list_tabs）无需提示即可运行；导航 / 写入调用仍然每次提示。它不会绕过请求级别的黑名单。
- 完全访问会话自动通过：当调用会话的审批策略为 never（完全访问 / danger-full-access 预设）时，intranet_ 调用无需提示即可通过 —— 用户已在会话级别选择退出审批提示，与 shell / 文件工具的信任级别一致。切换回 ask（例如 /permission workspace-write）会恢复每次调用的提示。
- Arm 模式仅在当前 agent 的进程生命周期内禁用提示；dsh 重启后需要再次执行 intranet_arm。在 per-call 模式下，intranet_arm 是文档中说明的空操作。
- 超时由配置驱动：maxWaitMs、navigationTimeoutMs、interactionTimeoutMs 在每次调用时从当前配置读取（热重载安全）；注册的工具超时是宽松的挂起保护。
- 默认情况下，元数据保持被阻止；在你不完全控制的网络之外，不要禁用 blockMetadata（例如，明确测试 IMDS 的云虚拟机）。
- 每次导航都会像 browser_ 工具一样返回 url / title / statusCode。
- 标签页按 harness 会话隔离；cookie 和本地存储通过单一持久化配置文件（~/.dsh/intranet-edge-profile）跨会话共享——请将已登录状态视为跨会话的。

模型体验

- 模型会看到 intranet_ 工具（描述中带有 SSRF 绕过 + 审批通知），以及页面文本/引用/截图附件；它永远不会看到 Playwright 或浏览器内部实现。
- 在 ask 策略下，每次 intranet_ 调用都可能触发审批提示；描述会告诉模型不要滥发请求，并先说明意图。在 never（完全访问）下不会出现提示。
- 长快照会消耗 token；截图以附件形式传输，而不是 base64。
- intranet_open 会返回最终 URL、标题和 HTTP 状态码，以便进行故障排查。