策略护栏 xiangshu2026/dsh-alpha-guard

dsh-alpha-guard

原仓库：https://github.com/xiangshu2026/dsh-alpha-guard 如果你是从别处下载的，建议回原仓库获取最新版与 issue 支持。

给 DeepSeek Harness 的 AI 助手加一层策略护栏：读哪些文件、写哪些目录、能跑哪些命令、子代理能干什么、下载的可执行文件是否可疑——在工具调用真正执行之前做一次检查。

⚠️ 先读这段：它不是什么

这不是防病毒软件。不是沙箱。不是内核级隔离。不是安全产品。

请把期望值放低，再往下看：

| 你可能以为 | 实际情况 |
| 「装了就不会中毒」 | ❌ 完全不成立。它不扫描病毒库，不做实时文件监控 |
| 「能挡住恶意程序」 | ❌ 挡不住。它只对可执行文件做静态特征扫描，加壳/加密的样本特征全无 |
| 「能防止数据泄露」 | ❌ 只能拦已知的敏感路径被读取，动态拼接路径、编码载荷都能绕过 |
| 「AI 被攻击也安全」 | ❌ 提示注入可能让 AI 自己拼出绕过路径；文本扫描挡不住有心人 |
| 「能替代 Defender」 | ❌ 绝对不能。两者不是一个层面的东西，请始终开着系统自带防护 |

它的准确定位：一道很浅的、针对「AI 助手误操作」的减速带。

两个「2 分钟」是硬限制，不是建议：
- 临时关防护：2 分钟后自动恢复，不能设成「一直关着」
- 放行一次安装：2 分钟内有效、只用一次，用完即废

这两个设计就是为了防止「关着关着忘了开」「放行一次放行一辈子」。

它真正擅长的事只有一件：当 AI 想干一件明显不该干的事时，拦一下、记一笔。
比如 AI 突然要读你的 SSH 私钥、要格式化 C 盘、要往系统目录写文件、要装一个来路不明的程序——这些它能拦。仅此而已。

不要用它替代任何真正的安全措施。 真正的隔离要靠独立用户 / 容器 / 虚拟机。

适用场景（它适合谁）

✅ 适合：
- 你想给 AI 助手加一道「别手滑」的保险
- 你想知道 AI 到底尝试过哪些操作（审计日志）
- 你是个人用户，在自己电脑上跑，希望有个基本提醒
- 你把它当成第一层过滤，后面还有别的防线

❌ 不适合：
- 企业环境、多人共用的机器（它不区分「谁」在操作）
- 你指望它能挡住针对性的攻击
- 你要处理敏感数据、受监管数据
- 你需要合规认证（它没有任何认证）

一句话：这是初步防护，是「聊胜于无」的那一层，不是「万无一失」的那一层。

安装

方式一：作为 DSH 插件安装（推荐）

dsh plugin --profile desktop add github:xiangshu2026/dsh-alpha-guard

或者克隆到本地再装：

git clone https://github.com/xiangshu2026/dsh-alpha-guard.git
dsh plugin --profile desktop add ./dsh-alpha-guard

装完重启一次 DSH（host 半边是 Node 模块，需要重启才换上新代码）。
启动日志里出现 [alpha-guard] active; config=<路径> 即为生效。

首次启动会自动生成默认配置到 %USERPROFILE%\.dsh\alpha-guard\config.json。

方式二：手动链接（调试用）

mklink /J "%USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-alpha-guard" "<本仓库路径>"

然后在 profile 的 cordis.patch.yml 里加上 dsh-alpha-guard 那一行（见 cordis.patch.yml）。

换机器 / 换用户名要改什么

什么都不用改。 默认配置里所有路径都从 os.homedir() 推导。

工作盘不在主目录下时，用环境变量加白：

setx DSH_GUARD_EXTRA_ROOTS "E:\work;D:\projects"

自测

node test/selftest.mjs

92 个用例。全部通过会打印 ALL SELFTESTS PASSED。
注意：这些用例只验证「策略判断逻辑对不对」，不验证「真实世界安不安全」。

它能做什么（功能说明，不打包票）

下面每条都写清楚「能拦什么」和「拦不住什么」。请按「能拦一半」来预期。

1. 读取白名单

read / read_image / glob / grep 只能访问 read.allowRoots 里的目录，外加当前会话工作区。

- 能拦：AI 直接去读 D:\某个没加白的目录
- 拦不住：pwsh / run_code 里用变量拼出来的路径（文本扫描看不到真值）

2. 敏感区拒绝

