Endava CATS for OpenAPI REST API Fuzzing

Why CATS Targets OpenAPI Contract Gaps

CATS addresses the gap between an API contract and the many invalid requests that ordinary happy-path tests do not exercise. The project describes itself as Contract API Testing and Security, but its documented center of gravity is REST API fuzzing and negative testing. It is for developers, QA engineers, security testers, and teams that already maintain an OpenAPI description and need to probe endpoints systematically.

The target is not random traffic against an arbitrary host. CATS uses fields, headers, data types, and constraints from an OpenAPI contract to construct requests. According to the README, its predefined set contains more than 100 Fuzzers, covering boundary and negative scenarios such as fully random large Unicode values and crafted values based on request types and constraints. The claim is broad test generation rather than a complete security assessment. The README does not describe exploitation, credential attacks, CAPTCHA handling, or account creation workflows.

CATS also treats the contract as an input that can change over time. The README calls the tests self-healing because it generates requests dynamically and picks up OpenAPI specification changes automatically. That is useful for repeated contract-based testing, but it does not mean that every generated assertion is correct. A schema can describe the intended contract while a deployed service has different validation, authentication, authorization, or data rules.

How Contract-Driven Fuzzing Builds Requests

The visible architecture is contract-first. CATS receives an OpenAPI document, identifies paths and request data, then uses scenario-specific Fuzzers to create values and requests. The README says that every field and header is covered, while individual Fuzzers apply expectations appropriate to the scenario under test. This distinction matters: CATS is not merely submitting a single malformed payload and checking for a status code. The generated case carries a scenario and an expected result model.

The documentation gives a normal CLI shape with `--contract` and `--server`. The optional `--tui` adds an interactive terminal interface over the same OpenAPI-backed fuzzing command. Its overview reports Paths, run configuration, response time, HTTP response codes, success, warnings, errors, and Fuzzers run. The detail screens expose the request, response, result, trace, and a replay command. That replay output is especially relevant for engineers who need to move from a generated failure to a focused reproduction.

The TUI supports filtering by result state and searching test IDs, fuzzers, paths, scenarios, result reasons, methods, results, and response codes. It retains the most recent 10,000 test details by default, configurable through `--tuiMaxResults`, while aggregate statistics cover the complete run after older details are discarded. This is a practical constraint for large runs: the report can preserve totals without retaining every detailed record in the terminal interface.

CATS supports filtering by Fuzzers, HTTP response codes, HTTP methods, request paths, and business context. The README also describes dynamic payload generation for simple end-to-end functional tests. That makes the tool more than a response-code scanner, although the README does not explain the internal rule engine or the exact format of business-context configuration.

Installing CATS and Running the First OpenAPI Fuzz

CATS offers Homebrew installation on systems where the tap is available. The README gives these commands:

brew tap endava/tap
brew install cats

The second command installs the CATS command from the Endava Homebrew tap. After installation, the expected result is a `cats` executable available to the shell.

For manual installation, the README says that CATS is bundled as an executable JAR or a native binary. Native binaries do not require Java. The documented native-binary placement command is:

sudo cp cats /usr/local/bin/cats

This copies the downloaded `cats` binary into `/usr/local/bin`, where it can be invoked as `cats` if that directory is on PATH. The README also documents optional autocomplete through `cats_autocomplete`:

source cats_autocomplete

The autocomplete script can be made persistent by adding the source line to `.zshrc` or `.bashrc`, with the fully qualified path used there.

There is no native binary for Windows. The README says to use the uberjar version, which requires Java 25+. It also shows Java 25+ in the repository badge, so an older Java runtime should not be assumed to work. The first real run against a local service is shown with an OpenAPI file and server URL:

cats --contract openapi.yml --server http://localhost:8080 --tui

This command asks CATS to fuzz the API described by `openapi.yml` at `http://localhost:8080` and opens the terminal interface. The README does not provide expected output text for a particular API, so the reader should use the TUI overview and generated reports to confirm that paths and fuzzers were selected. The README does not give a separate Windows launch command.

Reports, Replay, and Control in the TUI

CATS provides both an HTML report and terminal-oriented execution views. The README describes an HTML report containing test results, but it does not document report configuration flags or export formats. The TUI is more specific. It uses the same terminology as the CLI and HTML report, which reduces the need to translate result categories when investigating a failure.

