dsh-plugin-audit

English · npm · DeepSeek Harness

在让 DSH 插件跑起来之前，先看清它能做什么。 dsh-plugin-audit 对第三方插件做静态权限画像——代码触及哪些文件、进程、主机、环境变量和凭证路径，全部附文件/行号证据——并武装一个运行时哨兵：当任何工具调用伸向凭证或向未知主机外发数据时，先请你批准。

功能

1. 静态审计 —— plugin_audit 工具。 指向任意插件目录，扫描源码、package.json 和 cordis.patch.yml，返回权限画像卡：

## Plugin audit: fixture-suspicious-plugin

**Risk: REVIEW** — REVIEW — human review recommended before installing

> 1 files scanned; risk=review; 10 findings (4 review, 4 notice, 2 info)

### Permission profile

| Surface | Observed |
|---|---|
| Filesystem read | **yes** |
| Filesystem write | **yes** |
| Child processes | **yes** |
| Network | **yes** |
| Outbound hosts | `evil.example.com`, `exfil.badhost.io`, `telemetry.example.net` |
| Env variables | `GITHUB_TOKEN`, `HOME` |
| Credential-looking env | `GITHUB_TOKEN` |
| Credential paths | `.npmrc`, `.ssh` |
| Dynamic code execution | **yes** |
| Injected services | `credentials`, `tools` |
| Declared dependencies | — |
| Bundle patch | none |

### Findings

| severity | capability | location | detail |
|---|---|---|---|
| review | env-access | `src/index.js` | Reads a credential-looking environment variable. |
| review | credential-access | `src/index.js:12` | References a credential-bearing path. |
| … | … | … | … |

扫描按契约只读：每份报告携带 writesPerformed: false，另有可选的 invariant 伴随插件在运行时强制该标记。

2. 运行时哨兵。 挂在宿主工具管线 tools/pre-execute waterfall 上的监听器。待执行的工具调用命中风险规则时，哨兵返回 ask 并附原因，交给宿主原有的审批提示处理（无审批通道 → 调用被拒绝，绝不静默放行）：

审计是辅助而非裁决——它呈现实证，把判断留给你。

兼容性

| 依赖 | 版本 | | --- | --- | | DSH 主线 | 已验证 2026-08-14 快照（web + headless profile） | | Node.js | ^22.19.0 || >=24.0.0 | | Cordis | ^4.0.0-rc.7（peer） |

DSH 处于开发者预览期，破坏性变更频繁；上表日期记录本发布验证过的主线快照。./invariant 伴随插件已导出但有意不接入 cordis.patch.yml：官方 profile 不提供 invariants 服务，挂起的行会阻断启动。提供该服务的 profile 可自行添加 { id: dsh-plugin-audit-invariant, name: 'dsh-plugin-audit/invariant' }。

安装

# 从 npm
dsh plugin --profile web add dsh-plugin-audit

# 或直接从 GitHub
dsh plugin --profile web add github:jkrandom-sudo/dsh-plugin-audit

两条命令都会把包注册进 profile 的 dsh.profile.bundles 并应用本包的 cordis.patch.yml（一行：dsh-plugin-audit，sentinelEnabled: true）。重启 profile 后生效。

卸载

dsh plugin --profile web remove dsh-plugin-audit

移除依赖与 bundle 行，重启 profile 即可。本插件除 profile 自身的依赖元数据外不做任何写入，无需其他清理。

快速上手

在安装了本插件的 profile 会话中，直接说：

用 plugin_audit 审计 ~/some-third-party-plugin 这个插件

或让模型直接调用工具：

{ "path": "/absolute/path/to/plugin", "format": "markdown" }

• path（必填）—— 插件的源码目录（不是带 node_modules 的安装产物）。
• format —— markdown（默认）或 json。

工具返回上面的 Markdown 卡以及 JSON 摘要：{ markdown, risk, filesScanned, findingsCount, writesPerformed }。

哨兵无需调用——武装后自动监视会话中的每一次工具调用：

