dsh-dolphin-security

Dolphin（小海豚）—— 主动巡检型安全防御插件

本项目已收录于 dsh-plugin.org 官方插件市场（Listed on dsh-plugin.org）

将渗透测试方法论（信息收集 → 漏洞探测 → 利用验证 → 报告）转化为主动防御巡检流程，填补 DSH 生态中"主动防御巡检"的空白。 不再被动等告警，而是像海豚巡游一样，定期、主动地对目标主机做安全扫描与评估。

当前版本：v0.2.4（修复 Windows Git Bash 主机上 SFTP 与 exec 两条通道的 /tmp 路径错位——新增 detectRemoteTempBase 统一远端临时目录映射，远程规则文件上传后必达扫描目录）

---

⚠️ 免责声明

本项目为技术研究工具，严禁用于非法渗透测试。

• 本工具仅限用于你拥有合法所有权、或已获得明确书面授权的系统与代码。
• 使用本工具对任何第三方系统发起扫描、探测或连接，可能违反《网络安全法》《刑法》等相关法律法规。
• 作者不对任何因使用、误用或滥用本工具造成的直接或间接损失承担责任。
• 你必须获得明确授权方可使用。 使用者需自行承担全部法律责任与后果。

---

适用环境

项目	要求
操作系统	跨平台：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 协议发布。

---

相关文档

• CHANGELOG.md —— 更新日志
• README_EN.md —— English README
• WINDOWS_PREVIEW_GUIDE.md —— Windows 预览版交付说明（新手请先读这份）
• DEVELOPMENT_LOG.md —— 开发日志与踩坑记录
• docs/SSH_RECON_REPORT.md —— dsh-ssh 源码侦察报告与适配方案
• docs/RECON_REPORT.md —— dsh-code-scan 源码侦察报告

---

常见问题（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 协议发布。请合法、合规、获授权使用。