ConorGriffin-Dev/chaos-monkey

# Chaos Monkey — 自动化 REST API Fuzzer Chaos Monkey 是一款基于 Java 21 的 CLI 工具，它能够读取 OpenAPI 3.x 规范，为每个端点上的每个字段生成具备 schema 感知的 fuzz payload，通过 REST Assured 向运行中的 API 发起攻击，并生成一份完整的 Allure HTML 报告，详细记录它所发现的每一个服务器错误、stack trace 泄漏、意外的成功响应以及性能异常。 它的诞生源于在一个国家级政府平台上进行手动 API 负面路径测试时的真实挫败感——因为在那些平台上，记住各种边界情况完全是测试人员的责任。而 Chaos Monkey 让这不再成为任何人的负担。 ## 前置条件 | 需求 | 版本 | 检查命令 | |-------------|---------|-------| | Java JDK | 21+ | `java -version` | | Maven | 3.8+ | `mvn -version` | | Allure CLI | 最新版 | `allure --version` | | Git | 任意版本 | `git --version` | **安装 Allure CLI：** macOS: `brew install allure` Windows: `scoop install allure` Linux: 从 [allure releases](https://github.com/allure-framework/allure2/releases) 下载并添加到 PATH ## 安装说明 ``` git clone https://github.com/YoungGriff11/chaos-monkey.git cd chaos-monkey mvn clean package -DskipTests ``` 验证： ``` java -jar target/chaos-monkey.jar --help ``` ## 使用方法 ### Spec 感知 fuzz 运行（推荐） ``` java -jar target/chaos-monkey.jar fuzz \ --url https://petstore3.swagger.io/api/v3 \ --spec https://petstore3.swagger.io/api/v3/openapi.json ``` ### 自定义输出目录 ``` java -jar target/chaos-monkey.jar fuzz \ --url https://petstore3.swagger.io/api/v3 \ --spec https://petstore3.swagger.io/api/v3/openapi.json \ --output ./my-fuzz-results ``` ### 自定义超时时间 ``` java -jar target/chaos-monkey.jar fuzz \ --url https://petstore3.swagger.io/api/v3 \ --spec https://petstore3.swagger.io/api/v3/openapi.json \ --timeout 5000 ``` ### 仅标记模式（适用于大型 API — 将报告过滤为仅包含发现的问题） ``` java -jar target/chaos-monkey.jar fuzz \ --url https://petstore3.swagger.io/api/v3 \ --spec https://petstore3.swagger.io/api/v3/openapi.json \ --flag-only ``` ### Dry run（仅预览 payload，不发送请求） ``` java -jar target/chaos-monkey.jar fuzz \ --url https://petstore3.swagger.io/api/v3 \ --spec https://petstore3.swagger.io/api/v3/openapi.json \ --dry-run ``` ### 静态 fuzz 模式（无需 spec） ``` java -jar target/chaos-monkey.jar fuzz \ --url https://jsonplaceholder.typicode.com ``` ## 生成报告 ``` allure serve ./allure-results ``` 或生成一个静态文件夹： ``` allure generate ./allure-results --output ./allure-report --clean ``` ## 报告示例  *针对 Swagger Petstore v3 的 60 个测试套件中的 3343 个 fuzz 用例。运行时长：1小时 05分。* ## Petstore v3 测试发现 针对 `https://petstore3.swagger.io/api/v3` 运行的结果： - 写入端点出现 **SERVER_ERROR** —— `POST /user`、`POST /pet`、`POST /store/order`、`PUT /pet`、`DELETE /pet/{petId}` 在输入格式错误的情况下全部返回 500 错误。服务器直接崩溃而没有进行验证。 - `GET /user/login` 出现 **UNEXPECTED_SUCCESS** —— 发送 `null` 凭证却返回了 token。该端点接受了本应拒绝的输入。 - `GET /user/login` 出现 **VALIDATION_MISSING** —— 用户名和密码字段中超长的字符串被接受并返回了 200 而不是 400。 ## 案例分析 — 真实应用 除了 Petstore 演示之外，Chaos Monkey 还被用来测试一位同行开发的 **Currently**——一个基于 Spring Boot 的能源追踪 API（已获得作者许可），以此测试它在一个从未见过的应用上的表现。 由于目标 API 没有提供 OpenAPI spec，我们在本地添加了 springdoc 来发布一个。随后，Chaos Monkey 自动发现了 **22 个端点**，并发送了 **1,045 个具备 schema 感知的 payload**——运行时使用了有效的 JWT，因此它能够对已认证的端点进行测试，而不是被 `401` 错误拦截。本次运行针对的是由一次性数据库支持的本地实例。 **核心发现：** 普遍存在输入验证缺陷——大约有 **30 个端点在路径参数无法绑定到其预期类型时返回了 `500 Internal Server Error` 而不是 `400 Bad Request`**。示例： - `DELETE /api/users/me/rooms/not_an_int` — 非整数 ID - `PUT /api/users/me/appliances/3.14` — 在预期为整数 ID 的地方输入了小数 - `DELETE /api/vault/files/9999999999` — 整数溢出 - `PUT /api/users/me/rooms/` — 在没有 ID 的情况下写入集合根路径 每次错误的根本原因都是一样的：路径变量绑定失败，Spring 抛出异常，请求落入通用的 500 错误处理器中，而不是被捕获为客户端错误。 **经受住考验的地方：** 每一个 `500` 错误都返回了干净的错误信封，**没有泄漏任何 stack trace 和数据库错误**，JWT 认证屏障**拒绝了针对受保护端点的每一个畸形 payload**，并且没有任何写入端点静默接受无效数据。该工具还正确地**将其自身的“非发现”进行了分类**——将真正的错误与它无法进行 fuzz 的 multipart 端点以及公共只读端点区分开来——因此真正的发现并没有被淹没在噪声中。 这次运行促成了代码库中两项工具改进：**身份验证支持**（`--bearer-token` / `--auth-header`）用于在登录屏障后进行 fuzz，以及 **multipart 端点标记**，这样文件上传端点就不会被误算作服务器错误。 ## 运行测试 ``` mvn test ``` 101 个测试，0 个失败。集成测试（会向 Petstore 发送真实请求）被标记为 `@Tag("integration")`，并在标准构建中排除。要运行它们： ``` mvn test -Dgroups=integration ``` ## CLI 参考 | 参数 | 必填 | 默认值 | 描述 | |----------|----------|---------|-------------| | `--url` | 是 | — | 目标 API 的 Base URL | | `--spec` | 否 | — | OpenAPI 3.x spec 的路径或 URL。省略此项则进入静态 fuzz 模式 | | `--output` | 否 | `./allure-results` | Allure 结果文件的输出目录 | | `--timeout` | 否 | `10000` | 请求超时时间（毫秒） | | `--flag-only` | 否 | `false` | 仅将标记的结果写入报告 | | `--dry-run` | 否 | `false` | 仅解析并生成 payload，不发送请求 | | `--bearer-token` | 否 | — | 在每个请求中作为 `Authorization: Bearer ` 发送的 JWT/token | | `--auth-header` | 否 | — | 完整的 `Authorization` 标头值（例如 `ApiKey xyz`）。覆盖 `--bearer-token` | ## 为什么选择 Chaos Monkey 大多数 API fuzzing 工具要么是安全扫描器（如 Burp Suite），要么需要大量配置才能生成可读的输出。Chaos Monkey 则是： - **Java 优先** —— 基于 REST Assured 和 Spring Boot 构建，这正是企业 Java 团队中的 QA 工程师已经在使用的技术栈 - **Allure 原生** —— 每次运行都会生成 QA 团队早已熟知如何阅读的报告 - **面向 QA** —— 旨在发现数据完整性和错误处理方面的缺陷，而不是用于漏洞利用 ## 文档 完整的设计文档位于 `docs/` 目录中： - `docs/01-system-design/` — 系统设计文档和图表 - `docs/02-architecture/` — 架构决策记录 - `docs/03-build-roadmap/` — 版本化构建路线图 - `docs/04-test-plan/` — 包含测试用例 ID 的完整测试计划 - `docs/05-usage/` — 详细的使用指南 ## 许可证 MIT — 详见 [LICENSE](LICENSE)

标签：API安全, CISA项目, JSON输出, OpenAPI, REST API, 域名枚举