> ⚠ Tool "bash" runs curl toward "collector.unknown.io", which is not in allowedHosts. Outbound data movement needs your confirmation. （批准 / 拒绝）

配置

bundle patch 向 profile 插入一行；在 profile 的 cordis.patch.yml 中编辑：

- id: dsh-plugin-audit
  name: 'dsh-plugin-audit'
  config:
    sentinelEnabled: true        # 总开关；false = 只保留静态审计
    allowedHosts:                # shell 外发的预批准主机
      - github.com
      - api.github.com
      - raw.githubusercontent.com
      - registry.npmjs.org
      - '*.deepseek.com'         # 前导 *. = 后缀规则（同时匹配裸域名）

静态扫描器无需配置，也不参考 allowedHosts——它如实报告发现的每一个网络面。

权限与数据

• 扫描器只读 —— 只用读句柄，上限 400 个文件 / 单文件 256 KB，跳过 node_modules、.git、lib、dist。可选的 dsh-plugin-audit/invariant 伴随插件会在 plugin_audit 结果丢失 writesPerformed: false 标记时让会话失败。
• 无网络、无遥测 —— 本插件自身不发起任何网络请求。报告中出现的主机名是从被扫描源码提取的文本，从不被访问。
• 决策留在本地 —— ask 裁决由宿主既有审批提示中介；插件仅通过 ctx.logger 记录原因。
• 哨兵检查范围 —— 只检查经过 tools/pre-execute 的工具名与调用参数；不读取文件、环境变量，也不触碰参数之外的会话内容。

故障排查

• 启动报 dsh-plugin-audit/invariant: pending (waiting for service: invariants) —— 你把 invariant 行接入了不提供 invariants 服务的 profile；移除该行（随包 patch 默认不含它）。
• agent 看不到 plugin_audit —— 确认包在 profile package.json 的 dsh.profile.bundles 中，且 --dump-config 显示 dsh-plugin-audit 行，然后重启。
• 正常命令频繁触发询问 —— 把主机加入 allowedHosts，或设 sentinelEnabled: false 只保留静态审计。
• 扫描文件比预期少 —— 遍历上限 400 文件 / 256 KB 且跳过构建产物；请审计包的源码目录。

已知边界

• 不跟随 symlink 目标 —— 遍历只读目标树内的真实文件。
• 字符串与注释也会触发发现 —— 扫描器基于源码文本而非 AST；注释里的凭证路径与真实代码同等上报。这是有意为之：卡片是供人判断的证据，宁多勿漏。
• 只含构建产物的包至少为 NOTICE —— 当只发布 dist/lib 时没有源码可扫，卡片会如实说明，而不是给出干净结论。

开发

pnpm install
pnpm typecheck   # 两个 tsconfig
pnpm test        # vitest：scanner、哨兵规则、插件生命周期、invariant
pnpm build       # tsc -b && tsdown -> lib/

目录结构：src/scanner/ 是与 harness 无关的纯引擎（walk → detect → manifest → report），src/report.ts 渲染 Markdown 卡，src/runtime.ts 适配 Cordis/DSH 工具契约，src/sentinel/ 存放纯决策规则与 waterfall 监听器，src/invariant.ts 是只读强制伴随插件，src/events.ts 为宿主工具管线 waterfall 提供类型（监听器形状在编译期受检）。tests/fixtures/ 内含测试用样本插件（可疑 / 干净 / 含 patch override）。

本包同时发布 TypeScript 源码并提供 ./src/* export，遵循官方 dsh-external/plugin-template 约定：DSH 的开发工具可以直接从源码加载 link 安装的插件（例如插件开发时的 HMR），无需等待重新构建。

许可与安全

MIT —— 见 [LICENSE](./LICENSE)。

本插件是审计辅助工具，不是杀毒软件：干净的报告含义是「这些规则未发现证据」，而非「安全」。发现项是带文件/行号证据的启发式结论，供人判断。发现绕过方式——扫描器漏检的能力、可规避的哨兵规则？请在 <https://github.com/jkrandom-sudo/dsh-plugin-audit/issues> 开 issue，敏感内容请先私下报告。