# 📦 @goodandready/dsh-shadow-auditor

<div align="center">

<h3>DeepSeek Harness 后台安全审计卫士、敏感凭据泄漏扫描与高危指令防火墙插件</h3>

<p align="center">
  <a href="https://www.npmjs.com/package/@goodandready/dsh-shadow-auditor"><img src="https://img.shields.io/npm/v/@goodandready/dsh-shadow-auditor.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
</p>

<!-- 官方展示中心跳转按钮 -->
<p align="center">
  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者全部项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="作者全部项目"></a>
</p>

<p align="center">
  <a href="README.md"><b>🇬🇧 English</b></a> •
  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
</p>

<table align="center">
  <tr>
    <td align="center">
      ⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。
      <br><br>
      🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。
    </td>
  </tr>
</table>

</div>

---

## ⚡ 插件概览

**`dsh-shadow-auditor`** 为 **DeepSeek Harness** 智能体提供全时段后台安全审计与高危命令拦截防护。

智能体在编写代码、处理配置或执行 Shell 脚本时，存在误将 API 密钥、私钥凭据提交至代码库或执行破坏性终端命令（如无边界 `rm -rf /`、数据库删库、敏感权限覆写）的风险。

本插件作为进程级安全防火墙，实时扫描代码 Diff 中的敏感信息，并在终端命令执行前执行语法级安全拦截。

```mermaid
graph LR
    subgraph AgentExecution [智能体操作执行流]
        Agent[🤖 智能体: 编写代码 / 准备执行命令] --> Intercept{安全前置拦截器}
    end

    subgraph SecurityEngines [dsh-shadow-auditor 引擎]
        Intercept --> SecretScan[🔑 敏感凭据与 API Key 扫描器]
        Intercept --> CmdGuard[🛡️ 高危终端命令安全防火墙]
    end

    subgraph Enforcement [阻断与日志审计]
        SecretScan -->|安全| Pass[✅ 放行执行]
        SecretScan -->|检测到泄漏| Block1[⛔ 实时阻断并脱敏敏感信息]
        CmdGuard -->|安全| Pass
        CmdGuard -->|高危风险| Block2[⛔ 阻断执行并要求人工确认]
        Block1 --> AuditLog[📋 安全审计日志与可视化面板]
        Block2 --> AuditLog
    end

    style AgentExecution fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
    style SecurityEngines fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
    style Enforcement fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
```

---

## ✨ 核心特性

### 1. 🔑 密钥与敏感凭据前置扫描
* 实时正则与香农熵扫描 API 密钥、私有令牌、RSA/SSH 密钥与数据库凭据；
* 在传输至大模型或写入版本控制前提前拦截；
* 审计日志自动掩码与脱敏。

