Dolphin（小海豚）—— 主动巡检型安全防御插件
本项目已收录于 dsh-plugin.org 官方插件市场（Listed on dsh-plugin.org）
将渗透测试方法论（信息收集 → 漏洞探测 → 利用验证 → 报告）转化为主动防御巡检流程，填补 DSH 生态中"主动防御巡检"的空白。
不再被动等告警，而是像海豚巡游一样，定期、主动地对目标主机做安全扫描与评估。
当前版本：v0.2.5（修正 peerDependencies 中 @deepseek-ai/dsh-tools 的版本范围声明——prerelease 仅在相同版本元组内匹配，旧范围在启用严格 peer 校验时会装配失败；新范围对齐并覆盖 DSH 0.1.5 系列）
⚠️ 免责声明
本项目为技术研究工具，严禁用于非法渗透测试。
- 本工具仅限用于你拥有合法所有权、或已获得明确书面授权的系统与代码。
- 使用本工具对任何第三方系统发起扫描、探测或连接，可能违反《网络安全法》《刑法》等相关法律法规。
- 作者不对任何因使用、误用或滥用本工具造成的直接或间接损失承担责任。
- 你必须获得明确授权方可使用。 使用者需自行承担全部法律责任与后果。
适用环境
| 项目 | 要求 |
|---|
| 操作系统 | 跨平台：Windows 10 / 11、Linux、macOS、WSL2（详见下方「跨平台支持」） |
| Node.js | >= 20（推荐 20 LTS 或 22 LTS） |
| 包管理器 | npm（随 Node.js 一并安装） |
| 静态分析引擎 | semgrep（见下方安装指引；远端缺失时插件可自动隔离部署） |
跨平台支持
Dolphin 可跨操作系统使用：Windows / Linux / WSL / macOS（Node.js >= 20 即可），不依赖任何 OS 专属特性——
- 零硬编码路径：所有数据路径由运行时 API（
os.homedir()、os.tmpdir()、模块自身位置）推导，Windows 与 POSIX 路径通吃。
- SSH 层纯 JS：基于 ssh2（纯 JS 实现，无平台专属二进制），控制端与目标端可以是任意操作系统组合——例如 Linux 控制端扫描 Windows 目标、Windows 控制端扫描 Linux 目标，双向均已实测。
- 远端命令 POSIX 化：下发给远端的全部命令经严格 POSIX 语法校验（
dash -n 逐条通过），并做单引号转义防注入。
- 实测矩阵：Windows 控制端 ↔ Linux/WSL 目标端、Linux（WSL）控制端 ↔ Windows 目标端的完整巡逻闭环（健康检查 → 扫描 → 报告存档）全部验证通过。
数据与路径（环境变量）
| 环境变量 | 用途 | 默认值 |
|---|
DOLPHIN_HOME | 主机库等数据目录根 | 未设置时依次回退 DSH_HOME、~/.dolphin |
DSH_HOME | DSH 生态统一数据根（Dolphin 兼容读取） | ~/.dsh |
DOLPHIN_REPORTS_DIR | 巡逻报告输出目录 | <插件目录>/reports/ |
DOLPHIN_SEMGREP_CACHE | 远端部署用 Linux wheel 便携包缓存 | ~/.dolphin/semgrep-wheel-cache |
主机库文件为 <数据根>/dolphin-ssh-hosts.json（原子写入、0600 权限语义）；巡检报告属于敏感数据，已被 .gitignore 排除，不入库。
安装
1. 安装 dsh-dolphin-security（npm registry 或 GitHub，二选一）
# 方式 A：npm registry 安装（推荐，获取已发布版本）
npm install dsh-dolphin-security
# 方式 B：从 GitHub 仓库安装（获取最新提交）
npm install git+https://github.com/CCR-WER/dsh-dolphin-security.git
⚠️ 安装方式约束：请务必通过上述 npm install（官方 registry 或 GitHub 仓库）方式安装本插件，不要手工拷贝目录——本包以 files 白名单发布，手工拷贝会缺失运行文件。
依赖官方 DSH 环境：dsh-dolphin-security 是 DSH（DeepSeek Harness，@deepseek-ai/dsh）生态插件，由官方 DSH 宿主加载后向 Agent 注册 dolphin_scan（本地 Semgrep 扫描）与 dolphin_patrol（远程 SSH 巡逻）两个工具。请在官方 DSH 环境中通过插件命令挂载：
dsh plugin --profile web add dsh-dolphin-security
若脱离 DSH 宿主使用，dolphin-patrol.js / dolphin-core.js / dolphin-ssh-core.js 仍可作为独立库/CLI 直接调用（见「核心功能」），无需 DSH 环境。
2. 安装项目依赖（仓库开发）
npm install
依赖 ssh2（MIT）用于远程 SSH/SFTP 能力。
3. 前提：安装 semgrep 并加入 PATH
Dolphin 的扫描能力基于 semgrep（LGPL-2.1）。必须先安装 semgrep 并确保其可在命令行中直接调用：
pip install semgrep
安装完成后验证：
semgrep --version
若能正常输出版本号（如 1.175.0），说明安装成功且已加入 PATH。
Windows 特别注意：若 semgrep --version 提示"不是内部或外部命令"，说明 Python 的 Scripts 目录未加入 PATH。请先执行 pip show semgrep 定位安装路径，然后将对应目录加入系统环境变量 PATH，重启终端后重试。
若本机未安装 Python，请先到 https://www.python.org/downloads/ 下载安装（安装时勾选 Add Python to PATH）。
核心功能
1. 本地扫描（--local）
对本机指定目录执行静态安全扫描，输出结构化漏洞清单并存档报告：
node dolphin-patrol.js --local <目录>
示例：
node dolphin-patrol.js --local D:/your-project/src
2. 远程巡逻（--patrol）
通过 SSH 将扫描命令下发至远程主机执行，回收结果并本地存档——这是"主动巡检"的完整闭环。
首次使用前需先登记主机（以 test-ssh-hosts.js 为参考模板）：
import { createHostStore } from './dolphin-ssh-core.js'
const store = createHostStore()
store.create({
alias: 'server01',
host: '192.168.1.10',
port: 22,
user: 'ops',
auth: { kind: 'password', password: '...' }, // 或 { kind: 'key', privateKeyPath: '...' }
tags: ['prod'],
environment: 'production',
})
然后执行巡逻：
node dolphin-patrol.js --patrol <alias> <远程目录>
示例：
node dolphin-patrol.js --patrol server01 /srv/app
远程巡逻会自动完成：连接健康检查 → 探测远端 semgrep → 下发扫描 → 回收 JSON → 结构化映射 → 本地存档。
远端未安装 semgrep 时，会自动上传扫描器到远端临时目录执行（fallback 路径）。
3. 系统日志与报告生成
所有扫描结果统一映射为 SecurityFinding 数据模型，自动存档为 JSON 报告：
D:\Dolphin\reports\
├── patrol-local-20260831-223652.json # 本地扫描报告
├── patrol-server01-20260901-200652.json # 远程巡逻报告
└── dolphin-report-*.md / *.json # dolphin-core 生成的报告
报告字段：host / file / line / col / severity / checkId / message / remediationHint / metadata。
4. 其他入口
node dolphin-patrol.js # 运行自检（25 项断言，无需网络与 semgrep）
node dolphin-core.js --mock [目录] # 用内置 mock 数据自测完整管线（无需 semgrep）
node dolphin-ssh-core.js # SSH 引擎自检（18 项断言）
node test-ssh-hosts.js # 测试主机库 + healthcheck 失败路径验证
node test-ssh-hosts.js --live # 起本地 ssh2 服务端，验证完整巡逻闭环
架构
Dolphin 采用「眼睛 + 手脚 + 大脑」三层架构：
| 层 | 文件 | 职责 |
|---|
| 扫描层（眼睛） | dolphin-core.js | 基于 Semgrep 的扫描封装，提供统一 SecurityFinding 数据模型 |
| 执行层（手脚） | dolphin-ssh-core.js | 基于 Apache-2.0 许可的 dsh-ssh 独立封装的 SSH 引擎，提供 exec / cluster / upload / download / test |
| 融合控制器（大脑） | dolphin-patrol.js | 将扫描命令经 SSH 下发至远程主机，回收 JSON 并结构化存档 |
🔐 远程扫描逻辑优化（安全部署）
远端工具部署已全面重构：本插件采用隔离技术（pipx / venv / 便携二进制包）自动部署远端 semgrep，绝不直接污染生产系统。
全链路禁止 sudo、禁止 pip install --break-system-packages、禁止任何写入系统 site-packages 的操作——
每条部署命令下发前都会经过硬校验（assertNoPrivilegeEscalation），命中红线直接终止巡逻。
优化历史：旧的「上传 node 脚本」回退路径已被移除，替换为下述真正可交付 semgrep 的三级隔离部署链。
当目标主机 PATH 中没有 semgrep 时，巡逻器按以下优先级自动部署（每一步都先输出预检结论：
策略、上传字节数、远端下载量估算与风险等级）：
| 优先级 | 策略 | 隔离方式 | 代价 |
|---|
| 1 | pipx | pipx install semgrep，装入用户级隔离区（~/.local/share/pipx），持久可复用 | 远端从 PyPI 拉取 ≈30MB |
| 2 | 临时 venv | /tmp/dolphin-venv-<ts> 内 pip install semgrep，完全隔离 | 同上；venv 构建约 30s |
| 3 | 便携包（最终回退） | 本地缓存 Linux wheel（约 40–60MB）经 SFTP 上传，远端 pip --no-index --target 离线安装进 /tmp 隔离目录；远端无 pip 时退化为 zipfile 解包 + PYTHONPATH 直跑 | SFTP 上传流量（预检中明确给出字节数） |
- 自动清理：临时 venv、便携包目录、上传的规则文件（
/tmp/dolphin-*）在扫描结束后自动 rm -rf 回收；
便携 wheel 的本地缓存保留复用（可用环境变量 DOLPHIN_SEMGREP_CACHE 指定位置，默认 ~/.dolphin/semgrep-wheel-cache）。
- 诚实降级：远端既无 pipx 又无 python3 时，巡逻明确失败并给出原因，绝不悄悄使用提权手段。
- 缓存里的 semgrep 版本在首次下载时锁定；如需升级，清空缓存目录后重跑即可。
开源协议与致谢
| 项目 | 协议 | 用途 |
|---|
| dsh-code-scan | MIT | Semgrep 扫描能力封装，作为基础扫描模块 |
| dsh-plugin-hos-forge-v2 | MIT | 参考其 MCP 编排思路 |
| dsh-web（dsh-ssh 子包） | Apache-2.0 | 提供 SSH/SFTP 能力，独立封装为 dolphin-ssh-core.js |
| ssh2 | MIT | 底层 SSH 协议库 |
| semgrep | LGPL-2.1 | 开源静态分析引擎 |
本项目自身采用 MIT 协议发布。
相关文档
常见问题（FAQ）与排障指南
安装 DSH 插件时遇到 pnpm 报错怎么办
报错现象（在 D:\DSH 上通过 dsh plugin --profile web add dsh-dolphin-security 安装时可能出现）：
[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: ssh2@1.17.0, cpu-features@0.0.10
dsh: pnpm failed in profile directory D:\DSH\profiles\web
根因：pnpm 出于安全策略，默认不允许依赖包执行构建脚本（build scripts），从而拒绝了 ssh2 与 cpu-features 正常编译，导致 pnpm 以非零状态退出、dsh 认为插件安装失败（依赖已写入但 bundle 未注册）。
解决办法：进入 DSH 的 profile 目录（如 D:\DSH\profiles\web，即 pnpm-workspace.yaml 所在目录），执行：
pnpm approve-builds --all
该命令会放行所有待审批的构建脚本（ssh2、cpu-features），并把 pnpm-workspace.yaml 中的 allowBuilds 置为 true。若希望逐个挑选，可去掉 --all 走交互式界面。
如果无法执行 pnpm approve-builds，也可以手动编辑该目录下的 pnpm-workspace.yaml，将占位符值改为 true：
allowBuilds:
cpu-features: true
ssh2: true
放行后重新执行插件安装（dsh plugin --profile web add dsh-dolphin-security）即可成功；可用 dsh --profile web --dump-config 检查配置树中是否出现该插件的挂载节点。
许可证
本项目采用 MIT 协议发布。请合法、合规、获授权使用。
