Introduction
CATS (Contract API Testing and Security) is an autonomous REST API fuzzer, negative testing engine, and declarative functional testing tool. Give CATS an OpenAPI specification and a target URL, and it automatically generates, executes, and triages thousands of self-healing boundary, type-coercion, OWASP security, and multi-step workflow tests—without writing a single line of test code.
Run CATS only against local, staging, or dedicated test environments. Because CATS actively mutates payloads, exercises resource lifecycles (POST, PUT, PATCH, DELETE), and probes boundary and injection conditions, running it against production systems can modify state or degrade performance.
Quickstart
Make sure CATS is installed (Installation Guide):
brew tap endava/tap && brew install cats
1. Analyze Readiness & Smoke-Probe the API
Inspect the contract's 0–100 Fuzzability Readiness Score and producer-to-consumer resource chains offline, then send a single HappyPath request per operation (skipping DELETE by default) to confirm connectivity and authentication:
export API_AUTH='Bearer eyJ...'
cats analyze -c openapi.yml
cats smoke -c openapi.yml -s https://api.example.com -H 'Authorization=$$API_AUTH'
(Header values set to $$VAR are resolved from environment variables or .env and automatically masked in logs and HTML/JSON reports. Single-quote $$ in shells so bash does not expand it.)
2. Fuzz the API
Choose the depth that matches your workflow:
# Curated CI or OWASP Security profile with stateful resource correlation and breadth-first waves (enabled by default)
cats -c openapi.yml -s https://api.example.com -H 'Authorization=$$API_AUTH' --profile ci
cats -c openapi.yml -s https://api.example.com -H 'Authorization=$$API_AUTH' --profile security
# Full contract-aware suite (all active Field, Header, and HTTP fuzzers)
cats -c openapi.yml -s https://api.example.com -H 'Authorization=$$API_AUTH'
# Blackbox crash hunting: report only 5XX server errors
cats -c openapi.yml -s https://api.example.com -H 'Authorization=$$API_AUTH' -b
Open cats-report/index.html to inspect the interactive HTML report, or pass --tui to follow execution live in the terminal.
3. Run Stateful Functional Flows
Write multi-step CRUD workflows, cross-field rules, polling checks, and data-driven scenarios in minimal steps: YAML—CATS generates the rest of every request from your contract:
cats run -c openapi.yml -s https://api.example.com -H 'Authorization=$$API_AUTH' flow.yml
4. Triage Failures & Verify Fixes
Cluster failing tests by root cause, auto-generate remediation files (refData.yml, correlations.yml, reproducers.sh), and verify fixes live against the server:
cats triage -r cats-report -c openapi.yml \
--export-refdata refData.yml \
--export-correlations correlations.yml \
--export-reproducers reproducers.sh
# Replay 1 representative request per root-cause cluster to confirm FIXED vs STILL_FAILING
cats triage -r cats-report --verify -s https://api.example.com -H 'Authorization=$$API_AUTH'
What CATS Covers
| Capability | Scope | Where to Learn More |
|---|---|---|
Field Fuzzers (125) | Numeric/string boundaries, exclusiveMinimum/Maximum, multipleOf, minItems/maxItems, minProperties, const/not, merged oneOf branches, type coercion (NaN/Infinity), cross-field business logic (confirmation fields, mutually exclusive fields, arithmetic totals, path-vs-body IDs), search/filter & cursor tokens, timezone/locale/ISO codes, SQL/NoSQL/LDAP/Command/SSTI/XXE/XSS/SSRF/Path Traversal injections, readOnly & undeclared Mass Assignment, HTTP Parameter Pollution, and Unicode edge cases. | Field Fuzzers |
Header Fuzzers (39) | Content negotiation (Accept, Content-Type), Content-Length/Transfer-Encoding, CRLF injection, security headers, duplicate/extra headers, and Unicode/control-character header mutations. | Header Fuzzers |
HTTP Fuzzers (37) | HappyPath, authentication bypass, BOLA/IDOR, HTTP verb tampering & method-override tunneling (X-HTTP-Method-Override), Idempotency-Key conflict detection, PUT idempotency, partial PATCH omitted-field preservation, GET pagination limit enforcement, ETag preconditions, cross-parent isolation, and post-delete availability. | HTTP Fuzzers |
| Stateful Functional Flows | Declarative steps: YAML workflows with schema-backed payload generation, cross-step $steps / save correlation, expect.that assertions, poll / delayMs async helpers, repeat, forEach data tables, and correlate rules. | Functional Flow Fuzzer |
| Continuous & Spec-less Fuzzing | Time- or count-bounded mutation fuzzing with 36 built-in mutators (cats random), custom dictionary fuzzing (SecurityFuzzer), and template-based fuzzing without an OpenAPI spec (cats template). | Mutators · Template Fuzzer |
Contract Linters (58) | Offline OpenAPI 3.0/3.1 structural, semantic, and REST naming checks: ambiguous oneOf variants, default/example schema conformance, contradictory bounds, request/response symmetry, pagination & error consistency, and REST path role analysis. | Contract Linters |
Choosing a Command
| Goal | Command |
|---|---|
| Score contract readiness & view producer-consumer resource chains | cats analyze -c openapi.yml --mermaid |
Scaffold starter headers.yml, refData.yml, and functionalTests.yml | cats init -c openapi.yml |
| Install CATS skills for Devin, Claude Code, Codex, OpenCode, or Cursor | cats init --skills |
| Verify server reachability and auth (1 request per endpoint) | cats smoke -c openapi.yml -s http://localhost:8080 |
| Run fast PR/CI fuzzing suite | cats -c openapi.yml -s http://localhost:8080 --profile ci |
| Run OWASP API Security Top 10 audit | cats -c openapi.yml -s http://localhost:8080 --profile security |
| Execute stateful YAML functional or security flows | cats run -c openapi.yml -s http://localhost:8080 flow.yml |
| Cluster report failures & verify fixes live | cats triage -r cats-report --verify -s http://localhost:8080 |
Replay a test with its upstream 2XX producer chain | cats replay Test42 --stateful |
Export a failing test + producer chain as a runnable steps: flow | cats replay Test42 --export-flow reproducer.yml |
| Gate CI against a previous baseline report | cats compare -b ./baseline-report -t ./cats-report |
| Lint OpenAPI contract offline | cats lint -c openapi.yml --strict |
| Explain any fuzzer, linter, profile, mutator, or error reason | cats explain --type fuzzer ReadOnlyFieldsMassAssignment |