chendengyuanxm / dsh-plugin-security-audit

dsh-plugin-security-audit

Static security audit for dynamic Cordis plugins in DeepSeek Harness (DSH).

English · 中文

---

What it does

Dynamic Cordis plugins defined in a DSH session run plain JavaScript with access to real Host services — files, shell, sessions, credentials. The sandbox restricts accidental misuse; it is not a security boundary against malicious code. This plugin adds a deterministic, zero-token static audit layer over every cordis_define / cordis_run call in the session:

• Scan on define — every cordis_define's code.host / code.client source is scanned by a 16-rule engine before the package is minted.
• Gate on activate — a cordis_run for a package with critical or high findings is escalated to a user approval ({kind:'ask'}) whose reason carries the top findings. Clean and low-risk packages run normally.
• Report in the conversation — a compact risk report is appended beside every cordis_define / cordis_run result as an additionalContexts notice, so both the model and the user see it in the tool-result stream.
• Fail-open by design — any internal scan error is logged and the audited call proceeds untouched. The audit layer itself is never a failure point for the harness.

Install

Requires DSH with the dsh plugin command (v0.1.0-rc.6+).

# from npm (once published)
dsh plugin --profile web add dsh-plugin-security-audit

# from GitHub
dsh plugin --profile web add github:<owner>/dsh-plugin-security-audit

Restart the profile (dsh web) afterwards; bundle layers take effect on boot. Verify the row composed:

dsh --profile web --dump-config | grep plugin-security-audit

To use it in an agent preset instead, copy examples/preset/ into ~/.dsh/.agent-presets/plugin-security-audit/ and select the preset when starting a session.

How it works

cordis_define ─▶ tools/pre-execute ─▶ scan engine (16 rules, pure function)
                                        │ findings
                                        ▼
                                   report cache (LRU 100)
                                        │
cordis_run  ─▶ tools/pre-execute ─▶ high/critical? ─▶ {kind:'ask'} + reasons
                                        │ else
                                        ▼
tools/post-execute ─▶ additionalContexts notice (model + user visible)

• Listeners are registered on the composition scope, covering every agent in the profile/preset (DSH tool-pipeline events flow up the scope chain).
• Reports are plain owned JSON; no live Cordis objects are serialized.
• Report delivery uses the additionalContexts channel on tools/post-execute — independent of each tool's output.render, so the notice cannot be clobbered by the tool's own content finalization.

Rules

Group	Rule (id)	Severity
Dangerous capabilities	global-proc — Node process global	critical
	global-buf — Buffer global	high
	dynamic-eval — eval / new Function	critical
	module-load — require() / import of external modules	high
	ctx-bracket — ctx[...] dynamic property escape	high
	native-timer — setTimeout & friends (not ctx.timeout)	medium
	client-dom — direct document/window/fetch on Client	high
Data exfiltration	exfil-combo — sensitive source + network sink combo	critical
	hardcoded-cred — hardcoded secrets	high
	base64-net — base64 codec + network sink combo	high
Cordis anti-patterns	live-serialize — JSON.stringify/structuredClone on live objects	high/medium
	undeclared-svc — ctx.x access without inject	medium
	sensitive-svc — shell / subprocess / fs / web / credentials / sessionQuery use	high
	effect-no-dispose — ctx.effect callback without a disposer	medium
Over-reach surfaces	rpc-live-obj — package RPC returning live objects	medium
	shadow-slot — registering high-risk replacement Slots	medium

Activation gating threshold: critical or high ⇒ user approval required.

Limitations

• Static pattern matching with light scope approximation — it cannot catch intent-level or multi-step obfuscated attacks. A CLEAN verdict means "no rule matched", never "provably safe".
• critical+high findings escalate the approval; the audit never hard -blocks a call by itself.
• Reports are in-process only (no persistence, no history UI).

Development

npm test        # offline regression: bad vector must hit, clean must pass,
                # activation gate must return {kind:'ask'}

examples/dynamic/ ships the in-session dynamic-plugin form (identical Host logic plus a Client audit panel registered in the tool.view.cordis slot of its own Run card — that panel relies on dynamic-plugin-only Builtins (host.call, styles) and therefore is not part of the static bundle).

License

MIT

---

dsh-plugin-security-audit（插件安全审查）

