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

中文 | English

一款合法授权的若依（RuoYi）专项漏洞扫描器，插件化架构，三态判定（CONFIRMED / SAFE / UNKNOWN）。 支持批量扫描、多格式报告、WAF 绕过、漏洞利用链、Web API 等企业级特性。 ⭐ 如果这个工具对你有帮助，欢迎点个 Star 支持一下，让更多人看到它。

pip install ruoyi-scan

演示

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

文档

项目定位

• 作者：XIABAI
• 版本：1.3.0
• 仓库：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 客户端

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

方式二：从 Release 下载安装（离线环境）

前往 Releases 页面 下载最新 .whl 文件，然后：

pip install ruoyi_scan-1.3.0-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

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

# 执行漏洞利用链
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 绕过与利用链

认证扫描（D26）

Web API 服务（D9/D11）

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

OAST 带外检测（D30）

业务逻辑检测（D31）

认证后深度扫描（G1）

CVE 同步（D32）

SIEM 集成（D33）

异步引擎（D34）

Web UI 控制台（D35）

分布式扫描（D36）

结果缓存（D37）

通知（D21）

插件 SDK（D25）

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 入口（~440 行，纯参数解析+分发）
├── config/settings.py       # 全局配置
├── core/                    # 核心引擎层
│   ├── runner.py            # 扫描编排器（P0 拆分）
│   ├── engine.py            # 并发编排+令牌桶限速
│   ├── models.py            # 数据模型（三态判定）
│   ├── loader.py            # 插件动态发现
│   ├── fingerprint.py       # 指纹识别
│   ├── router.py            # 指纹→插件路由
│   ├── session.py           # 会话封装
│   ├── chain.py             # 漏洞利用链引擎
│   ├── report.py            # 报告渲染（HTML/JSON/CSV）
│   └── ...                  # 更多核心模块
├── plugins/                 # 插件系统
│   ├── base.py              # PluginBase 抽象基类
│   ├── ruoyi/               # 若依 18 个插件
│   ├── spring/              # Spring 14 个 POC
│   ├── jeecgboot/           # JeecgBoot 8 个插件
│   ├── common/              # 通用 11 个插件
│   └── chain/               # 3 条利用链
├── lib/                     # 工具库（33 个模块）
├── api/                     # Web API（FastAPI + WebSocket）
├── data/                    # 字典文件
├── tests/                   # 51 个测试文件 / 1000+ 条用例
├── lab/                     # 靶场环境
├── web/                     # Web 控制台前端
├── monitoring/              # Grafana + Prometheus
├── .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/）或授权目标上复现，确保判定特征真实可靠。

安全与合规

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

License

MIT License © 2026 XIABAI