# dsh-guardian

[![CI](https://github.com/lonelymoon87/dsh-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/lonelymoon87/dsh-guardian/actions/workflows/ci.yml)
[![最新 DSH 兼容性](https://github.com/lonelymoon87/dsh-guardian/actions/workflows/dsh-compatibility.yml/badge.svg)](https://github.com/lonelymoon87/dsh-guardian/actions/workflows/dsh-compatibility.yml)
[![Release](https://img.shields.io/github/v/release/lonelymoon87/dsh-guardian)](https://github.com/lonelymoon87/dsh-guardian/releases/latest)
[![License](https://img.shields.io/github/license/lonelymoon87/dsh-guardian)](./LICENSE)

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的运行时危险操作策略、规范结果脱敏和安全审查工作流。

v0.1.3 已针对 DSH 0.1.0-rc.8 与 0.1.1-rc.1 验证，同时保留兼容 rc.6 的 peer 范围。项目继续通过 GitHub Release 分发预构建包。未加 scope 的 npm 包名已被其他发布者占用，因此本项目不在该名称下发布。

[English](./README.md)

## MVP

- 在 `tools/pre-execute` waterfall 中检查 shell、SQL 和结构化文件写入参数，返回 `deny`、`ask` 或保持原决策；
- 提供 `standard`、`strict` 和 `permissive` 三档策略，同时保留不可关闭的拒绝规则；
- 允许用正则表达式添加部署环境专属的 `deny` 或 `ask` 规则；
- 在 `tools/post-execute` waterfall 中对规范 JSON 结果、失败输出、渲染文本和拦截反馈做统一脱敏；
- 把连续文本块作为一段内容扫描，避免通过跨块拆分密钥绕过检测；
- `/security-review` 加载内置的只读安全审查技能。

本插件不是进程沙箱、授权系统或完整的数据防泄漏服务，也不会取代下游 provider 已有的安全策略。

## 策略行为

内置规则会拒绝对根目录或用户目录执行递归强制删除、把网络响应直接管道传给 shell、向 `/dev` 写入原始数据以及写入 `/etc`。强制推送、破坏性 SQL 和其他递归强制删除会要求审批。严格模式还会要求审批 `sudo`，宽松模式只保留拒绝规则。

Guardian 始终调用 `next()`。当其他策略监听器也返回决策时，插件保留更严格的结果，优先级依次为 `deny`、`ask`、`allow`。

## 脱敏行为

内置模式覆盖 AWS access key ID、GitHub token、`sk-` API key、PEM 私钥块和常见凭据赋值。存在规范 JSON 值时，插件优先脱敏该值，并保留数组、对象、数字、布尔值和 null 的结构。这样可以避免 Code Mode 或后续渲染器在安全显示文本背后继续持有未脱敏结果。

日志只记录工具名、匹配数量和脱敏标签，不记录秘密内容。插件不会追加自定义会话事件，因为当前外部插件 API 无法声明 ignorable 事件信封。写入必须识别的未知事件会导致用户卸载插件后无法读取旧会话。

## 权限与数据

- Guardian 在当前 DSH 进程内检查工具名、参数、规范结果和渲染输出。它可以拒绝调用或要求审批，但不会自行执行目标操作。
- 脱敏会在后续模型可见消费者收到规范结果前替换秘密文本。日志只保留工具名、匹配数量和不含秘密的标签。
- 插件不读取凭据存储，不发起网络请求，不写入工作区文件，不发送遥测，也不持久化自定义会话事件。

## 安装

当前代码支持 DSH `>=0.1.0-rc.6 <0.2.0` 插件 API，要求 Node.js `^22.19 || >=24`。

```sh
dsh plugin --profile web add https://github.com/lonelymoon87/dsh-guardian/releases/download/v0.1.3/dsh-guardian-0.1.3.tgz
```

Release tarball 已预构建，不需要构建权限。也可以固定版本从源码安装。

```sh
dsh plugin --profile web add github:lonelymoon87/dsh-guardian#v0.1.3
```

源码安装会运行本包的 `prepare` 构建。pnpm 10 及以上版本默认拒绝执行，第一次安装失败时请按 DSH 输出的提示，将准确的包键加入 profile 的构建白名单，然后重新执行同一条命令。需要装进一次性 Agent profile 时，把命令中的 `web` 换成 `headless`。

升级时用新版本的 Release URL 再执行一次 `dsh plugin add`。卸载时执行

```sh
dsh plugin --profile web remove dsh-guardian
```

## 配置

```yaml
- id: guardian
  name: dsh-guardian
  config:
    profile: standard
    rules:
      - name: production-host
        pattern: production\\.internal
        action: ask
        reason: production target requires review
    redaction:
      enabled: true
      patterns:
        - label: internal-token
          pattern: INT_[A-Z0-9]{12}
```

正则 flags 只允许 `i`、`m`、`s` 和 `u`。表达式或标签无效时，插件会在加载阶段明确失败。

## 发布验证

测试覆盖全部内置规则的正反例、结构化路径、策略组合、嵌套规范值、自定义凭据、跨块秘密、禁用脱敏、命令分派和非法配置。

- v0.1.3 tarball 已从 HTTPS Release URL 直接安装进全新的 DSH 0.1.0-rc.8 与 0.1.1-rc.1 profile；
- pack 产物与固定版本 GitHub 源码安装均通过 `dsh --dump-config` 检查；
- CI 覆盖 Node 22.19 与 Node 24，兼容矩阵会分别使用 DSH 0.1.0-rc.8、npm `latest` 与 `next` 标签重跑真实安装；
- bug 与兼容性问题统一进入 [GitHub Issues](https://github.com/lonelymoon87/dsh-guardian/issues)。

## 许可证

[MIT](./LICENSE)