@zhaoxuejie

dsh-plugin-tool-guard

Name: dsh-plugin-tool-guard
Availability: InStock
Author: zhaoxuejie

DeepSeek Harness 工具调用安全守卫（防火墙）插件：危险命令拦截、路径白名单、敏感文件黑名单、人工审批与审计

Stars: 0
Language: TypeScript
Created: Sep 8, 2026
Updated: Sep 8, 2026

Auth

GitHub repo

Introduction

🛡️ dsh-plugin-tool-guard

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/<name>（$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/<name>/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；运行时立即作用于所有会话，重启后恢复配置默认值。

人工审批

命中 approve（strict 级别下最常见）→ DSH Web GUI 弹原生审批卡（宿主无 approval 服务时回退内置面板 + 聊天兜底）；
选择：允许（仅放行这一次）/ 允许本次会话（同会话同类操作后续直接放行）/ 拒绝（不执行，模型收到拒绝原因）；
超时（默认 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。