dsh-plugin-security-audit

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

[English](#english) · [中文](#中文)

---

<a id="english"></a>

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/](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

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

---

<a id="中文"></a>

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/](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，不会被工具的内容终改覆盖。

规则

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

局限

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

开发

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

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

许可

MIT