Result categories include success, warnings, errors, and skipped tests. The TUI can filter the test list with `a`, `e`, `w`, `s`, and `i`. Those keys represent all, error, warning, successful, and skipped results. Operators can also press `/` to search across multiple test attributes, then select a test and press Enter. The detail view exposes the request and response, result, trace, and replay command, which gives a direct path from aggregate failure to manual inspection.

The TUI is deliberately constrained. It requires an interactive terminal at least 80 columns by 24 rows. It cannot be combined with `--dryRun`, and it is available for OpenAPI-backed fuzzing commands. The standalone `template` command continues to use normal CLI output. During an active run, pressing `q` requests cancellation. CATS then finishes the current test where possible, preserves results already written, and exits with status `130`. After execution finishes, `q` exits normally.

This cancellation behavior matters for long-running suites. A user does not necessarily receive a clean full-run exit when stopping early. The documented status is tied to the TUI cancellation path, so automation should not treat every `130` result as an ordinary completed fuzzing run without checking the execution context.

Configuration Scope and Practical Boundaries

CATS offers substantial control over generated tests, but the README does not document a complete configuration reference. Confirmed controls include Fuzzer selection, HTTP response-code filtering, HTTP method filtering, request-path filtering, business context, and the TUI result-detail limit. This configuration is useful when a broad contract scan creates noise, particularly for services with many internal paths or environment-specific endpoints.

The tool is most appropriate when the OpenAPI document is accurate and the target service is stable enough for generated requests to be interpreted. A stale or incomplete specification can produce misleading tests. For example, if the contract requires a field that the deployed API does not require, or if it omits a header that the service enforces, CATS can generate cases whose results do not represent the intended API behavior. The README's self-healing claim addresses specification changes in generation, not semantic validation of the contract.

CATS is also not a replacement for authorization testing, business-process testing, or precise endpoint assertions in every case. The README mentions business context and end-to-end functional test generation, but it does not specify how credentials, state transitions, or domain-specific invariants are modeled. Those behaviors require additional tooling or carefully written tests.

The Apache-2.0 license permits use and modification under its terms, subject to the license text. The repository information identifies the license but does not replace a legal review of obligations such as notices or distribution conditions.

CATS Compared with Scripted API Assertions

The main alternative is a handwritten or code-generated suite built around an HTTP client and assertions. Scripted tests usually encode a small number of exact requests and expected outcomes. That approach is precise for known defects, authentication flows, stateful workflows, and business rules that cannot be inferred from a schema. It also requires maintaining fixtures, request builders, and assertions as the API changes.

CATS takes the opposite approach for broad negative coverage. It reads the contract, derives many combinations of values and headers, applies scenario-specific expectations, and produces a large volume of results. The workflow is therefore closer to contract-driven fuzz generation than to a conventional unit-test suite. Its advantage is breadth across fields and scenarios with little hand-written test code. Its tradeoff is less direct authorship over every case and a greater need to interpret generated results.

Neither approach replaces the other cleanly. Scripted tests are the better fit when a request must exercise a known sequence or assert a domain rule. CATS is the better fit when the immediate concern is whether many endpoint fields reject boundary, malformed, or unexpected inputs consistently. In practice, the documented CATS workflow also points toward combining generated negative tests with targeted functional tests rather than treating the HTML report as the entire quality process.

Maintenance is relatively visible in the repository information. The repository is not archived, and its last push was on 2026-10-05. Recent releases include `cats-14.0.0`, `cats-13.8.0`, and `cats-13.7.0`. The README does not document a separate long-term support policy or a compatibility matrix for older contracts, so upgrade planning should focus on the release being selected.

Editorial conclusion

CATS fits teams with an OpenAPI contract and a repeatable REST endpoint test process. It is a poor fit for APIs without a usable contract, black-box targets with no reliable schema, or workflows that require narrowly scripted assertions. Verify first that Java 25 or a supported native binary is available, the contract represents deployed behavior, and the configured fuzzers and paths produce results that match the service's risk profile. The repository's last push was on 2026-10-05, and its most recent listed release is cats-14.0.0 from 2026-09-05.

Frequently asked questions

Official sources

1. Endava/cats on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases