# dsh-plugin-tool-guard — 内置规则清单（Rules Reference）

> 规则引擎：`src/guard-engine.ts`；单规则实现：`src/rules/*.ts`。
> 规则检查为纯字符串 / 路径匹配，毫秒级完成；正则每次调用预编译（单条编译失败跳过并告警）。

---

## 规则执行顺序

```
危险命令黑名单（reject）→ 敏感文件黑名单（reject）→ 路径白名单（reject）→ 写入保护（approve/allow）→ 严格级别 shell 审批
```

任一规则命中即短路返回；全部通过则放行。管理类工具（guard_*）在任何规则之前直接放行（但记录审计）。

## 安全级别 × 规则矩阵

| 规则 | loose（宽松） | standard（标准） | strict（严格） |
|---|---|---|---|
| 危险命令黑名单 | ✅ reject | ✅ reject | ✅ reject |
| 敏感文件黑名单 | — | ✅ reject | ✅ reject |
| 路径白名单 | — | ✅ reject | ✅ reject |
| 写入保护（覆盖/删除需审批） | — | ✅ approve | ✅ approve |
| 创建新文件 | 放行 | 放行 | ✅ 审批 |
| shell 命令（安全命令） | 放行 | 放行 | ✅ 审批 |
| 暂停防护 | ✅ | ✅ | ❌ 禁止 |

---

## 规则1：危险命令黑名单（dangerous-commands.ts）

匹配 shell 工具的 `command` 参数（正则，大小写不敏感）。内置模式：

| 类别 | 模式（节选） |
|---|---|
| 递归删除 | `rm -rf /`、`rm -rf ~`、`rm -rf *`、`rm -rf C:\`、`Remove-Item -Recurse -Force` 根目录、`rm -rf C:\Windows` |
| 磁盘操作 | `mkfs*`、`fdisk`、`parted`、`dd if=`、`Format-Volume`、`Clear-Disk`、`Initialize-Disk` |
| 系统电源 | `shutdown`、`reboot`、`halt`、`poweroff`、`Stop-Computer`、`Restart-Computer` |
| fork 炸弹 | `:(){ :|:& };:` 及其变体 |
| 权限篡改 | `chmod 777 /`、`chmod -R` 根目录、`chown -R` 根目录 |
| 远程执行 | `curl ... \| bash`、`wget ... \| sh`、`iwr ... \| iex`、`IEX(...)`、`Invoke-Expression ... DownloadString` |

**绕过风险提示（PRD §8）：** 正则黑名单无法覆盖所有变种（引号变形、变量拼接、混淆编码）。缓解：
1. 严格级别下所有 shell 命令需人工审批；
2. 支持配置扩展模式列表；
3. 规则4（写入保护）与规则2（白名单）独立执行，不依赖单一规则。

## 规则2：路径白名单（path-whitelist.ts）

- 默认白名单：配置 `rules.pathWhitelist.paths`；为空则使用会话工作目录（`session.header.cwd`）；`guard_whitelist_add` 运行时追加。
- 提取入参中的路径字段：`file_path / path / paths / directory / dir / file / target / root`（支持数组）。
- 路径解析：`path.resolve`（相对路径基于会话 cwd）+ `fs.realpathSync.native`（文件存在时解析符号链接）→ 防 `../../` 与符号链接绕过。
- 目录边界校验：`C:/project` 不会误匹配 `C:/project-other`。
- 命中 → `reject`，返回「路径不在白名单内」。

## 规则3：敏感文件黑名单（sensitive-files.ts）

glob 匹配（支持 `** / * / ?`），同时检查「原始入参路径」与「解析后绝对路径」两个形态。内置模式：

```
**/.env  **/.env.*  **/.ssh/**  **/id_rsa  **/id_rsa.pub  **/id_ed25519  **/id_ed25519.pub
**/*.pem  **/*.key  **/*.p12  **/*.pfx  **/credentials.json  **/secrets.yml  **/secrets.yaml
**/.aws/**  **/.npmrc  /etc/passwd  /etc/shadow  /etc/sudoers  **/.netrc
```

命中 → `reject`（读取类工具）。

## 规则4：文件写入保护（write-protection.ts）

| 场景 | 决策 |
|---|---|
| write 创建新文件 | `allow`（标准级别） |
| write 覆盖已有文件 | `approve` |
| edit 修改已有文件 | `approve` |
| 删除任意文件 | `approve` |
| strict 级别任意写入 | `approve` |

审批通过后的可选增强：「允许本次会话」会把 `规则名 + 工具名 + 关键入参` 记入会话放行集合，同会话同类操作后续直接放行（PRD §3.2 功能6）。

---

## 规则开关运行时覆盖

面板「规则」页与 HTTP `POST /tool-guard/rule` 可即时开关任一规则（`dangerousCommands / pathWhitelist / sensitiveFiles / writeProtection`），立即作用于所有会话；重启后恢复配置默认值。