cdxiaodong/dsh-guardian

dsh-guardian

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

🎯 解决什么问题

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

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

🛡️ 五大检测引擎

外加：

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

🚦 三级处置

📦 安装

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))

🔧 对应论文机制

🧪 测试

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