cdxiaodong/dsh-guardian

dsh-guardian

Agent 安全护栏 · 基于 Cordis 时空可组合元内核的 DeepSeek Harness 插件。
在 Agent 每次工具调用前做安全审查，命中危险即拦截或要求人工确认。

CI

🎯 解决什么问题

LLM Agent（Claude Code / DeepSeek Harness）能自主执行 shell、读写文件、发网络请求。一旦被提示注入、工具投毒或模型误判带偏，可能在你不知情时 rm -rf、读取 .ssh/id_rsa、把密钥外泄到远程。本插件是一道运行时安全网：

Agent 想执行工具 → guardian/check 前置审查 → 命中规则 → 拦截 / 人工批准 → 才放行

🛡️ 五大检测引擎

| 引擎 | 检测内容 | 借鉴来源 |
|---|---|---|
| CMD/INJ 危险命令 | rm -rf、dd、mkfs、fork炸弹、反弹shell、管道执行、提权 | Sigma 规则、PayloadsAllTheThings |
| CRED 凭据保护 | 读 .ssh/.aws/.env/kubeconfig、/etc/shadow | mcp-safeguard CRED 系列 |
| SECRET 密钥泄露 | AWS/GitHub/OpenAI/Anthropic/Slack/Stripe 等 25+ 种密钥正则 + Shannon 熵过滤降误报 | gitleaks、trufflehog |
| SSRF 网络目标 | 云 metadata（169.254.169.254）、内网网段、file://、gopher:// | mcp-safeguard SS 系列 |
| PI/TP 提示注入+工具投毒 | ignore previous instructions、DAN越狱、零宽字符、HTML注释藏指令、瞒用户指令 | Rebuff、LLM Guard、Vigil |

外加：

- 路径沙箱（guardian/path）：realpath 解析 + 白名单根目录 + 编码变体解码 + 空字节截断检测——比纯正则可靠
- 风险评分引擎（risk.ts）：多信号并集概率式加权成 0~1 分，按阈值分级处置（deny/block/warn/allow）

🚦 三级处置

| 级别 | 行为 | 例子 |
|---|---|---|
| deny | 直接拒绝 | 反弹shell、mkfs、读 /etc/shadow、明文密钥 |
| block | 需人工确认（走 guardian/approve） | rm -rf ~、读 .ssh、curl 上传文件 |
| log | 仅记录审计 | 路径穿越、读取 shell history |

📦 安装

dsh plugin --profile web add github:cdxiaodong/dsh-guardian

🚀 用法

import { Context } from 'cordis'
import * as guardian from 'dsh-guardian'

const ctx = new Context()
ctx.plugin(guardian, {
allowedRoots: ['/home/user/workspace'],   // 可选：文件访问沙箱白名单
scanSecrets: true, scanSSRF: true,        // 开关各引擎
})

// ① 接入人工批准（无此监听器时 block 级默认拒绝）
ctx.on('guardian/approve', async ({ tool, rule, snippet }) => {
const ok = await confirm(${rule.reason}：${snippet})  // 你的 UI 弹窗
return { approved: ok }
})

// ② 工具调用前审查（同步短路）
const r = ctx.bail('guardian/check', toolName, args)
if (r && r.intercepted) throw new Error(已拦截：${r.reason})

// ③ 文件访问前校验路径
const v = ctx.bail('guardian/path', filePath)
if (v && v.safe === false) throw new Error(路径被拦截：${v.reason})

// ④ 查审计日志
console.log(ctx.guardian.readAudit(20))

🔧 对应论文机制

| Cordis / 时空可组合概念 | 本插件体现 |
|---|---|
| 响应式协效应（provide/inject） | provide=['guardian'] 对外提供服务；依赖 cordis 事件系统 |
| 可逆效应（Revertible Effects） | ctx.effect(() => () => stream.end()) 注册撤销函数，卸载自动关文件流、零残留 |
| 拦截机制（Intercept） | ctx.bail('guardian/check') 全局短路拦截，不改被保护组件代码 |
| 隔离机制 | 多实例可绑定独立配置/白名单 |

🧪 测试

npm ci && npm test     # 19/19 通过

🙏 致谢 / 参考

本插件的规则与架构缝合自以下优秀开源方案：

- gitleaks — 密钥正则库 + 熵过滤
- trufflesecurity/trufflehog — 密钥检测器设计
- protectai/llm-guard — scanner pipeline 架构
- protectai/rebuff — 四层纵深检测思想
- deadbits/vigil-llm — 提示注入签名
- SyedAnas01/mcp-safeguard — TP/PI/SSRF/CRED 规则分类法
- SigmaHQ/sigma — 危险命令检测规则

⚠️ 安全认知：所有正则/启发式护栏都可能被绕过（对抗样本实测可绕过多种护栏）。本插件是 risk reducer，关键操作仍需人在环确认 + 最小权限沙箱，不能替代这两者。

📜 License

MIT