Ruoyi-Scan — 若依专项漏洞扫描工具

中文 | English

一款合法授权的若依（RuoYi）专项漏洞扫描器，插件化架构，三态判定（CONFIRMED / SAFE / UNKNOWN）。 支持批量扫描、多格式报告、WAF 绕过（含对抗型传输层）、漏洞利用链、Web API 等企业级特性。 桌面端已上线 —— 单个 exe 双击即用，无需 Python / Docker / 任何环境配置。 ⭐ 如果这个工具对你有帮助，欢迎点个 Star 支持一下，让更多人看到它。

pip install ruoyi-scan

不想装 Python？终端版 ruoyi-scan.exe（命令行，约 38 MB，免安装）或 桌面端单文件版（双击即用）。

不知道什么时候该用它？先看 使用指导（六个真实场景 + 20 条实战技巧）； 全部命令见 操作命令手册，能覆盖哪些漏洞见 插件清单。

⚠️ 成熟度声明与共建邀请 Ruoyi-Scan 目前以内置签名靶场与真实版本栈为主要验证环境，尚未经过大规模实战项目检验， 因此不对漏洞检出率（产出率）、漏报率与误报率做任何承诺 —— 拿不准的项一律如实标注 UNKNOWN，不凑数。 项目会保持小步快跑的迭代节奏，判定质量逐版本持续收敛。 欢迎共建：提交 Issue 或 PR； 也欢迎自行 fork 二次开发 —— 基于 MIT License，衍生作品**标注原版出处（XIABAI / Ruoyi-Scan）**即可。

演示

上图：对内置若依签名靶场执行综合扫描，实时展示风险分布与漏洞列表。

命令行 · 真实运行截图

以下均为对本机签名靶场（lab/，vuln / safe 双模式）的真实运行记录：vuln 模式 23 个漏洞全部命中，safe 模式零误报。

帮助 —— python main.py -h：5 种扫描模式与全部可选长参数一览。

综合扫描（进行中） —— 自动指纹识别（cms=ruoyi，置信度 0.70）、WAF 特征检测、目录扫描实时输出。

综合扫描（结果） —— 未授权访问、Nacos 配置泄露、SSTI、任意文件读取、定时任务 RCE 等逐一判定；Druid 弱口令 ruoyi/123456 与后台默认口令 admin/admin123 爆破成功。

登录爆破 —— -l 模式：Druid 弱口令与后台默认口令一键爆破，命中即判定。

零误报验证 —— 对 safe 靶场（全修复模式）执行漏洞检测：满屏「不存在」，拿不准的如实标注「无法判定」，不凑数、不误报。

报告生成 —— --report reports：扫描摘要（耗时 / 风险分布 / 去重统计）+ 7 种格式报告一键落盘。

桌面端 · 单个 exe，双击即用

引擎、54 个 POC、Web 控制台全部在编译期嵌入同一个文件。无需 Python、无需 Docker、无需任何环境配置 —— 对没有开发环境的机器，这是最省事的用法。

总览 —— 三态判定实时分布、任务趋势、最新发现。SAFE 与 UNKNOWN 在设计上就与 CONFIRMED 分开展示，不做「结果全红」的扫描器。

扫描现场 —— WebSocket 实时日志流、插件进度、结果明细（可按三态筛选）。下方三态统计卡与引擎在线状态一目了然。

漏洞库 —— 54 个 POC 插件一览，含严重度、CVE / CNVD 编号、影响版本区间、WAF 绕过支持标记。

个性化 —— 4 套主题包、6 个核心色派生 30 个设计 token、操作员人格（11 个预设形象 + 自定义代号）、CRT 扫描线与字体模式。

下载

实现要点

更多细节见桌面端文档。

为什么不直接用通用扫描器

Ruoyi-Scan 不与 nuclei / xray 竞争，而是互补 —— 它们负责广度，我们负责若依生态的深度与判定纪律。

