Security Fuzzer

Item	Description
Full Fuzzer Name	SecurityFuzzer
Log Key	N/A; test identifiers and scenarios from the input file identify executions.
Description	Runs custom security payloads from a dictionary against explicitly selected request targets.
Enabled by default?	No. Enable it with cats run <security-fuzzer-file>.
Target fields	targetFields, targetFieldTypes, HTTP headers, or the entire request body as configured in the YAML file.
Expected result	The expectedResponseCode supplied for each test case; security tests commonly expect 4XX or a context-specific 2XX.
Fuzzing logic	Creates one test for each selected target and dictionary value while preserving generated values for fields that are not tested.
Conditions when this fuzzer will be skipped	When no security fuzzer file is supplied, a path has no matching configuration, or no target is selected.
HTTP methods that will be skipped	Methods excluded by the test file or unavailable on the selected OpenAPI path.
Reporting	Reports results against each test's configured response-code expectation and optional verify assertions.

You can use CATS with your own dictionary by fuzzing specific fields with different sets of nasty strings. The behaviour is similar to the FunctionalFuzzer using cats run <file-name> sub-command. You can use the exact same elements for output variables, test correlation, verify responses and so forth, with the addition that you must also specify a targetFields and/or targetFieldTypes and a stringsList element. A typical SecurityFuzzer file will look like this:

/pet:
    test_1:
      description: Run XSS scenarios
      name: "My Pet"
      expectedResponseCode: 200
      httpMethod: all
      targetFields:
        - pet#id
        - pet#description
      stringsFile: xss.txt

And a typical run:

cats run securityFuzzerFile.yml -c contract.yml -s http://localhost:8080

You can also supply output, httpMethod, oneOfSelection and/or verify (with the same behaviour as within the FunctionalFuzzer) if they are relevant to your case.

The file uses Json path syntax for all the properties you can supply; you must separate elements through # as in the example instead of ..

This is what the SecurityFuzzer will do after parsing the above SecurityFuzzer file:

• it will add the fixed value "My Pet" to all the request for the field name (act as a reference data)
• for each field specified in the targetFields i.e. pet#id and pet#description it will create a test for each line from the xss.txt file
• if you consider the xss.txt sample file included in the CATS repo, this means that it will send 21 requests targeting pet#id and 21 requests targeting pet#description i.e. a total of 42 tests
• for each of these 42 tests, the SecurityFuzzer will expect a 200 response code (i.e. will report the match as a success). If another response code is returned, then CATS will report the test as error.

info

It was a deliberate choice to not include all fields by default.

If you want the above logic to apply to all paths, you can use all as the path name:

all:
    test_1:
      description: Run XSS scenarios
      name: "My Pet"
      expectedResponseCode: 200
      httpMethod: all
      targetFields:
        - pet#id
        - pet#description
      stringsFile: xss.txt

When using this fuzzer you must explicitly specify what is the target of fuzzing. You have multiple options.

Targeting specific fields

You can target specific fields using the targetFields element:

all:
    test_1:
      description: Run XSS scenarios on specific fields
      name: "My Pet"
      expectedResponseCode: 200
      httpMethod: all
      targetFields:
        - pet#id
        - pet#description
      stringsFile: xss.txt

This will iterate through all fields mentioned in the targetFields elements and replace their value with each line from the xss.txt file.

Targeting specific field types

You can target specific fields using the targetFieldTypes element and specifying the OpenAPI type you are willing to fuzz.

all:
    test_1:
      description: Run XSS scenarios on string fields
      name: "My Pet"
      expectedResponseCode: 200
      httpMethod: all
      targetFieldTypes:
        - string
      stringsFile: xss.txt

This will iterate through all the string fields and replace their values with each line from the xss.txt file.

Targeting http headers

You can target HTTP headers using the targetFieldTypes element and specifying the http_headers keyword.

all:
    test_1:
      description: Run XSS scenarios on http headers
      name: "My Pet"
      expectedResponseCode: 200
      httpMethod: all
      targetFieldTypes:
        - http_headers
      stringsFile: xss.txt

This will iterate through all http headers and replace their values with each line from the xss.txt file.

Targeting the entire http request body

You can target the entire http request body (i.e. replace it entirely with another payload) using the targetFieldTypes element and specifying the http_body keyword:

all:
    test_1:
      description: Run XSS scenarios on http body
      name: "My Pet"
      expectedResponseCode: 200
      httpMethod: all
      targetFieldTypes:
        - http_body
      stringsFile: xss.txt

This will cycle the entire http request body and replace it with each line from the xss.txt file.

tip

You can split the nasty strings into multiple files. You can have a sql_injection.txt, a xss.txt, a command_injection.txt and so on. For each of these files, you can create a test entry in the SecurityFuzzer file where you target the fields that are relevant. The expectedResponseCode should be tweaked according to your particular context. Your service might sanitize data before validation, so might be perfectly valid to expect a 200 or might validate the fields directly, so might be perfectly valid to expect a 400. A 500 will usually mean something was not handled properly and might signal a possible bug.

Working with additionalProperties in SecurityFuzzer

You can also set additionalProperties fields through the functionalFuzzerFile using the same syntax as for Setting additionalProperties in Reference Data.

SecurityFuzzer Reserved keywords

The following keywords are reserved in SecurityFuzzer tests: output, expectedResponseCode, httpMethod, description, verify, oneOfSelection, targetFields, targetFieldTypes, stringsFile, checkBoolean, additionalProperties, topElement and mapValues.