zhaoxuejie/dsh-plugin-tool-guard

🛡️ dsh-plugin-tool-guard

npm version
github release
license
node

DeepSeek Harness 工具调用安全守卫插件 —— 给 AI 的每一次工具调用装上防火墙：
拦截危险命令 · 禁止读取敏感文件 · 限定可操作目录 · 高危操作人工审批 · 全量审计留痕。

挂载即生效、卸载即失效，零侵入 Agent 业务代码：不改一行业务逻辑，规则引擎在每次工具执行前独立决策。

用途

面向 DeepSeek Harness（DSH）用户的工具调用安全层，核心能力：

| 能力 | 说明 |
|---|---|
| 🚫 危险命令黑名单 | rm -rf /、mkfs、dd if=、shutdown、fork 炸弹、curl \| bash 等内置正则，命中直接拒绝（无审批环节） |
| 🔒 敏感文件黑名单 | .env、.ssh、id_rsa、.pem、/etc/passwd 等 glob 模式，禁止 AI 读取 |
| 📁 路径白名单 | 只允许操作指定目录（默认=当前工作目录），resolve + realpath 防 ../../ 与符号链接绕过 |
| ✍️ 写入保护 | 覆盖已有文件 / 删除文件按配置要求人工审批；创建新文件放行 |
| 🖐 人工审批 | 原生 GUI 审批卡（允许 / 拒绝 / 允许本次会话）；超时默认拒绝（安全优先） |
| 📜 审计日志 | 每次工具调用记录：时间 / 会话 / 轮次 / 工具 / 脱敏入参 / 决策 / 命中规则 / 原因 |
| 🎚 三档安全级别 | loose 宽松 / standard 标准（默认）/ strict 严格（一切写入与 shell 需审批） |
| 🎛 管理工具 | 直接让 AI 调 guard_ 工具，或 HTTP 端点，或面板操作，三者同一套运行时状态 |

界面演示

Web GUI 侧边栏「🛡 安全守卫」面板（src/client.js，纯 DOM 零依赖）：

宿主未加载客户端也不影响安全：审批走原生 approval 通道（GUI 弹卡），或回退内置审批 + 聊天流兜底。

安装

本插件是 DeepSeek Harness 原生插件（Cordis 组合 + dsh.bundle.patch 自注册 + web 客户端面板），
不是独立应用，须装进某个 DSH profile 后由 loader 组合生效。插件按 profile 隔离，目录位于
$DSH_HOME/profiles/（$DSH_HOME 默认 ~/.deepseek-harness）；运行 GUI 一般用 web profile。

方式 A：从 GitHub 下载源码安装

git clone https://github.com/zhaoxuejie/dsh-plugin-tool-guard.git
cd dsh-plugin-tool-guard
npm install          # prepare 脚本自动 build → 生成 lib/（编译产物不入库，须构建后加载）

dsh plugin --profile web add file:./dsh-plugin-tool-guard   # 装进 profile，loader 自动应用 bundle patch
dsh web              # 重启 DSH，守卫即生效

跟随上游更新：git pull 后重跑 dsh plugin add；或改用 add link:./dsh-plugin-tool-guard
目录符号链接，源码即改即生效。npm 发布后也可一行直装（方式 B）。

方式 B：npm 安装

dsh plugin --profile web add dsh-plugin-tool-guard
dsh web

方式 C：手动 patch 挂载

在 patch 文件加一行（按生效范围选文件：$DSH_HOME/profiles//cordis.patch.yml
只对该 profile 生效；$DSH_HOME/cordis.patch.yml 对所有 profile 生效）：

- import: /绝对/路径/dsh-plugin-tool-guard/cordis.patch.yml

patchReload: live 的 profile 保存即热生效，startup 型需重启 DSH。

验证与卸载

- 验证：侧边栏出现「🛡 安全守卫」面板；对 AI 说「读取项目里的 .env」应被拒绝；GET /tool-guard/status 返回状态 JSON。
- 卸载：dsh plugin --profile web remove dsh-plugin-tool-guard，或删除手动添加的 patch 行。

用法

5 分钟快速体验

装好后直接对 AI 说下面的话，观察守卫拦下 / 放行：