对 DeepSeek Harness（DSH）中动态 Cordis 插件的静态安全审查。

功能

会话内定义的动态 Cordis 插件以纯 JavaScript 运行，并可访问真实 Host 服务——文件、Shell、会话、凭据。沙箱只防误用，不是对抗恶意代码的安全边界。本插件在每个 cordis_define / cordis_run 调用上加一层确定性、零 token 的静态审查：

• 定义即扫描——每次 cordis_define 的 code.host / code.client 源码都会先经过 16 条规则的引擎扫描。
• 激活前把关——对存在 critical / high 发现的插件包，cordis_run 会升级为用户审批（{kind:'ask'}），审批理由携带最高危发现；干净与低风险包正常放行。
• 报告进对话流——每次 cordis_define / cordis_run 结果旁附带一条紧凑的风险报告（additionalContexts 通知），模型与用户都能在工具结果流里看到。
• 设计上永不阻塞——审查层内部任何异常只记录日志，被审调用照常进行；审查器自身永远不会成为 harness 的故障点。

安装

需要带 dsh plugin 命令的 DSH（v0.1.0-rc.6+）。

# npm（发布后）
dsh plugin --profile web add dsh-plugin-security-audit

# GitHub
dsh plugin --profile web add github:<owner>/dsh-plugin-security-audit

之后重启 profile（dsh web），bundle 层在启动时生效。验证组合结果：

dsh --profile web --dump-config | grep plugin-security-audit

若想以 agent preset 方式使用，把 examples/preset/ 复制到 ~/.dsh/.agent-presets/plugin-security-audit/，建会话时选择该预设即可。

工作原理

cordis_define ─▶ tools/pre-execute ─▶ 扫描引擎（16 条规则，纯函数）
                                        │ findings
                                        ▼
                                   报告缓存（LRU 100）
                                        │
cordis_run  ─▶ tools/pre-execute ─▶ 有 critical/high？─▶ {kind:'ask'} + 理由
                                        │ 否则放行
                                        ▼
tools/post-execute ─▶ additionalContexts 通知（模型 + 用户可见）

• 监听器注册在组合层作用域上，按 DSH 工具管线事件的作用域链覆盖该 profile / preset 下的每个 agent。
• 报告是自有的纯 JSON，不序列化任何 Cordis 活对象。
• 报告走 tools/post-execute 的 additionalContexts 通道——独立于各工具自身的 output.render，不会被工具的内容终改覆盖。

规则

分组	规则（id）	级别
危险能力	global-proc——Node process 全局	critical
	global-buf——Buffer 全局	high
	dynamic-eval——eval / new Function	critical
	module-load——require() / import 外部模块	high
	ctx-bracket——ctx[...] 动态属性逃逸	high
	native-timer——setTimeout 等（未用 ctx.timeout）	medium
	client-dom——Client 端直接用 document/window/fetch	high
数据外泄	exfil-combo——敏感数据源 + 网络出口组合	critical
	hardcoded-cred——硬编码密钥	high
	base64-net——base64 编解码 + 网络出口组合	high
Cordis 反模式	live-serialize——对活对象 JSON.stringify/structuredClone	high/medium
	undeclared-svc——未声明 inject 就访问 ctx.x	medium
	sensitive-svc——使用 shell / subprocess / fs / web / credentials / sessionQuery	high
	effect-no-dispose——ctx.effect 回调不返回清理函数	medium
越权面	rpc-live-obj——包私有 RPC 返回活对象	medium
	shadow-slot——注册高风险覆盖型 Slot	medium

激活把关阈值：critical 或 high ⇒ 需用户审批。

局限

• 静态模式匹配 + 轻量作用域近似，无法识别意图级或多步混淆攻击；CLEAN 结论只表示"未命中规则"，绝不等于"证明安全"。
• critical+high 只升级为审批；审查器自身从不硬阻断调用。
• 报告仅存于进程内（无持久化、无历史界面）。

开发

npm test        # 离线回归：违规向量必须命中、干净向量必须通过、
                # 激活把关必须返回 {kind:'ask'}

examples/dynamic/ 提供会话内动态插件形态（Host 逻辑一致，另带一个挂在 自身 Run 卡 tool.view.cordis Slot 的 Client 审查面板——面板依赖动态插件 专属 Builtin（host.call、styles），因此不属于静态 bundle）。

许可

MIT