凭据文件、密码管理器库、DSH 会话日志与记忆目录、.ssh / .gnupg / .aws、浏览器配置与 Login Data、微信 / QQ 聊天记录、Windows SAM / SECURITY、其他用户目录、UNC 网络共享。

- 能拦：AI 直接写 Get-Content ~/.ssh/id_rsa
- 拦不住：String.fromCharCode(46,115,115,104) 这种运行时拼出来的路径（代码里能看到「字符串拼接」这个动作，但看不到拼完是什么）

3. 写入保护

系统目录、凭据、防护配置自身、DSH 安装目录、其他用户目录禁止写入或删除。

- 能拦：Remove-Item C:\Windows\...
- 拦不住：一个已经在跑的脚本内部去删东西（那不在工具调用层面）

4. 危险命令拦截

格式化 / 分区、改引导、关机重启、删根目录、禁用 Defender / 防火墙、加管理员账号、导出 SAM / LSASS、下载即执行、-EncodedCommand。

- 能拦：明文写出的危险命令
- 拦不住：Base64 编码后由别的程序解码执行、从文件里读命令再跑

5. 安装审批

系统包管理器安装、Windows 安装包、DSH 插件安装、全局包安装、下载可执行文件——默认拒绝，需要主人手动放行。

- 能拦：AI 自作主张 winget install xxx
- 拦不住：把 .exe 先改个名字再下载，或者分几步把安装动作拆开

6. 子代理隔离

子代理 / 队友只能读写「工作区 + 临时目录」，禁用 memory、dtodo、 de_channel_send、再嵌套开子代理。

- 能拦：子代理试图读主会话的记忆
- 拦不住：子代理把读到的内容通过别的方式带出去（比如写进它被允许写的文件）

7. 外发审计

web_fetch / web_search / bcdp_navigate / de_channel_send 全部记审计（不阻断）。
web_fetch 禁止访问 localhost / 127.0.0.1 / 内网 IP。

- 能拦：AI 被诱导去读 http://127.0.0.1:8080/admin
- 拦不住：DNS 重绑定、通过公网域名访问内网服务

8. 恶意文件静态审计

命令里出现真实存在的可执行文件时，只读字节、不运行，按特征打分，超过阈值拦下并可移入隔离区（改 .bin + 禁止执行 ACL）。

识别的特征：凭据类 API、键盘记录、屏幕捕获、进程注入、网络外发、反分析、敏感数据路径、加壳（UPX / Themida / VMProtect）、恶意行为字符串。

组合提权示例：

| 组合 | 加分 | 含义 |
| 网络能力 + 敏感数据访问 | +40 | 可能窃取并外发 |
| 凭据 API + 网络能力 | +40 | 可能读取并回传凭据 |
| 键盘记录 + 网络能力 | +35 | 可能记录按键并回传 |
| 进程注入 + 无签名 | +25 | 典型注入型恶意软件 |

- 能拦：特征明显的已知家族样本
- 拦不住：加壳 / 加密载荷（特征全无）、新写的、改过特征码的、白利用的
- 会误报：远程桌面、屏幕录制、系统工具、游戏加速器都会命中键盘/屏幕/网络 API

这一项最容易让人产生错误的安全感。请记住：静态扫描看不出运行时行为。

它绝对做不到的事（再说一遍）

1. 不做实时防护。文件落地后不会持续监控。
2. 不查病毒库。没有特征库、没有云查杀、没有行为沙箱。
3. 不拦截运行中的进程。一个已经开始跑的程序，它管不了。
4. 不防网络攻击。端口扫描、漏洞利用、中间人，都不在它范围。
5. 不区分「谁」在操作。谁坐在电脑前、谁在 DSH 里打字，它认不出来。
6. 不保证绕过不了。这是文本扫描 + 路径判断，写代码的人都知道怎么绕。

如果你需要真正的防护：
- 系统自带 Defender / 第三方杀软 —— 请始终开着
- 独立 Windows 用户 / 容器 / 虚拟机 —— 真正的隔离
- 定期备份 —— 唯一能救回数据的办法
- 不要给 AI 不必要的权限 —— 比任何插件都有效

配置

路径：%USERPROFILE%\.dsh\alpha-guard\config.json （首次加载自动生成；改完下一次工具调用即生效，不用重启）

完整字段见 config.example.json。常用项：

| 字段 | 说明 |
| read.allowRoots | 读取白名单根目录 |
| read.denyPaths | 永远拒绝读取（优先级高于白名单） |
| read.denyNamePatterns | 按文件名拒绝（*.kdbx、id_rsa） |
| write.denyPaths | 禁止写入 / 删除 |
| commands.mode | deny（默认）/ warn（只记录不拦，排障用） |
| subagent.allowWeb | false = 子代理完全断网 |
| malware.blockAt | 拦下的风险分阈值，默认 30。调低更严格但误报更多 |
| malware.notifyOnly | true = 只告警不拦 |
| enabled | false 临时停用 |
| failClosed | 插件内部异常时是否拒绝（默认 false，异常时放行并记日志） |

