Skip to main content

Mutators

Mutators are the fuzzers used by continuous fuzzing. You can list the built-in mutators using cats list --mutators sub-command. Mutators are using more randomness than typical fuzzers. They either generate data on the fly or randomly select from a larger set. They also don't take into consideration data types, constraints, boundaries, etc.

Custom Mutators​

You can also define your own mutators using a simple syntax. A custom mutator is a yaml file with the following syntax:

name: xss mutator
type: replace
values:
  - "<script>"
  - "alert(1)"
  - "console.log('hack')"

where:

  • name is the mutator name
  • type is one of TRAIL, INSERT, PREFIX, REPLACE, REPLACE_BODY, IN_BODY
  • values an array of possible values that will be used by the mutator for random selection

If values is a simple string (not an array as above) it will be interpreted as a file location and try to load the fuzz values from that file. An example:

name: xss mutator from file
type: replace
values: /my/full/path/to/xss.txt

CATS will load all values from /my/full/path/to/xss.txt and randomly select when fuzzing.

caution

The path to the file with fuzz values must be relative to where you run CATS from, not the location where the custom fuzzer file is. Or you can use an absolute path.

This is what each type means:

  • trail will trail a valid field value with the one generated by the mutator
  • insert will insert the generated mutator value inside a field valid value
  • prefix will prefix a valid field value with the one generated by the mutator
  • replace will replace a valid field value with the one generated by the mutator
  • replace_body will replace the entire request body with the value generated by the mutator
  • in_body will insert the value generated by the mutator inside the request body

Mutators must be grouped in a common folder. This is how you can supply a custom mutators location:

cats random --contract=openapi.yaml --server=http://localhost:8080 -H "API-KEY=$token" --mc 500 --path "/users/auth" -X POST -stopAfterTimeInSec 10 --mutators "./mutators"

./mutators must contain valid custom mutators files.

caution

Only one mutator is allowed per file.