DOCSEARCHbyAlgolia
Submit Docs

CATS OpenAPI Fuzzing Tool

website·Indexed 30 days ago

https://endava.github.io/cats/

A fuzzing tool for OpenAPI endpoints that generates tests based on configured Fuzzers to identify API vulnerabilities and inconsistencies. It features support for custom mutators, quality gates, reference data files, and a terminal interface (TUI) for interactive result inspection. CATS includes a wide range of built-in fuzzers for headers, HTTP response codes, and JSON bodies, and supports non-OpenAPI endpoints via TemplateFuzzer.

Tokens
72.4K
Snippets
208
Records
427
Agent score
75%

What's inside CATS

  1. Overview of CATS automated testing capabilities

    CATS is an automated testing tool that goes beyond standard fuzzing (random input generation). It generates negative testing scenarios based on data types and structural constraints. It is designed to automatically generate, execute, and report thousands of tests within minutes without requiring manual coding.

  2. Overview of the Temporal Logic Fields Fuzzer (TLF)

    The TemporalLogicFieldsFuzzer (Log Key: TLF) tests semantic temporal validation by injecting logically invalid date/time values into request payloads. Unlike syntactic validation tests, this fuzzer targets business logic vulnerabilities, such as:

    • Sending a startDate that occurs after an endDate.
    • Setting expiry dates in the past.
    • Providing future dates where only past values are permitted.

    It targets date and date-time fields (strings with temporal semantics) inferred from field names. The fuzzer is enabled by default. When a fuzzed field is required, optional, or does not match the field pattern, the expected server response is a 4XX error.

  3. Overview of the Security Fuzzer

    The SecurityFuzzer runs custom security payloads from a dictionary file against explicitly selected request targets. It creates one test for each selected target and dictionary value while preserving generated values for fields that are not being tested. It reports success based on the expectedResponseCode and optional verify assertions.

  4. Overview of CATS REST API Fuzzer

    CATS (Contract API Testing and Security) is a REST API fuzzer and negative testing tool designed for OpenAPI endpoints. It automatically generates, runs, and reports thousands of tests using over 140 pre-defined Fuzzers that cover boundary testing and negative scenarios (e.g., random large Unicode values, context-dependent values based on data types and constraints). Key features include comprehensive coverage of all request fields and headers, self-healing capabilities that automatically adapt to OpenAPI spec changes, and high configurability for filtering fuzzers, response codes, and request paths.

  5. Understand the Command Injection in String Fields Fuzzer (CIISF)

    The CommandInjectionInStringFieldsFuzzer (Log Key: CIISF) is enabled by default. It detects command injection vulnerabilities by sending OS command injection payloads into OpenAPI string fields. It analyzes server responses for evidence of unintended command execution, such as system command output, file contents, or environment information leakage.

    Operational Details:

    • Target Fields: OpenAPI type string.
    • Skipped Scenarios: The fuzzer is skipped if the request payload is empty, if no string fields are present, or if the HTTP method is HEAD or TRACE.
    • Expected Baseline: When a fuzzed field is required or does not match the field pattern, a 4XX response is expected.

  6. Use the RemoveFieldsFuzzer to test missing field handling

    The RemoveFieldsFuzzer (log key RF) tests how an API handles the removal of fields and subfields from a request. It is enabled by default and targets all field types.

    Expected Behavior:

    • If a required field is removed: The API should return a 4XX response.
    • If an optional field is removed: The API should return a 2XX response.

    Reporting Logic:

    • Error: Response is 404, response code is documented but unexpected, or an unexpected exception occurs.
    • Warning: Response code is expected and documented but doesn't match the schema, response code is expected but not documented, or response is 501.
    • Success: Response code is expected, documented, and matches the response schema.

  7. Understand how CATS generates and reports tests

    CATS generates tests using configured Fuzzers, where each Fuzzer targets a specific scenario with an expected result. The engine executes the scenario, retrieves the service response, and matches it against expectations to determine the report status:

    • info/success: Expected and documented behavior; no action required.
    • warn: Expected but undocumented behavior or misalignment between the contract and the service; should ideally be actioned.
    • error: Abnormal or unexpected behavior; must be actioned.

    CATS iterates through all endpoints, HTTP methods, request bodies, and parameters (including oneOf/anyOf combinations), fuzzing values based on their defined data types and constraints.

  9. Explain response codes and error reasons

    The cats explain command provides detailed information about specific fuzzers, mutators, response codes, or error reasons using the --type flag.
    # Explain a specific response code
cats explain --type response_code 953

# Explain a specific error reason
cats explain --type error_reason "Error details leak"

  10. Run OpenAPI fuzzing with the Terminal Interface (TUI)

    The --tui flag allows you to follow fuzzing progress and inspect results interactively. The TUI provides an overview of paths, run configuration, response times, response-code counts, and result counts. It requires an interactive terminal with a minimum size of 80 columns by 24 rows. Note that the TUI is only available for OpenAPI-backed fuzzing and cannot be used in combination with the --dryRun flag.
    cats -c openapi.yml -s http://localhost:8080 --tui

  11. Understand how CATS generates values without examples

    When no examples are provided in the OpenAPI specification, CATS automatically generates values based on the schema definition. It uses the type and format fields to determine the value range (e.g., type: integer and format: int32 results in a random integer between -2147483648 and 2147483647). Additionally, CATS includes built-in generators that produce realistic data for names, addresses, and emails based on the property name or format type.

  12. Use the Bidirectional Override Fields Fuzzer to detect Trojan Source ambiguities

    The BidirectionalOverrideFieldsFuzzer (Log Key: BOF) injects bidirectional-override Unicode control characters into string fields. This is used to detect Trojan Source–style ambiguities, log-forging issues, and UI or parsing inconsistencies where text is visually reordered while the original byte sequence is preserved.