dsh-dolphin-security

Readme

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

[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/ccr-wer/dsh-dolphin-security)

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

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

当前版本：**v0.2.2**（修复：LICENSE 许可证声明——清除合并冲突残留标记，恢复纯 MIT 文本，消除 SPDX 扫描的 NOASSERTION 误判）

---

## ⚠️ 免责声明

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

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

---

## 适用环境

| 项目 | 要求 |
|---|---|
| 操作系统 | **跨平台**：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，二选一）

```bash
# 方式 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 环境中通过插件命令挂载：
>
> ```bash
> dsh plugin --profile web add dsh-dolphin-security
> ```
>
> 若脱离 DSH 宿主使用，`dolphin-patrol.js` / `dolphin-core.js` / `dolphin-ssh-core.js` 仍可作为独立库/CLI 直接调用（见「核心功能」），无需 DSH 环境。

### 2. 安装项目依赖（仓库开发）

```bash
npm install
```

> 依赖 `ssh2`（MIT）用于远程 SSH/SFTP 能力。

### 3. 前提：安装 semgrep 并加入 PATH

Dolphin 的扫描能力基于 [semgrep](https://semgrep.dev)（LGPL-2.1）。**必须先安装 semgrep 并确保其可在命令行中直接调用**：

```bash
pip install semgrep
```

安装完成后验证：

```bash
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`）

对本机指定目录执行静态安全扫描，输出结构化漏洞清单并存档报告：

```bash
node dolphin-patrol.js --local <目录>
```

示例：

```bash
node dolphin-patrol.js --local D:/your-project/src
```

### 2. 远程巡逻（`--patrol`）

通过 SSH 将扫描命令下发至远程主机执行，回收结果并本地存档——这是"主动巡检"的完整闭环。

**首次使用前需先登记主机**（以 `test-ssh-hosts.js` 为参考模板）：

```javascript
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',
})
```

然后执行巡逻：

```bash
node dolphin-patrol.js --patrol <alias> <远程目录>
```

示例：

```bash
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. 其他入口

```bash
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](./CHANGELOG.md) —— **更新日志**
- [README_EN.md](./README_EN.md) —— **English README**
- [WINDOWS_PREVIEW_GUIDE.md](./WINDOWS_PREVIEW_GUIDE.md) —— **Windows 预览版交付说明（新手请先读这份）**
- [DEVELOPMENT_LOG.md](./DEVELOPMENT_LOG.md) —— 开发日志与踩坑记录
- [docs/SSH_RECON_REPORT.md](./docs/SSH_RECON_REPORT.md) —— dsh-ssh 源码侦察报告与适配方案
- [docs/RECON_REPORT.md](./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` 所在目录），执行：

```bash
pnpm approve-builds --all
```

该命令会放行所有待审批的构建脚本（`ssh2`、`cpu-features`），并把 `pnpm-workspace.yaml` 中的 `allowBuilds` 置为 `true`。若希望逐个挑选，可去掉 `--all` 走交互式界面。

如果无法执行 `pnpm approve-builds`，也可以手动编辑该目录下的 `pnpm-workspace.yaml`，将占位符值改为 `true`：

```yaml
allowBuilds:
  cpu-features: true
  ssh2: true
```

放行后重新执行插件安装（`dsh plugin --profile web add dsh-dolphin-security`）即可成功；可用 `dsh --profile web --dump-config` 检查配置树中是否出现该插件的挂载节点。

---

## 许可证

本项目采用 [MIT](./LICENSE) 协议发布。请合法、合规、获授权使用。