rootkiller6788/dsh-plugin-scanner

dsh-plugin-scanner

一个面向 DeepSeek Harness（dsh）插件的安全扫描器，构建于 dsh 插件内核之上。它检测有风险的第三方插件包——配置行覆盖、!!js 表达式、能力提升、提示注入以及自我修改——并通过面向模型的工具和面向人类的命令报告发现结果。

要点：插件化的核心

参考架构是 skill-scanner，但 skill-scanner 有一个特权工厂（analyzer_factory.py 硬编码了分析器集合），而本项目将分析器注册变为一种 effect：

- ctx.pluginScan.registerAnalyzer(analyzer) 返回一个 disposer，与 Cordis 注册完全一致。
- 四个内置分析器（dsh-plugin-scan-rules）通过同一个公共方法注册。
- 外部引擎桥接（dsh-plugin-scan-bridge）通过子进程添加了一整个检测器——同样通过 registerAnalyzer，且对核心没有任何改动。

没有需要打补丁的特权核心。接缝是标准的 dsh 三角色拆分：

| 包 | 角色 | ctx 键 |
|---|---|---|
| dsh-plugin-scan | 服务定义：分析器注册表、包加载器、策略 | ctx.pluginScan |
| dsh-plugin-scan-rules | 服务提供者：四个内置分析器 + YAML 规则包 | 注册到 ctx.pluginScan |
| dsh-plugin-scan-bridge | 服务提供者：作为持久子进程的外部引擎 | 注册到 ctx.pluginScan |
| dsh-tool-plugin-scan | 消费者：scan_plugin 工具 + /scan 命令 + bundle 补丁 | 注册到 ctx.tools、ctx.commands |

内置分析器

| 分析器 | 检测内容 |
|---|---|
| config-analyzer | patch 覆盖/禁用与安全相关的行（sandbox、approval、credentials、llm……）；!!js 表达式以及 !!js 触及 fs/shell/credentials |
| capability-analyzer | eval/new Function/node:vm；直接导入 node:fs/child_process/net；process.env + 网络（凭据外泄）；遮蔽内置工具名；preinstall/postinstall/prepare 脚本 |
| model-analyzer | 模型可见文本中的提示注入指令（忽略-覆盖、越狱） |
| runtime-analyzer | 动态 Cordis 包（cordis_define/cordis_run/ctx.dynamic）；写入 cordis.yml/profile 状态 |
| coverage-analyzer | 扫描自身的缺口：加载器拒绝读取的文件（过大/不可读/超出字节预算）以及因文件上限而停止的遍历 |

最后一个并不检测包的任何内容；它报告的是扫描本身。一个 payload 位于加载器从未读取的文件中的包，看起来与干净的包一模一样，因此“无发现”只有在“所有内容都已读取”的旁边才有意义。
规则位于 packages/scan-rules/rules/core.yaml：清单（严重性 / 类别 / 描述）加上每条规则的大小写不敏感 matches 列表。结构性检查（行覆盖、AND 组合、生命周期脚本）保留在分析器代码中。分析器发出的每个 ruleId 都必须有清单条目——finding() 在缺失时会大声失败。

外部引擎桥接

dsh-plugin-scan-bridge 通过 JSON-lines 协议将任意检测器作为持久子进程运行，在握手时按版本固定，并按请求进行限制（超时 + 最大行大小）——与 skill-scanner 的 cel-go 辅助程序相同的版本化、有界子进程姿态。引擎在握手时声明自己的规则；它们会出现在 ctx.pluginScan.ruleRegistry 中。

enable a bridge engine in a patch
- insert:
- id: my-scan-engine
name: 'dsh-plugin-scan-bridge'
config:
command: node
args: ['./engines/my-engine.mjs']
engineName: my-engine
engineVersion: 1.0.0

协议（基于 stdio 的 JSON lines）：init {version} → ready {version, rules}；scan {id, root} → findings {id, findings} | error {id, error}。版本不匹配会导致插件加载失败。

扫描目标

- { kind: 'directory', path } — 扫描一个插件包目录。
- { kind: 'profile', name } — 扫描已安装配置文件自身的文件（$DSH_HOME/profiles/；DSH_HOME 默认为 ~/.dsh）。
- { kind: 'github', repo } — 将 owner/name（或完整 URL / 本地路径）浅克隆（git clone --depth 1）到临时目录，扫描它，然后删除克隆。
- scanRegistry(path) — 批量：读取注册表 JSON 文件并扫描每个条目。

注册表批量

scanRegistry(path)（以及 /scan-registry  命令）读取包含条目的 JSON 文件并逐个扫描，返回 ScanBatchReport：

[
{ "name": "my-plugin", "path": "/abs/path/to/my-plugin" },
{ "name": "someone/some-plugin", "repo": "someone/some-plugin" }
]

每个条目携带 path（本地目录）或 repo（github 简写 / URL）。

策略与门控

- ctx.pluginScan 配置：disabledRules（丢弃规则 id）和 severityOverrides（按规则覆盖严重性）。
- scan-rules 配置：trustedRowIds、builtinToolNames。
- tool-scan 配置：failOn — 一个严重性阈值；当 maxSeverity 达到该阈值时，scan_plugin 结果会携带 failed: true（留空则禁用）。
- tool-scan 最多渲染 25 条发现，并且每批最多渲染 25 个被标记的包；其余按数量汇总。渲染出的块是面向模型的工具内容，因此这限制了某个包携带数百条发现时能推入上下文的内容。

范围与限制
这是一个尽力而为的静态扫描器，并非安全保证。“无发现”意味着没有匹配到已知模式——它并不证明插件是安全的。每次扫描都会报告它未读取的内容（SCAN_FILE_SKIPPED）以及遍历是否因达到上限而停止（SCAN_TRUNCATED）；当其中任一项存在时，“未检测到已知威胁模式”这一行只是一个部分答案。规则是启发式的（子字符串 + 结构，而非完整的 AST/数据流）；坚定的攻击者可以绕过特征签名，而扫描器即使在注释中也会匹配像 eval 这样的字面 token。在安装你不信任的插件之前，请将结果与人工审查结合使用。

仓库布局

packages/
scan/         dsh-plugin-scan         (Service Definition)
scan-rules/   dsh-plugin-scan-rules   (Provider: 4 analyzers + YAML rules)
scan-bridge/  dsh-plugin-scan-bridge  (Provider: external engine)
tool-scan/    dsh-tool-plugin-scan    (Consumer: tool + command + bundle)
testdata/       malicious + clean fixtures, and a bridge engine fixture

开发

本仓库从同级 deepseek-harness-master 检出目录中解析 dsh 框架包作为工作区成员（参见 pnpm-workspace.yaml），因此 @deepseek-ai/cordis 保持单一的 Context 标识，并且构建出的 lib/ 用于类型。

pnpm install
pnpm run typecheck
pnpm test

安装到 dsh profile

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add link:../dsh-plugin-scanner/packages/tool-scan
or, once published: dsh plugin --profile web add dsh-tool-plugin-scan

然后让模型对某个目录执行 scan_plugin，或输入 /scan 。

设计说明

- v1 仅报告。 该工具返回结构化报告；它绝不会因某个发现而阻塞模型。Guard/deny 行为和上下文注入是后续里程碑。
- v1 不添加会话事件。 仓库外插件尚无法将新的 SessionEventMap 成员标记为 ignorable，因此新增事件类型会导致第一方读取器拒绝恢复。报告输出搭载现有的 tool/result 接口。
- 退出码 / CLI 是后续里程碑；v1 暴露 failed 标志和 maxSeverity，供调用方据此进行门控。