把话说全：模板存量、跨框架广度、社区规模这三项我们明确落后 —— nuclei 数千个模板的存量与 多框架覆盖是真护城河，本项目短期内追不上，也不打算追。我们做的是另一件事： 在若依生态里给出「这个漏洞确实存在 / 确实不存在 / 无法判定」的判定与可交付报告。 两者是互补关系：先用通用工具铺开广度，再对疑似目标用本工具做深度确认与合规交付。

一句话：通用扫描器告诉你「这里可能有东西」；Ruoyi-Scan 告诉你「这个漏洞确实存在 / 确实不存在 / 无法判定」，并直接产出可交付的报告。

若依是国内应用最广的开源 Java 后台框架之一，二次开发项目在政企与外包中大量存在。通用工具在它面前的问题是不知道对面是什么 —— 指纹粗糙、变体不辨、版本无感，于是误报与漏报同时发生。我们把「扫得准」做在前面。

文档

📖 在线文档站 —— 全部文档已编组上线（mkdocs-material），推荐从那里开始。

项目定位

• 作者：XIABAI
• 版本：1.5.2
• 仓库：https://github.com/xiabai2008/Ruoyi-Scan
• 技术栈：Python 3.8+ / requests / FastAPI / Docker
• 许可：MIT License

核心能力

快速开始

方式一：pip 安装（推荐）

# 安装（自动安装核心依赖）
pip install ruoyi-scan

# 可选功能依赖（按需安装）
pip install pyyaml          # --config YAML 配置文件
pip install redis           # --distributed Redis 分布式扫描
pip install aiohttp         # --async 异步 HTTP 客户端
pip install "ruoyi-scan[adversarial]"  # --adversarial-transport 对抗型传输层（Scrapling）

# 运行扫描
ruoyi-scan -p http://target:8080/

方式二：从 Release 下载（离线 / 无 Python 环境）

前往 Releases 页面：

• 完全不想装 Python：下载 ruoyi-scan.exe（终端版，约 38 MB），放到任意目录后在 CMD / PowerShell 里运行，参数与 pip 版一致：

  .\ruoyi-scan.exe -V
  .\ruoyi-scan.exe -u http://target:8080/ --report .\reports\demo
  

• 已有 Python、想离线装包：下载最新 .whl，然后：

  pip install ruoyi_scan-1.5.2-py3-none-any.whl
  

方式三：源码安装

git clone https://github.com/xiabai2008/Ruoyi-Scan.git
cd Ruoyi-Scan
pip install -r requirements.txt

# 单目标漏洞扫描
python main.py -p http://target:8080/

# 批量扫描
python main.py -f targets.txt -p --report ./reports

# 手动指定 CMS（跳过指纹识别）
python main.py -p http://target:8080/ --cms ruoyi

# 综合扫描（目录扫描 + 漏洞检测 + 登录爆破）
python main.py -u http://target:8080/

# 生成全格式报告（HTML/JSON/CSV/PDF/Word/Excel）
python main.py -p http://target:8080/ --report ./reports --report-format all

# docx 合规报告模板 / 整改复测（G5）
python main.py -p http://target:8080/ --report ./reports --report-template ./templates/compliance.docx
python main.py -p http://target:8080/ --remediation ./baseline.json --report ./reports

# WAF 绕过（检测到 WAF 自动启用）
python main.py -p http://target:8080/ --bypass-waf auto

# 对抗型传输层（Scrapling；需先安装 [adversarial] 可选依赖）
python main.py -p http://target:8080/ --adversarial-transport

# 执行漏洞利用链
python main.py --chain ruoyi_sql_to_rce -u http://target:8080/
python main.py --chain list  # 列出可用链

# 组件版本检测（fastjson/SpringBoot/Shiro/Nacos/Log4j → CVE 比对）
python main.py -p http://target:8080/ --components

# 执行 nuclei 模板（nuclei-templates 生态直接复用）
python main.py -p http://target:8080/ --nuclei examples/nuclei/
python main.py --nuclei-validate examples/nuclei/  # 模板校验（不扫描）