config.json 被列为「禁止工具写入」，防止被提示注入自我解除防护。
要改请手动编辑。

配套脚本（主人手动用，模型不能碰）

scripts/ 下有三个工具，都需要主人双击运行，模型无法调用：

pause-guard-2min.cmd — 临时关掉防护 2 分钟

有些操作被防护误拦（比如你自己想装个软件），可以临时关一下。

- 双击运行，弹出倒计时窗口
- 2 分钟后自动恢复，窗口可以关掉（恢复进程是独立隐藏的）
- 关闭期间：读取白名单、敏感路径拦截、危险命令拦截、安装审批、恶意文件审计 全部失效
- 恢复后会写一行日志到 %USERPROFILE%\.dsh\alpha-guard\pause.log

设计上的小心思：
- 改配置前先备份成 config.json.bak-before-pause-<时间戳>
- 只改顶层那一个 "enabled": true，并校验文件长度正好 +1 字节，不对就回滚
- 配置里有多个 enabled（顶层 + 各子模块），脚本用 IndexOf 取第一个并校验位置 < 400 字符， 绝不误伤子模块
- 如果上次异常退出留下了关闭状态，下次运行会先恢复

提醒：这是给「确实需要」的场合用的，不要养成长期关着的习惯。
关着的时候它什么都不是。

approve-one-install.cmd — 放行一次安装

防护默认拦安装。你真要装东西时：

1. 双击这个脚本
2. 它写一个带时间戳的许可文件到 %USERPROFILE%\.dsh\alpha-guard\install-approval.json
3. 2 分钟内有效、一次使用，用完自动失效
4. 然后让 AI 执行安装

这个许可文件本身不授予任何权限——它只是个时间戳，只有本机的 alpha-guard 认它，而且只认一次。没有网络请求、不含凭据、不上传任何东西。

放行窗口是硬编码的 2 分钟（120 秒），不可延长：

| 环节 | 实际行为 |
| 有效期 | 写入时间戳后 120 秒内有效 |
| 使用次数 | 1 次。用掉后文件立刻被改写成 {"used": true}，第二次调用直接失效 |
| 时钟回拨 | 时间戳在未来（age < 0）直接判无效 |
| 子代理 | 子代理不能用这个放行，只有主会话可以 |
| 过期后 | 文件留着也不管用，必须重新双击脚本 |

想改时长可以改 config.json 的 installApproval.windowSeconds，但默认值 120 秒就是设计意图——够装一个东西，不够做别的。

为什么必须手动：如果模型能自己写这个文件，那安装审批就形同虚设。
所以只有坐在键盘前的人能开这个口子。

guard-pause.ps1 / guard-resume.ps1 / approve-install.ps1

上面两个 cmd 的实际实现。一般不用直接调用，想改时长/行为时看这里。

审计日志

%USERPROFILE%\.dsh\alpha-guard\audit.jsonl

每行一条 JSON：时间、会话 ID、main/subagent、工具名、deny/warn、原因、参数摘要。
超过 5 MB 自动轮转为 audit.jsonl.1（保留一份）。

这是它最有价值的输出——你不需要它挡住一切，但你可以通过日志知道 AI 尝试过什么。

审计账本（防篡改校验）

日志本身也可能被改。bin/audit-ledger.mjs 给每一行登记「行号 + sha256」，用来证明日志没被动过。

node bin/audit-ledger.mjs --init # 首次建账本（拒绝覆盖已存在的）
node bin/audit-ledger.mjs --sync # 把新增行补进账本（老记录不覆盖）
node bin/audit-ledger.mjs --verify # 校验，不一致则退出码 1
node bin/audit-ledger.mjs --stats # 统计

为什么是「行号 + 哈希」两个维度：

| 只有哈希 | 只有行号 | 两者结合 |
| 能抓「改了一条」 | 能抓「删了一条」 | 两种都能抓 |
| 抓不到删除（剩下的都对） | 抓不到改写（行数对得上） | — |

纪律：先 sync 再 verify。 反过来的话，每一行新增都会被误报成「被篡改」，因为账本里还没有它。

这个账本能做什么、不能做什么：

- ✅ 能证明：某一行被改过、某一行被删了、行数对不上
- ❌ 不能证明：整个账本文件被一起替换（账本自己没被保护）
- ❌ 不能防：有写权限的人同时改日志和账本

