dsh-plugin-tool-guard

Readme

# 🛡️ dsh-plugin-tool-guard

[![npm version](https://img.shields.io/npm/v/dsh-plugin-tool-guard)](https://www.npmjs.com/package/dsh-plugin-tool-guard)
[![github release](https://img.shields.io/github/v/release/zhaoxuejie/dsh-plugin-tool-guard)](https://github.com/zhaoxuejie/dsh-plugin-tool-guard/releases)
[![license](https://img.shields.io/github/license/zhaoxuejie/dsh-plugin-tool-guard)](LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)

**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 零依赖）：

<img src="assets/demo1.png" alt="面板：状态总览（级别/暂停/今日拦截/待审批）" width="640"/>

<img src="assets/demo2.png" alt="面板：拦截记录（实时审计视图）" width="640"/>

<img src="assets/demo3.png" alt="面板：规则开关（运行时即时生效）" width="640"/>

> 宿主未加载客户端也不影响安全：审批走原生 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 下载源码安装

```bash
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 安装

```bash
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 生效）：

```yaml
- 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`](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`](docs/api.md) §4，规则细节与级别矩阵见 [`docs/rules.md`](docs/rules.md)。

```yaml
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`](LICENSE)。

### 相关文档

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