# AI 生成插件（LLM 自验证回灌；无 Key 时降级规则模板）
python main.py --ai "检测若依任意文件读取漏洞" --category ruoyi

# 插件模板仓库（社区分发）
python main.py --plugin-export ./ruoyi-scan-templates
python main.py --plugin-manifest ./ruoyi-scan-templates  # 生成/校验 manifest（Ed25519 签名）
python main.py --plugin-update  # 从官方仓库更新插件

# Web API 服务
python main.py --serve
# 访问 http://localhost:8000/ (Web 控制台)
# 访问 http://localhost:8000/docs (OpenAPI 文档)

# 端口扫描 + 漏洞检测
python main.py -p http://target:8080/ --portscan

# 被动代理模式
python main.py --passive --passive-port 8080

# Docker 部署（见下方「Docker 部署」章节）
# docker-compose up -d

Docker 部署

Ruoyi-Scan 提供生产就绪的 Docker 镜像（多阶段构建、非 root 用户）。

构建镜像

docker build -t ruoyi-scan .

扫描目标

# 基本扫描
docker run --rm ruoyi-scan -p http://target/

# 扫描并保存报告到宿主机
docker run --rm -v $(pwd)/reports:/app/reports ruoyi-scan \
  -p http://target/ --report /app/reports

Web API 服务

# 启动 FastAPI Web API（端口 8000）
docker run --rm -p 8000:8000 ruoyi-scan --serve --host 0.0.0.0 --port 8000

# 带认证的 API
docker run --rm -p 8000:8000 -e RUOYI_SCAN_API_KEY=your-secret ruoyi-scan \
  --serve --host 0.0.0.0 --port 8000 --api-key your-secret

Docker Compose 一键部署

# 启动全部服务（扫描器 + API + 2 个签名靶场）
docker compose up -d

# 扫描内置靶场
docker compose run --rm scanner -p http://lab-ruoyi:8080/ --report /app/reports

# 启动监控栈（Prometheus + Grafana）
docker compose --profile monitor up -d
# Grafana: http://localhost:3000 (admin/admin)
# Prometheus: http://localhost:9090

# 清理
docker compose down

CLI 参数速查

完整参数说明请运行 python main.py -h。以下按功能分组列出全部参数。

核心扫描模式

网络与并发

信息收集（D14）

报告与输出

WAF 绕过与利用链

组件版本与 nuclei 模板（D4/E2）

认证扫描（D26）

Web API 服务（D9/D11）

详细的 API 端点说明、请求/响应示例、WebSocket 事件格式请参考 API 使用指南。 OpenAPI 3.0 规范可通过 python scripts/export_openapi.py 导出至 docs/openapi.json。

OAST 带外检测（D30）

业务逻辑检测（D31）

认证后深度扫描（G1）

AI 能力（E7/E8/G3）

CVE 同步（D32）

SIEM 集成（D33）

异步引擎（D34）

Web UI 控制台（D35）

分布式扫描（D36）

结果缓存（D37）

通知（D21）

插件 SDK（D25）

插件模板仓库（E5）

CI/CD 集成（D28）

漏洞知识库（D29）

扫描模式速览

核心命令只有两个：-p（单目标漏洞扫描）和 -u（综合扫描）。两者区别：

# 仅快速确认漏洞（单目标）
python main.py -p http://target:8080/

# 完整评估（目录 + 漏洞 + 爆破）
python main.py -u http://target:8080/

仍不清楚该选哪种？可参考 issue #1 的讨论（两种模式的区别详解）。

目录结构