### 2. 🛡️ 破坏性命令安全防火墙
* 在终端执行前分析 Shell 命令语法与参数；
* 拦截高危危险命令（无界 `rm -rf`、清空磁盘、fork 炸弹、危险 `dd`）；
* 工作区边界防护 (#103)：严格拦截针对系统根路径或解析超出当前会话工作区外的递归删除命令；
* 关键系统路径保护 (#105)：无条件保护敏感核心目录 (`~/.dsh`, `~/.claude`, `~/.ssh`, `/etc`, `/usr`, Windows 系统目录)；
* 试运行标志放行 (#104)：自动识别预检标志 (`-WhatIf`, `-Confirm`, `--dry-run`, `git clean -n`)，允许安全预检而无需触发误拦截。

### 3. 🪝 多阶段生命周期拦截引擎 (`lib/guards/lifecycle-hooks.js`)
* **优先拦截注册 (`prepend: true`)** (#125)：确保安全钩子位于 Cordis 处理器队列首位，先于第三方插件执行；
* **无条件严重威胁阻断 (`secretBlockCritical`)** (#124)：针对系统根破坏、磁盘格式化、AWS及私钥外发等高危行为，即使处于 `audit_only` 或 `warning` 模式亦强制阻断；
* **用户交互审批模式 (`ask`)** (#108)：在 `tools/pre-execute` 阶段与 DSH 审批机制无缝联动，高危操作返回 `{ kind: 'ask', reason, displayReason }` 请求用户确认；
* **用户输入提示词前置过滤 (`agent/pre-step`)** (#110)：在大模型处理前扫描用户消息，及时拦截 Prompt 注入与越狱攻击 (`{ kind: 'reject' }`)；
### 4. 🔒 可逆脱敏与占位符引擎 (`lib/mask/`)
* **单调递增占位符与实体复用** (#126, #127)：在 `agent/pre-step` 阶段自动扫描提示词，将 API 密钥、私钥、邮箱、IPv4 及电话替换为单调占位符（`<KEY_1>`, `<EMAIL_1>`, `<IP_1>`）；同一会话内相同实体自动复用既有占位符；
* **长度降序消除前缀碰撞** (#128)：恢复解密时按占位符长度严格降序处理（优先替换 `<KEY_10>` 再处理 `<KEY_1>`），避免子串切片破坏；
* **会话还原命令** (#136)：授权用户可在终端通过斜杠命令本地还原原始内容：
  ```text
  /shadow-auditor restore <masked-text>
  ```
* **会话日志零泄露不变量** (#135)：发送给大模型的上下文和本地落盘的 JSONL 日志中绝不包含明文机密。

---

## 📦 安装指南

```bash
dsh plugin --profile web add @goodandready/dsh-shadow-auditor
```

---


---

## 🔄 版本记录

### v0.2.9 (安全功能演进与规范语言支持)
- **规范语言标准**：代码及界面全面支持英文（`en`）与中文（`zh`）；俄语本地化通过 `goodandready/dsh-russian-lang` 维护。
- **发布包规范**：彻底清除 `AGENTS.md` 与 `index.md` 等非产品文件；严格执行单个文件 $\le 256$ KiB 上限。
- **实时拦截与审计日志流**：支持按全部、Shell 防护、差异网关和高风险进行分类过滤与刷新。
- **自定义安全策略**：支持命令与敏感路径的自定义正则表达式黑名单，并提供强制阻断与仅审计模式。
- **差异网关可视化检查与修复建议**：展示可疑代码行高亮及安全替代建议（Safe Remediation）。
- **文件完整性与敏感锚点监控**：主动拦截对 `.env`、`settings.yaml` 及密钥文件的读写尝试。
- **合规审计导出**：界面一键导出 JSON 日志或 Markdown 审计对账单。

### v0.2.8 (界面统一与设置同步)
* **统一UI设计风格（对齐 `dsh-clinebot`）**：采用原生 DSH 设计令牌，将设置页面重构为4个结构化卡片分区，提供一致的网格布局、状态徽标与表单控件。
* **完整的配置响应式同步**：草稿状态完整支持 `diffGateMode`、`enableSastScan` 和 `enablePromptInjectionScan` 的持久化保存。
* **异常处理增强**：消除静默 catch 代码块，增加规范的日志记录。
* **测试覆盖扩充**：新增 `test/ui-and-stability-028.test.mjs` 测试套件（26项测试全部通过）。

### v0.2.7 (稳定性与误报优化)
* **消除 secret-write 误报**：不再对 `check_token.js` 或 `test_secret.py` 误报拦截，仅严格保护 `.env`、`.credentials`、SSH密钥等核心凭据。
* **SAST 注释智能过滤**：包含 SQL 关键字或 eval 示例的注释不再触发误报；允许通过 `import.meta.url` 和 `__dirname` 进行安全相对路径解析。
* **Diff 门禁资源保护**：超长行（>2048字符）截断扫描防卡死；测试文件自动跳过 prompt injection 检查。
* **安全 /audit 命令**：默认加载最近 50 条记录，防止大日志导致内存溢出（支持 `--all`）。
* **后台标签页轮询节流**：网页不可见时自动暂停状态轮询。

### v0.2.4 (DSH 插件规范修复与设置卡片优化)
* **Web UI 设置卡片参数补齐**: 在前端卡片中完整支持审计日志参数 (`enableAuditLog` 启用日志、`maxFileSizeMb` 文件大小上限、`retentionDays` 归档保存天数)，并支持中英俄本地化 (#34)。
* **消除双重插槽注册**: 移除了针对 `settings.section` 的 `setTimeout` 延迟回退机制，确保卡片原子化、稳定注入至 `settings.plugin.item` (#35)。
* **配置不可用时禁用表单**: 当设置快照处于 `unavailable` 状态时，表单控件与保存按钮自动禁用 (`disabled: true`) 并显示不可用提示 (#32)。
* **清理无用对等依赖**: 从 `package.json` 的 `peerDependencies` 中移除了未引用的 `@deepseek-ai/dsh-credentials` (#33)。
* **样式隔离**: 为 `<style>` 标签附加 `data-dsh-plugin="dsh-shadow-auditor"` 属性，防止被相邻插件清理。
* **设计契约**: 新增 `docs/design/DESIGN.md`，确立界面契约与状态流转规范。

### v0.2.3 (网络外发误报热修复)
* **消除合法 API 调用的误报**: 允许通过 shell 从本地凭据配置读取密钥并作为请求头传入 (如 `K=$(grep KEY ~/.dsh/.credentials.yaml) && curl ... -H "Authorization: Bearer $K"`).
* **精确网络外发攻击分析**: 仅针对将凭据文件本身作为负载传输 (`-d @.env`, `-F file=@...`, `--post-file=...`)、直接管道传输 (`cat .env | curl/nc`)、输入重定向 (`< .env`) 以及远程文件拷贝 (`scp/rsync`) 进行阻断。

### v0.2.0 (全功能审计套件、风险评分与外发防护)
* **DSH 聊天斜杠命令 `/audit`**: 在对话中直接生成详尽的运维风险账单 (Operation Bill)——汇总工具调用次数、风险评分 (0–100)、可疑调用明细表以及被拦截的危险指令。支持参数：`--turn` (仅限当轮)、`--all` (全量历史)、`--json`、`--since=YYYY-MM-DD`。
* **持久化审计归档 `AuditRecorder`**: 将调用事件以 JSONL 格式保存在 `<DSH_HOME>/shadow-auditor/<yyyy-mm>.jsonl` 中，依托 Promise 写入队列消除并发竞争，单文件超过 50 MB 自动 `.gz` 压缩并保留 30 天。
* **深层内核遥测钩子**: 全局监听 `tools/result` 获取工具真实执行结果 (`result.isError`) 与脱敏报错信息，并通过 `session/event` (`turn/end`) 精确切分交互轮次。
* **凭据网络外发防御**: 拦截携带敏感凭据文件 (`.env`, `id_rsa`, `.git-credentials` 等) 的网络工具调用 (`curl`, `wget`, `scp`, `ssh`, `nc`, `socat`)。
* **越界重定向防御**: 拦截指向工作区外部（如 `/etc/`, `~/.bashrc`, `%USERPROFILE%`, cron）的 shell 输出重定向 (`>` 与 `>>`)。
* **智能 `git push --force`**: 严格锁定受保护分支 (`main`, `master`, `prod`) 及受控远端的强制推送，同时保留开发者本地特性分支的自由 rebase 能力。
* **确定性风险评分 (0–100)**: 无需消耗大模型 token 的快速风险定级引擎，配备 10 分钟滑动窗口识别高频同类操作与连续高危行为。
* **不动点递归脱敏**: `redactText` / `redactValue` 模块递归清理深层嵌套结构中的 token、密码及 `.env` 敏感赋值，直至数据完全收敛。

### v0.2.6 (代码安全 Diff 门禁与 SAST 引擎)
* **代码安全 Diff 门禁 (`lib/diff-gate/`)**: 在代理操作确认边界处对补丁和文件变更进行多类别静态分析。
* **规范化发现模型**: 稳定规则标识符 (`SEC-*`, `SAST-*`, `PI-*`)、严重性评级、风险解释与修复建议。
* **增强型凭证扫描器**: 支持香农熵检测及高熵密钥识别。
* **轻量级 SAST 规则集**: 检测 SQL 注入、命令注入、路径遍历、硬编码密码与 eval 代码执行。
* **提示词注入启发式扫描**: 识别隐藏在代码变更中的越狱与系统提示词窃取指令。
* **门禁策略 (`disabled`, `warning`, `block`)**: 可在设置面板配置，block 模式可阻断高危漏洞。
* **行内误报抑制**: 支持 `// shadow-audit-ignore: <ruleId>` 局部忽略规则。

### v0.2.5 (稳定性、内存管理与UI盾牌组件重构)
* **会话头部安全盾牌插槽 (`conversation.session.header.utilities`)**: 注入实时 `AuditShieldChip` 组件，显示安全状态与快速审计弹窗。
* **审计日志 OOM 防护**: `AuditRecorder` 增加 `readRecent(limit)`，默认仅读取近期记录，不再解压历史 `.gz` 文件。
* **斜杠命令 `--limit=N`**: `/audit` 默认显示最近 50 条记录。
* **内存泄漏清理**: 增加会话生命周期监听与 LRU 缓存上限。
* **消除命令误报**: 允许 `grep -i kill` 与 `systemctl status`。
* **移除冗余工具**: 移除 `shadow_auditor_rules_list` 降低模型提示词负担。

### v0.1.4 (设置插槽注册热修复)
* **声明感知的插槽注入 (`settings.plugin.item`)**: 设置卡片注册全面迁移至 `ctx.slots.inject`，彻底解决在父级插槽尚未声明时直接注册导致的加载器崩溃 (`slot is not declared`)。
* **后备设置项 (`settings.section`)**: 在当前 DSH 构建缺少插件卡片插槽时，自动降级至独立设置分区，并通过 `ctx.effect` 安全管理生命周期。

### v0.1.3 (安全加固与稳定性修复)
* **复合命令链式分析 (`findDangerous`)**: 解析 `&&`、`||`、`;` 和换行续行命令，杜绝利用白名单安全命令掩盖高危操作 (`systemctl status && rm -rf /`) 的绕过漏洞。
* **精准密钥过滤 (`scanSecrets`)**: 修复包含 "example" 子串的真实有效密钥被误放行的问题。
* **敏感凭据脱敏保护 (`maskSecret`)**: 拦截到的密钥在存入审计日志、HTTP API 返回及 Web UI 渲染前均执行脱敏 (`sk-pr...****...1234`)。
* **文件全量扫描**: 移除文件写入/编辑时 8 KB 的扫描上限截断，完整检测任意体积的文件。
* **Cordis 生命周期与上下文完善**: 工具注册统一交由 `ctx.effect` 管理，支持热重载注销；修复 `approval/asked` 事件上下文。
* **Web UI 体验与内存泄漏优化**: 移除导致表单编辑冲突的定时重置逻辑，仅在面板展开时轮询审计接口，防止组件卸载时发生内存泄漏。
* **API 缓存控制**: 为 `/dsh-shadow-auditor/audit` 路由显式增加 `Cache-Control: no-store` 标头。

---

## 📄 开源协议

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

## v0.2.11 变更
- 审计发现描述全面标准化为英文与中文，代码库零西里尔字母 (#47)
- 设置卡片支持一键检查与平滑升级模块 (#48)
- 加固 HTTP 路由：限制 GET 方法并实施严格调用来源校验 (#49)
- 将内部规划文档从 git 跟踪与 npm 发布包中剔除 (#50)
- 清理工作树中残留的历史版本 .tgz 压缩包 (#51)
- 全面迁移至 DSH 原生 CSS 变量与设计令牌，消除硬编码颜色 (#52)
- 在 package.json 中补齐声明客户端 inject 依赖清单 (#53)
- 新增持久化审计写入故障监控与不可读行数统计指标 (#54)
- 使用 ctx.effect 包装语言注册并在插件卸载时安全清理 (#55)

## v0.2.10 变更

本版本修复两种命令防护误报，保留递归删除和受保护文件写入防护，并为尽力而为的失败添加安全调试诊断。

当没有递归标志时，命令防火墙允许 rm -f；仍会拦截 rm -r、rm -rf，以及组合或分开的递归标志。受保护文件写入检查按 shell 命令和管道阶段分别执行，因此前一条命令的 stderr 重定向不会误影响后续读取。使用 grep、cat 或非原地 sed 读取 settings.yaml 可以通过；重定向、tee 和原地编辑等写入仍会拦截。

分析器会识别引号和转义分隔符。这些改动不改变网络、SQL、服务控制、受保护 Git、设备写入或工作区逃逸规则。命令检查是有界分析，并非完整 Bash AST。