dsh-plugin-security-audit

Readme

# dsh-plugin-security-audit

**Static security audit for dynamic Cordis plugins in [DeepSeek Harness](https://github.com/deepseek-ai/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+).

```bash
# 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:

```bash
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

| 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

```bash
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](https://github.com/deepseek-ai/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+）。

```bash
# 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 层在启动时生效。验证组合结果：

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

## 规则

| 分组 | 规则（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` 只升级为**审批**；审查器自身从不硬阻断调用。
- 报告仅存于进程内（无持久化、无历史界面）。

## 开发

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

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

## 许可

MIT