Ruoyi-Scan/
├── main.py                  # CLI 入口（542 行，纯参数解析+分发）
├── config/settings.py       # 全局配置
├── cli/                     # CLI 控制层
│   ├── dispatcher.py        # 模式分发（工具/服务/扫描三段）
│   ├── runner.py            # 扫描模式执行器（参数 → ScanRequest）
│   └── ...                  # preflight / serve_runner / chain_runner 等
├── core/                    # 核心引擎层
│   ├── orchestrator.py      # 扫描编排器（CLI 与 Web API 共用）
│   ├── engine.py            # 并发编排+令牌桶限速
│   ├── loader.py            # 插件动态发现
│   ├── fingerprint.py       # 指纹识别
│   ├── router.py            # 指纹→插件路由
│   ├── session.py           # 会话封装
│   ├── chain.py             # 漏洞利用链引擎
│   ├── report.py            # 报告渲染（HTML/JSON/CSV）
│   └── ...                  # 更多核心模块
├── common/                  # 共享基础层
│   ├── models.py            # 数据模型（三态判定）
│   ├── console.py           # 控制台编码处理
│   └── logger.py            # 日志配置
├── plugins/                 # 插件系统
│   ├── base.py              # PluginBase 抽象基类
│   ├── ruoyi/               # 若依 20 个插件（含 2 个 Plus 变体专属）
│   ├── spring/              # Spring 14 个 POC
│   ├── jeecgboot/           # JeecgBoot 8 个插件
│   ├── common/              # 通用 12 个插件
│   └── chain/               # 3 条利用链
├── lib/                     # 工具库（41 个模块）
├── api/                     # Web API（FastAPI + WebSocket）
├── data/                    # 字典文件
├── tests/                   # 67 个测试文件 / 1300+ 条用例
├── lab/                     # 靶场环境
├── web/                     # Web 控制台前端
├── monitoring/              # Grafana + Prometheus
├── desktop/                 # Tauri 桌面端（React 前端 + Rust 壳 + 内嵌引擎）
├── scripts/                 # 构建 / 验收 / OpenAPI 导出脚本
├── .github/workflows/       # CI 配置
├── Dockerfile               # Docker 镜像
├── docker-compose.yml       # Docker 编排
├── LICENSE                  # MIT License
└── requirements.txt         # 依赖管理

测试

# 全量测试
python -m pytest tests/ -q

# 若依插件回归
python tests/regression_ruoyi.py

# Spring 插件回归
python tests/regression_spring.py

贡献

欢迎贡献 POC 与改进：

• 报告 Bug / 请求 POC：使用 Issue 模板（Bug / POC 请求 / 功能请求）
• 提交 POC：python main.py --plugin-init <name> 生成骨架 → 实现 verify()（三态判定）→ --plugin-check 验证 → PR（模板含完整 checklist）
• 插件分发：合入后自动进入 ruoyi-scan-templates 官方仓库（Ed25519 签名）
• 开发指南：docs/plugin_dev.md / CONTRIBUTING.md

贡献 POC 前请先在自建靶场（lab/）或授权目标上复现，确保判定特征真实可靠。

自行二次开发：欢迎 fork 后按自己的场景改造（加私有 POC、换判定规则、接入内部系统）。 本项目采用 MIT License，唯一要求是衍生作品中标注原版出处（XIABAI / Ruoyi-Scan，附仓库链接即可）， 不需要额外申请授权，也不限制商用或闭源分发。改造后如果对社区有价值，欢迎回提 PR。

安全与合规

本工具仅用于授权范围内的安全测试与学习研究。不得用于未授权目标。涉及利用的插件默认仅做存在性验证，不做实际破坏。

对抗型传输层（Scrapling）为可选依赖（[adversarial]），默认不安装；启用后同样仅可用于授权测试。

供应链验证：Release 产物附带 SHA256 校验和，可独立验证；v1.4.3 起同时提供 SLSA 构建来源证明。

v1.4.2 及更早版本没有来源证明——证明步骤在 v1.4.2 发布后 48 分钟才合入 release.yml。 对这些版本请只用校验和验证，gh attestation verify 会返回 not found。

# 校验和验证（所有版本）
sha256sum -c checksums.txt
# SLSA 构建来源验证（需 gh CLI，v1.4.3+ 产物）
gh attestation verify ruoyi_scan-<version>-py3-none-any.whl -R xiabai2008/ruoyi-scan

License

MIT License © 2026 XIABAI

作者背景与致谢见 AUTHOR.md。