bennamrouche/dirbuster-ng

## 目录 1. [概述](#overview) 2. [状态](#status) 3. [功能](#features) 4. [截图](#screenshots) 5. [环境要求](#requirements) 6. [快速开始](#quick-start) 7. [用法](#usage) - [GUI](#gui) - [CLI](#cli-headless) - [选项参考](#options-reference) - [示例](#examples) 8. [扫描模式](#scan-modes) 9. [报告](#reports) 10. [恢复](#resume) 11. [HTTP 配置](#http-configuration) 12. [原生打包](#native-packaging) 13. [本地测试目标](#local-test-target) 14. [架构](#architecture) 15. [项目结构](#project-layout) 16. [开发](#development) 17. [路线图](#roadmap) 18. [法律与免责声明](#legal--disclaimer) 19. [致谢与许可](#credits--license) ## 概述 `dirbuster-ng` 接收一个目标 URL，并对候选路径发送大量 HTTP 请求，以查明哪些路径是存在的。候选项来自**字典（wordlist）**或通过**字符集生成**，可选择与**文件扩展名**列表（`.php`、`.bak` 等）结合使用。当它发现一个目录时，可以对其进行**递归**扫描，并且能够**解析返回的 HTML** 以发现更多需要探测的链接。为了保持结果整洁，它首先会学习目标对“未找到（not found）”情况的基础（baseline）响应，并根据该基准过滤匹配结果。 这是对经典 **OWASP DirBuster** 的全面现代化改造： | | 旧版 DirBuster | dirbuster-ng | | --- | --- | --- | | Java | Java 6/7 时代 | **Java 21** | | UI | Swing | **JavaFX**（浅色/深色）+ 无头 CLI | | 并发 | OS 线程 | **虚拟线程** | | HTTP | HttpClient 3.x | **Apache HttpClient 5** | | 报告 | 文本/XML | 文本、**HTML**、**Markdown**、**JSON Lines** | | 构建 | Ant | **Maven** | | 包名 | `com.sittinglittleduck.DirBuster` | `net.alphaben.dirbusterng` | - **包名：** `net.alphaben.dirbusterng` - **坐标：** `net.alphaben:dirbuster-ng:0.1.0` - **作者：** alphaben · **许可证：** MIT · **基于：** [OWASP DirBuster](https://owasp.org/www-project-dirbuster/) ## 状态 | 领域 | 状态 | | --- | --- | | 核心扫描引擎（所有模式） | ✅ 正常工作 | | 无头 CLI | ✅ 正常工作 | | JavaFX GUI（设置 → 运行 → 报告） | 🟡 可用，正在完善 | | 递归 + HTML 链接解析 | ✅ 正常工作 | | 虚拟线程并发 | ✅ 正常工作 | | 基础 / 误报过滤 | ✅ 正常工作 | | 报告：文本 / HTML / Markdown / JSON Lines | ✅ 正常工作 | | 恢复 / 检查点（checkpointing） | 🟡 实验性（仅限基于列表的扫描） | | 速率限制 | ✅ 正常工作 | | 代理 / HTTP 认证 / 自定义 header | 🟡 已在引擎中接入，GUI 覆盖部分尚不完全 | | 原生应用镜像（jpackage） | ✅ Linux 已验证；其他操作系统未测试 | | 自动化测试 (JUnit 5) | 🟡 增加中（约 12 个类） | ✅ 正常工作 · 🟡 部分实现/进行中 · ❌ 未开始 ## 功能 **扫描** - 四种扫描模式：基于列表、纯暴力破解以及 URL 模糊测试（列表和暴力）—— 参见 [扫描模式](#scan-modes)。 - 递归目录发现（使用 `-R` 切换）。 - 文件扩展名模糊测试（例如 `-e php,bak,old`）。 - HTML 链接解析，用于从响应中发现更多路径（使用 `-P` 切换）。 - 基准检测，可处理 soft-404 和不一致的基础情况响应。 - 自动选择 HEAD/GET，或仅使用 GET（`-g`）。 **性能与控制** - Java 21 **虚拟线程**工作线程池；可配置线程数（`-t`）。 - 请求**速率限制**以保持适度。 - 引擎内置暂停/恢复/停止控制。 **HTTP** - 核心 Apache HttpClient 5。 - 代理（可选代理认证）、HTTP 认证、自定义 header、User-Agent、超时、可选的重定向跟随 —— 全部通过 `HttpConfig` 实现，并通过 Java `Preferences` 持久化。 **报告** - 易于阅读的**文本**报告（在无头模式下退出时自动保存）。 - **HTML** 和 GitHub 风格的 **Markdown** 高级报告。 - **JSON Lines / NDJSON** 实时流（`-j`），用于通过管道传输给其他工具。 - 实时扫描统计（速度、总数、进度）。 **前端与打包** - JavaFX GUI（[AtlantaFX](https://github.com/mkpaz/atlantafx) 浅色/深色主题）和一个共享同一引擎的无头 CLI。 - 通过 `jpackage` 构建自包含的**原生应用镜像**（捆绑 jlink runtime —— 运行时无需单独的 JDK/JavaFX）。 ## 截图 ## 环境要求 - **JDK 21+** - **Maven 3.8+** - _（可选）_ Docker —— 用于内置的 nginx 测试目标。 ## 快速开始 ``` # 1. 构建 (生成 target/dirbuster-ng-0.1.0-full.jar) mvn clean package # 2a. 启动 GUI java -jar target/dirbuster-ng-0.1.0-full.jar # 2b. …或运行 headless 扫描 java -jar target/dirbuster-ng-0.1.0-full.jar -H -u https://example.com/ ``` 在开发过程中，您可以跳过构建 jar 包，直接使用 `mvn javafx:run` 从源码运行 GUI。 ## 用法 ### GUI ``` java -jar target/dirbuster-ng-0.1.0-full.jar # empty setup screen java -jar target/dirbuster-ng-0.1.0-full.jar -u https://example.com/ # target prefilled ``` 启动时**不带** `-H` 参数将打开 JavaFX 界面。在命令行中传入的任何 URL/字典/报告值都会用于预填充设置界面。 ### CLI（无头模式） ``` java -jar target/dirbuster-ng-0.1.0-full.jar -H -u https://example.com/ ``` `-H` 在无 GUI 模式下运行，并在退出时自动保存报告。非常适合自动化和 pipeline。 ### 选项参考 | 选项 | 参数 | 描述 | 默认值 | | --- | --- | --- | --- | | `-h` | | 显示帮助并退出 | — | | `-H` | | 无头模式（无 GUI）；退出时自动保存报告 | GUI | | `-u` | `` | **目标 URL**，例如 `http://example.com/` | _必填_ | | `-l` | `` | 用于基于列表的暴力破解的字典 | `directory-list-2.3-small.txt` | | `-e` | `` | 逗号分隔的扩展名列表，例如 `asp,aspx` | `php` | | `-t` | `` | 工作线程数 | `10` | | `-s` | `` | 扫描的起始点 | `/` | | `-g` | | 仅使用 `GET` 请求 | 自动 (HEAD/GET) | | `-P` | | **不**解析 HTML 中的链接 | 解析 | | `-R` | | **不**对发现的目录进行递归 | 递归 | | `-r` | `` | 文本报告输出路径 | `dirbuster-ng-Report-[host]-[port].txt` | | `-j` | `` | 同时以 JSON Lines 格式实时流式传输结果/错误 | 关闭 | | `-c` | `` | 恢复/检查点文件（用于基于列表的扫描） | 关闭 | | `-v` | | 详细输出 | 关闭 | ### 示例 ``` # 50 个线程，探测 .php 和 .bak，将 JSON Lines 流式传输到文件 java -jar target/dirbuster-ng-0.1.0-full.jar -H -u https://example.com/ \ -t 50 -e php,bak -j results.jsonl # Non-recursive，仅限 GET，自定义 wordlist，从 /app 开始 java -jar target/dirbuster-ng-0.1.0-full.jar -H -u https://example.com/ \ -R -g -s /app/ -l /usr/share/wordlists/common.txt # 可恢复扫描 — 重新运行相同的命令以从停止处继续 java -jar target/dirbuster-ng-0.1.0-full.jar -H -u https://example.com/ \ -c scan.checkpoint ``` ## 扫描模式 | 模式 | 功能描述 | 候选来源 | | --- | --- | --- | | **基于列表** | 针对目录/文件进行字典暴力破解（推荐的默认方式） | 字典 | | **纯暴力破解** | 通过字符集枚举名称 | 生成 | | **URL 模糊测试（列表）** | 替换 URL 中的标记，值来源于字典 | 字典 | | **URL 模糊测试（暴力）** | 替换 URL 中的标记，值由生成得出 | 生成 | 每种模式都是一个 `ScanMode` 常量，携带着自身的工作生成器，因此引擎可以在没有分支逻辑的情况下实现“模式 → 行为”的直接映射。 ## 报告 | 格式 | 触发方式 | 描述 | | --- | --- | --- | | 文本 | `-r ` / 无头模式下自动生成 | 发现结果的纯文本摘要 | | HTML | 高级报告生成器 / GUI | 具有按状态划分区块的样式化单页 | | Markdown | 高级报告生成器 / GUI | GitHub 风格的“readme”报告 | | JSON Lines | `-j ` | 每个事件输出一个 JSON 对象，实时流式传输 | **JSON Lines** 每行输出一个对象（NDJSON），字段采用固定顺序，从而保证输出结果稳定且支持 grep： ``` {"event":"result","type":"dir","url":"http://t/admin/","status":200} {"event":"result","type":"file","url":"http://t/x.php","status":200} {"event":"error","url":"http://t/y","message":"Connection refused"} ``` GUI 支持在应用内预览 HTML/Markdown 报告（通过 CommonMark 渲染）。 ## 恢复 传入 `-c ` 即可在基于列表的扫描过程中为已探测的候选项和结果建立检查点。重新运行**带有相同文件的相同命令**，将跳过已完成的工作，并从上次中断的地方继续。 ## HTTP 配置 除了 CLI 标志外，引擎的 `HttpConfig` 还支持： - HTTP 代理，支持可选的代理认证 - HTTP 认证（凭据、realm/domain、认证类型） - 自定义请求 header 和可配置的 **User-Agent** - 连接超时和可选的重定向跟随 这些均通过 GUI 的**设置**界面展现，并通过 Java `Preferences` 进行持久化。针对每一个选项的 GUI 覆盖功能仍在不断完善中。 ## 原生打包 构建一个自带精简版 Java runtime 的独立启动器 —— 运行时无需系统 JDK/JavaFX： ``` packaging/build-app-image.sh # then: target/dist/dirbuster-ng/bin/dirbuster-ng ``` `jpackage` 无法进行交叉编译，因此请在每个目标操作系统/架构上运行此命令。已在 Linux 环境下使用 JDK 21 进行了验证。 ## 本地测试目标 项目内置了一个一次性的 nginx 测试平台，其中的内容旨在涵盖每种扫描模式以及各种边缘情况（重定向、认证、禁止访问、不一致的基础响应）： ``` cd docker/nginx-testbed docker compose up --build -d # serves http://localhost:8088/ docker compose down # stop it ``` 参见 [docker/nginx-testbed/README.md](docker/nginx-testbed/README.md)。仅供开发/测试使用 —— 不属于 Maven 构建的一部分。 ## 架构 扫描引擎（`core`）**完全不需要了解任何 UI**；两个前端都通过 `ScanUiListener` 接口对其进行驱动，因此 GUI 和 CLI 共享同一条代码执行路径。 ``` net.alphaben.dirbusterng ├── app/ Entry point — chooses GUI vs headless ├── cli/ Argument parsing + headless runner ├── core/ UI-agnostic scan engine │ ├── http/ Apache HttpClient 5 wrapper + config │ ├── candidates/ Wordlist / brute-force candidate sources │ ├── workGenerators/ Per-mode work generation │ ├── bruteForceIterator/ Character-set enumeration │ ├── html/ Jericho link extraction │ ├── session/ Worker pool, queues, resume, dedup, rate limit │ ├── report/ Text / HTML / Markdown / JSON Lines writers │ ├── monitorThreads/ Progress + statistics │ └── ui/ Listener interfaces the front ends implement └── guifx/ JavaFX UI (controllers, FXML, view models) ``` ## 项目结构 ``` dirbuster-fx/ ├── pom.xml # Maven build ├── src/ │ ├── main/java/net/alphaben/dirbusterng/ # app / cli / core / guifx │ ├── main/resources/ # FXML, CSS, images │ └── test/java/... # JUnit 5 tests ├── docs/ # architecture blueprints & design notes ├── packaging/ # jpackage app-image build script ├── docker/nginx-testbed/ # local test server └── README.md ``` ## 开发 ``` mvn test # run the JUnit 5 test suite mvn javafx:run # run the GUI from source mvn clean package # build the fat jar (runs tests) ``` 设计和迁移笔记存放在 [`docs/`](docs/) 目录中：包含整洁架构蓝图、核心/GUI/CLI 分离、基础响应处理以及扫描类型文档。 ## 路线图 - [ ] 完善所有 `HttpConfig` 选项的 GUI 覆盖（代理 / 认证 / header） - [ ] 将恢复支持扩展到基于列表的扫描之外 - [ ] 扩充自动化测试套件 - [ ] 跨平台原生镜像（Windows / macOS）+ CI 打包 - [ ] 稳定 CLI 标志和报告 schema，为发布 1.0 版本做准备 ## 法律与免责声明 本工具仅供**授权的安全测试和教育用途**。请仅扫描您拥有或获得**明确书面许可**进行测试的系统。对您无权控制的系统进行未经授权的扫描可能是违法的您需对自身的使用方式承担全部责任。 ## 致谢与许可 基于由 James Fisher 创建的原版 [OWASP DirBuster](https://owasp.org/www-project-dirbuster/)。现代化重写版本（`net.alphaben.dirbusterng`）由 **alphaben** 完成。基于 **MIT License** 发布。

标签：JavaFX, Web安全, 域名枚举, 目录爆破, 蓝队分析, 蓝队工具, 请求拦截