CATS 文档可在 https://endava.github.io/cats/ 获取
REST API 模糊测试与负向测试工具。无需编写代码,几分钟内即可运行数千个自愈式 API 测试!
时间紧张?查看1 分钟快速入门指南!
通过使用简单且极简的语法以及平缓的学习曲线,CATS(Contract API Testing and Security,契约 API 测试与安全)使你能够在几分钟内生成数千个 API 测试,且无需编写代码。
所有测试均基于一组预定义的 160+ 个 Fuzzer(外加 31 个用于持续模糊测试的随机变异器)自动生成、运行并报告。
这些 Fuzzer 覆盖了广泛的边界测试、类型强制转换、注入和负向场景:从大型 Unicode 和控制字符载荷,到根据请求数据类型和约束推导出的上下文相关值,以及针对 IDOR、PUT 幂等性、更新-读取一致性、条件 ETag 处理、已删除资源可用性和敏感数据暴露的有状态检查。
开箱即用,CATS 会将生产者 POST 路径排在依赖操作之前,跨路径以广度优先波次执行 Fuzzer,复用从 2XX 响应中学习到的标识符和基线用于后续请求,将 HappyPath 的 DELETE 调用推迟到运行结束,并根据 OpenAPI 3.0 和 3.1 模式验证响应。你还可以使用 cats run 以 YAML 编写端到端功能测试。
# Run the full suite against an OpenAPI contract
cats -c openapi.yml -s http://localhost:8080
# Run a built-in profile (quick, security, compliance, ci, coverage, crash, type-coercion, health-check)
cats -c openapi.yml -s http://localhost:8080 --profile quick
# Run for a fixed time budget, continuing with random mutations if deterministic fuzzers finish early, and enforce a quality gate
cats -c openapi.yml -s http://localhost:8080 --stopAfterTimeInSec 60 --fillTimeBudget --qualityGate "errors<1"
# Lint the OpenAPI contract
cats lint -c openapi.yml
# Inspect dependency-ordered paths or explain a profile/fuzzer
cats list --paths --executionOrder -c openapi.yml
cats explain --type profile security
# Replay a test case or print the equivalent curl command
cats replay Test12
cats replay Test12 --curl
在常规模糊测试命令中使用 --tui,即可在不离开终端的情况下跟踪执行过程并查看结果:
cats --contract openapi.yml --server http://localhost:8080 --tui
概览使用与 CLI 和 HTML 报告相同的术语显示路径、运行配置、响应时间、HTTP 响应代码、成功/警告/错误以及已运行的模糊测试器。模糊测试器表格使用所有可用的终端行;当完整列表无法容纳时,使用 j/k 或 Page Up/Page Down 浏览。按 2 查看执行详情,按 3 查看执行摘要和质量门结果,按 4 查看按结果原因分类的执行详情,按 5 查看包含的路径,或按 6 查看按响应时间排序的已执行测试。结果原因和路径行可通过 Enter 打开其匹配的测试。
使用方向键或 j/k 选择测试,然后按 Enter 在全屏详情视图中检查其请求、响应、结果、跟踪和重放命令。在测试列表中按 / 可搜索测试 ID、模糊测试器、路径、场景、结果原因、方法、结果和响应代码。a、e、w、s 和 i 分别筛选全部、错误、警告、成功和跳过的结果。Esc 首先清除活动搜索,否则返回上一屏幕;1 打开概览。
按 q 离开界面。在活动运行期间,这会请求取消,尽可能完成当前测试,保留已写入的结果,并以状态 130 退出。执行完成后,q 正常退出。
TUI 需要至少 80 列 × 24 行的交互式终端,且不能与 --dryRun 组合使用。它适用于基于 OpenAPI 的模糊测试命令;独立的 template 命令继续使用常规 CLI 输出。TUI 默认保留最近 10,000 条测试详情;使用 --tuiMaxResults 选择不同的正数限制。当较旧的详情被丢弃时,聚合统计仍覆盖完整运行。
以下是包含使用 CATS 分步指南的文章列表:
> brew tap endava/tap
> brew install cats
CATS 以可执行 JAR 或原生二进制文件的形式提供。原生二进制文件无需安装 Java。
下载适用于你操作系统的原生二进制文件后,你可以将其添加到 PATH 中,以便像其他任何命令行工具一样执行它:
sudo cp cats /usr/local/bin/cats
你可以直接从二进制文件为 bash 或 zsh 启用 shell 补全:
source <(cats generate-completion)
或者,你可以从仓库中 source cats_autocomplete 脚本:
source cats_autocomplete
要使补全持久生效,请将该命令添加到 .zshrc 或 .bashrc 中。
Windows 没有原生二进制文件,但你可以使用 uberjar 版本。这需要安装 Java 25+。
你可以通过 java -jar cats.jar 运行它。
前往 releases 页面下载最新版本:https://github.com/Endava/cats/releases。
你可以在本地机器上从源码构建 CATS。你需要 Java 25。Maven 已随附。
在运行首次构建之前,请确保运行
./mvnw clean。CATS 使用了 OkHttp(com.squareup.okhttp3:okhttp:5.5.0-CATS)和 Swagger Parser(io.swagger.parser.v3:swagger-parser-v3:2.1.49-CATS)的修补分支,Maven 会从lib/本地安装这些依赖,而不会覆盖官方依赖版本。
你可以使用以下 Maven 命令将项目构建为 uberjar:
./mvnw package -Dquarkus.package.jar.type=uber-jar -DskipTests
你将在 target 文件夹中得到一个 cats-runner.jar。你可以通过 java -jar cats-runner.jar ... 运行它。
你还可以使用 GraalVM Java 版本构建原生镜像。
./mvnw package -Pnative
在运行单元测试时,你可能会看到一些 error 日志消息。这些是测试 Fuzzer 负面场景时的预期行为。
CATS 默认验证服务器证书和主机名。对于使用自签名证书的可信测试环境,可以通过 --insecure 显式禁用验证。
对于双向 TLS,请使用 --sslKeystore、--sslKeystorePwd 和 --sslKeyPwd。如果省略 --sslKeyPwd,CATS 将使用 keystore 密码作为私钥密码。
CATS 默认在报告中遮蔽身份验证标头和敏感查询参数,将请求值替换为可重放的 $$EnvironmentVariable 占位符。它会在运行 CATS 的目录中创建不含机密值的 replay.env.example。
当存在 ./.env 时,CATS 会自动加载它。使用 --envFile path/to/cats.env 选择其他文件,或在 normal、random、functional、template 和 replay 命令中使用 --noEnvFile 禁用 dotenv 加载。进程环境变量优先于 dotenv 值。仅在明确需要未遮蔽的报告和控制台输出时,才使用 --showSecrets。
通过 --wfcAuth 和 --wfcAuthName 支持 Web Fuzzing Commons 身份验证文件。当省略 --wfcAuthName 且文件定义了多个条目时,CATS 从第一个条目开始,如果基线请求返回 HTTP 401 或 403,则切换到后续条目。
CATS 会取消超过 --callTimeout(默认 20 秒)的调用,并且最多捕获 --maxResponseBytes(默认 10 MiB 的解压响应体)。将任一选项设置为 0 可禁用其限制。被截断的响应会保留其状态和标头,跳过完整正文验证,并会以专用警告进行报告。
启用 --dryRun 时,CATS 会解析本地配置并计算测试数量,而不会调用目标服务、WFC 登录端点、身份验证脚本、更新检查或报告写入器。
请参阅 CONTRIBUTING.md。