| 你说的话 | 预期结果 |
|---|---|
| 「读取一下项目里的 .env」 | 🚫 拒绝：命中敏感文件黑名单 |
| 「执行 rm -rf D:\」 | 🚫 拒绝：命中危险命令黑名单 |
| 「读一下 C:\Windows\win.ini」（工作区外） | 🚫 拒绝：路径不在白名单 |
| 「切换到 strict 级别」→「写一个新文件 demo.txt」 | 🖐 弹审批卡，等你点允许 / 拒绝 |
| 「查一下最近的拦截记录」 | 📜 返回上面所有操作的审计条目 |

更细的图文教程见 docs/QUICKSTART.md。

安全级别

| 级别 | 行为 | 适合 |
|---|---|---|
| loose 宽松 | 仅拦极危险命令（rm -rf /、mkfs、shutdown 等），文件操作全放行 | 完全信任 AI、零打扰 |
| standard 标准（默认） | 危险命令 + 敏感文件 + 路径白名单；写入审批按配置 | 日常开发 |
| strict 严格 | 所有文件写入与 shell 命令均需人工审批；禁止暂停 | 跑不信任代码 / 重要机器 |

切换：guard_set_level(level) 工具 / 面板下拉 / POST /tool-guard/level / 配置 securityLevel；
运行时立即作用于所有会话，重启后恢复配置默认值。

人工审批

1. 命中 approve（strict 级别下最常见）→ DSH Web GUI 弹原生审批卡（宿主无 approval 服务时回退内置面板 + 聊天兜底）；
2. 选择：允许（仅放行这一次）/ 允许本次会话（同会话同类操作后续直接放行）/ 拒绝（不执行，模型收到拒绝原因）；
3. 超时（默认 120 秒）无人操作 → 按 defaultOnTimeout 处理（默认 deny，宁可误杀不放漏）。

暂停防护

guard_pause(minutes?)：暂停期间所有调用直接放行但仍记录审计；默认 10 分钟自动恢复；
严格级别禁止暂停（需先降级）。

审计日志

每次调用都留痕（入参自动脱敏），按会话隔离、单会话上限 200 条滚动覆盖；
查询：guard_recent_blocks(limit) / guard_stats() / 面板「拦截」页 / GET /tool-guard/recent；
audit.keepAfterUnload: true 时卸载归档到 ~/.deepseek-harness/audit/tool-guard-.json。

管理工具速查

| 操作 | 对 AI 说（工具） | HTTP |
|---|---|---|
| 查看状态 | guard_status() | GET /tool-guard/status |
| 查看统计 | guard_stats() | GET /tool-guard/stats |
| 最近拦截 | guard_recent_blocks(limit) | GET /tool-guard/recent |
| 切换级别 | guard_set_level(level) | POST /tool-guard/level |
| 暂停 / 恢复 | guard_pause(min?) / guard_resume() | POST /tool-guard/pause / POST /tool-guard/resume |
| 白名单增删 | guard_whitelist_add(path) / guard_whitelist_remove(path) | POST /tool-guard/whitelist/add / POST /tool-guard/whitelist/remove |

配置

以下为 cordis.patch.yml 参考配置（与 schema 默认值一致）；更完整的字段表见
docs/api.md §4，规则细节与级别矩阵见 docs/rules.md。

securityLevel: standard          # loose / standard / strict
rules:
dangerousCommands:
patterns: []                 # 危险命令正则；空 = 内置列表
pathWhitelist:
paths: []                    # 允许操作目录；空 = 仅当前工作目录
sensitiveFiles:
patterns: []                 # 敏感文件 glob；空 = 内置列表
writeProtection:
⚠️ 参考配置默认关闭覆盖/删除审批（日常开发免打扰）。
需要弹审批卡把关时改为 true，或直接用 strict 级别。
requireApprovalForOverwrite: false
requireApprovalForDelete: false
approval:
timeoutSeconds: 120            # 审批超时（秒）
defaultOnTimeout: deny         # 超时默认拒绝（安全优先）
pause:
autoResumeMinutes: 10          # 暂停自动恢复分钟数
audit:
keepAfterUnload: false         # true = 卸载时归档审计日志为 JSON
maxRecordsPerSession: 200      # 单会话最大审计条数（滚动覆盖）

面板「规则」页的开关运行时即时生效（重启还原为配置值）；guard_whitelist_add/remove
运行时增删白名单目录。

许可

MIT — 见 LICENSE。

相关文档

- docs/QUICKSTART.md — 快速上手教程
- docs/api.md — 接口参考（事件 / 工具 / HTTP / 配置）
- docs/rules.md — 内置规则与级别矩阵
- docs/PRD.md — 产品需求规格
- tests/run-tests.mjs — 端到端测试（npm test，81 断言）