bigclawd/dsh-security-guard

English | 中文

DeepSeek Harness（dsh）的安全守卫插件。 静态扫描 + 运行时拦截，绝不执行它帮你防护的代码。

---

✨ 特性一览

🔍 静态扫描	基于规则的源码分析——只使用 ts.createSourceFile，被扫描的代码从不被 import 或执行
👁️ 运行时监控	在危险工具调用、提示词步骤和文件操作发生之前将其拦截
📊 判定分级	每个发现项归类为 block | warn | clean，写入 JSON 或人类可读报告
🧩 可扩展规则	纯可审计 JSON 规则，按 id 可覆盖，无黑盒签名机制
🪝 安装钩子	自动扫描每个新安装的插件（监听 profile 清单变化）
🖥️ 交互界面	/scan 命令、plugin_scan 工具、实时 Web 面板、用户可管理的白名单

🎯 威胁模型

类别	示例	默认严重级别
🧨 恶意代码	eval / new Function、child_process、require("node:...")、postinstall 钩子、process.env 数据外泄、隐藏 base64/hex 载荷、对全局对象的计算成员访问	block
💉 上下文注入	“忽略之前的指令”等提示词覆盖短语、未经验证的 URL 主机	block / warn
⏳ 令牌浪费	超大文件、base64 占主体的内容、重复单词/字符、填充性注释	warn
🔐 敏感路径	代码触及 ~/.ssh、.env、凭据存储	warn

🔍 检测器家族

• AST 传递（src/static/ast.ts）— 用 TypeScript 编译器 API（ts.createSourceFile） 解析 TS/JS，遍历语法树并匹配规则模式（ast-call、ast-member、ast-computed、ast-import）。 文本从不被执行。
• 内容传递（src/static/content.ts）— 对文本、代码字符串、图片 alt 属性和 markdown 运行 regex / phrase / url / file 规则。
• 令牌传递 — 体积、base64 占比、重复和注释填充启发式 （src/static/content.ts 启发式，src/rules/token.json 调参）。
• 运行时监控（src/runtime/watcher.ts）— 步骤前 / 工具前 / 工具后三道闸门、 管道与破坏性 shell 模式、SSH 写入与令牌消耗遥测、session 用量监控。
• 白名单（src/whitelist.ts）— 持久化到磁盘的用户白名单；可通过 CLI 或面板信任/取消信任。

📦 规则

规则是打包在 src/rules/ 下的纯 JSON——code.json、injection.json、 token.json、allowlist.json。rulesDir 选项可以按 id 覆盖或扩展它们。 完整的 schema 见 src/rules.ts。

{ "id": "code.eval", "kind": "ast-call", "severity": "block", "callee": ["eval"] }

matcher 种类：ast-call（调用/new）、ast-member（点访问）、 ast-computed（对全局对象的计算成员访问——混淆信号）、 ast-import（导入/require）、regex（作用于 all/string/comment）、 phrase、url、file。除经典恶意模式外，内置规则还针对混淆做了加固： hex/base64 的 Buffer.from/toString 编码、长 hex 纯字符串载荷、 对 globalThis/global/process 的计算成员访问都会被标记。 完整 schema 见 src/rules.ts。

🚀 用法

安装

dsh plugin --profile default add dsh-security-guard

宿主应用

import { Context } from '@deepseek-ai/cordis'
import Guard from 'dsh-security-guard'

ctx.plugin(Guard, {
  rulesDir: 'config/guard-rules',          // 可选覆盖
  scan: { maxFiles: 5000, maxFileSize: 4 * 1024 * 1024, skipSegments: ['node_modules', '.git', 'dist', 'lib'] },
  runtime: { enabled: true, blockOnSeverity: ['block'], maxFindingsPerScan: 200 },
  allowlist: { file: 'data/guard-allowlist.json' },
  web: { enabled: true, path: '/scan' },
  installHook: { enabled: true, intervalMs: 5000 },  // 自动扫描新安装的插件
})

安装钩子

宿主没有"插件已安装"事件（dsh plugin add 是独立 CLI 进程），所以守卫监听 profile 清单（$DSH_HOME/profiles/<name>/package.json——CLI 在安装成功后 唯一会改写的文件）。每次新增的依赖包都会在 node_modules 下被静态扫描； 报告记为运行时事件（source: install）、以 guard/install-scan 事件发出， 并追加到 profile 目录的 guard-install-scans.jsonl。用 installHook: { enabled: false } 关闭。

静态扫描

/scan ./plugin-dir                 # 人类可读报告
/scan ./plugin-dir --json          # 机器可读
/scan ./plugin-dir --json --out report.json

也可以使用 plugin_scan 工具，参数为 target、severity、json、out。

👁️ 运行时监控

默认开启。守卫监听以下事件：

事件	动作
agent/pre-step	拒绝匹配 injection.* 或令牌消耗模式的步骤
tools/*	拒绝 exec/spawn 运行破坏性命令；对写入 ~/.ssh 或令牌缓存的 shell 管道请求确认；阻止在 workspaceRoots 之外执行 write/edit
fs/*	观察敏感路径（~/.ssh、.env、……）的读取/编辑
session/event	跟踪 assistant/message 的令牌用量，对可疑消耗发出警告

🖥️ Web 面板

由 harness 的 Web 服务器在配置的路径（默认 /scan）提供： 实时发现项、规则概览、白名单管理（信任/取消信任）、报告下载。

🧪 开发

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest run（89 个测试：static、rules、runtime、whitelist、plugin）
pnpm build       # tsc 输出 + 将打包规则复制到 lib/

测试套件在 tests/fixtures/ 下运行三组样例——clean/、injected/、malicious/， 外加 samples/malicious-demo——一个故意恶意的示例插件，扫描器绝不会执行它 （用 /scan samples/malicious-demo 扫描即可看到它被报告）。

🔒 设计约束

• 扫描器是纯静态的：只使用 ts.createSourceFile / ts.createScanner； 被扫描的源码从不被 import、求值或执行。
• 不使用未经审查的 AI 签名或哈希机制；判定来自可审计、可按 id 覆盖的 JSON 规则。
• 运行时闸门决策使用宿主原生的 PreToolDecision / PostToolDecision / PreStepDecision 契约。

⚠️ 已知边界

• 混淆是一场军备竞赛。 规则模式能可靠拦截脚本小子级恶意代码、复制粘贴的 样本，以及最重要的——package.json 里的安装时生命周期脚本（无法隐藏： npm 要求字面量键名）。但铁了心的攻击者仍可通过运行时解码或加密隐藏载荷。 扫描器是风险降低层，不是安全证明。
• 存在误报。 合法代码也可能触发启发式规则（例如 hex 哈希常量）； 判定默认 warn，白名单和 ruleSeverity 覆盖可以兜底。
• 先扫后装。 恶意 postinstall 在包安装的那一刻就会执行——先扫描 （/scan），再 dsh plugin add。

📄 License / 许可证

MIT