所以它是「防误改和防粗心」，不是「防有心人」。真要防篡改，日志得写到你控制不了的地方（远程 syslog、WORM 存储）。

隔离区

%USERPROFILE%\.dsh\alpha-guard\quarantine\

- <id>.bin：原始字节，扩展名一律 .bin，双击不会运行
- <id>.json：元数据（原路径、SHA256、隔离时间、审计结论）
- 目录额外加了 ACL：当前用户完全控制但拒绝执行

永不自动删除，要取出或删除都得你说话。

命令行工具：

$cli = "$env:USERPROFILE\.dsh\plugins-src\dsh-alpha-guard\bin\quarantine-cli.mjs"

node $cli list # 列出隔离区
node $cli pending # 待决队列
node $cli audit 文件路径 # 只审计，不动文件
node $cli get id 目标路径 # 取出
node $cli del id # 永久删除
node $cli stats # 统计

如何停用

1. 临时 2 分钟：双击 scripts\pause-guard-2min.cmd
2. 临时不限时：把 config.json 的 "enabled": true 改成 false（立即生效）
3. 彻底：删掉 profile cordis.patch.yml 里 dsh-alpha-guard 那一行，重启 DSH

常见问题

Q：装了是不是就安全了？ A：不是。 它只是一道很浅的减速带。系统自带防护请始终开着。

Q：它会不会拖慢 DSH？ A：每次工具调用做一次路径/正则判断，开销很小。但恶意文件静态审计要读文件字节，大文件（默认上限 32 MB）会有可感知的延迟。

Q：误报了怎么办？ A：远程桌面、屏幕录制、系统工具、游戏加速器这类会命中键盘/屏幕/网络 API 的软件确实会误报。把 malware.blockAt 调高（如 60），或者 notifyOnly 设成 true 只告警。

Q：它会不会上传我的数据？ A：不会。不联网、不上传、不执行目标文件，所有判断都在本地。

Q：改了 config.json 要重启吗？ A：不用，下一次工具调用就生效。

Q：为什么模型不能自己改 config.json？ A：故意的。防止提示注入让 AI 给自己解除防护。

Q：failClosed 是什么？ A：插件自身出异常时是否拒绝所有调用。默认 false（异常时放行并记日志），避免插件 bug 把整个助手锁死。如果你更看重安全，可以设 true——但风险是插件一出问题 DSH 就完全不能用。

Q：能挡住提示注入吗？ A：挡不住。 它能拦「读了敏感路径」这个动作，但拦不住 AI 被话术说服去做别的事。
提示注入的防御要靠你在输入端把关。

开发者信息

- 纯 ESM（Node.js），无构建、无第三方依赖
- 要求 Node ≥ 20、DSH 0.2.x
- 入口：lib/index.js 注册 ctx.tools.guard；策略引擎在 lib/policy.js

| 文件 | 职责 |
| lib/index.js | 插件入口 |
| lib/policy.js | 策略引擎：白名单、拒绝列表、命令规则、文本扫描 |
| lib/malware-audit.js | 可执行文件静态审计与打分 |
| lib/quarantine.js | 隔离区与待决队列 |
| bin/quarantine-cli.mjs | 命令行工具 |
| scripts/ | 主人手动用的暂停 / 放行脚本 |
| test/selftest.mjs | 92 项策略自测 |

最后的免责声明

使用本软件即表示你理解并接受：

1. 本软件按「现状」提供，不附带任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和不侵权的担保。
2. 作者不对任何损失负责，包括但不限于数据丢失、系统损坏、业务中断、安全事件造成的损失——无论是否与本软件有关。
3. 本软件不是安全产品，不能替代杀毒软件、防火墙、沙箱或任何专业安全方案。
请勿将其作为唯一的安全措施。
4. 本软件的策略基于静态规则，存在已知和未知的绕过方式。
作者不保证能拦截任何特定类型的攻击。
5. 本软件可能误拦正常操作，也可能漏拦恶意操作。
两种情况的后果都由使用者自行承担。
6. 使用者应自行评估本软件是否适合其使用场景。涉及敏感数据、受监管数据、生产环境的场景，请勿依赖本软件。
7. 本软件会记录操作审计日志到本地磁盘，日志内容可能包含路径、命令片段等信息。
请自行评估日志的存放位置与访问权限。
8. 本软件对故意构造的绕过（动态拼接路径、编码载荷、加壳样本等）基本无效。
如果你面对的是有动机的攻击者，而不是 AI 的误操作，本软件帮不上忙。

如果你不能接受以上任何一条，请不要使用本软件。

许可

MIT