Dolphin（小海豚）—— 主动巡检型安全防御插件
将渗透测试方法论（信息收集 → 漏洞探测 → 利用验证 → 报告）转化为主动防御巡检流程，填补 DSH 生态中"主动防御巡检"的空白。 不再被动等告警，而是像海豚巡游一样，定期、主动地对目标主机做安全扫描与评估。
当前版本：v0.1.1（正式发布，DSH 生态插件适配层已包含）
⚠️ 免责声明
本项目为技术研究工具，严禁用于非法渗透测试。
- 本工具仅限用于你拥有合法所有权、或已获得明确书面授权的系统与代码。
- 使用本工具对任何第三方系统发起扫描、探测或连接，可能违反《网络安全法》《刑法》等相关法律法规。
- 作者不对任何因使用、误用或滥用本工具造成的直接或间接损失承担责任。
- 你必须获得明确授权方可使用。 使用者需自行承担全部法律责任与后果。
适用环境
| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10 / 11 x64 |
| Node.js | >= 20（推荐 20 LTS 或 22 LTS） |
| 包管理器 | npm（随 Node.js 一并安装） |
| 静态分析引擎 | semgrep（见下方安装指引） |
安装
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 并结构化存档 |
开源协议与致谢
| 项目 | 协议 | 用途 |
|---|---|---|
| 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 协议发布。
相关文档
- 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 协议发布。请合法、合规、获授权使用。
No comments yet. Be the first to write one.