API Fuzzer

This project uses RESTler (from Microsoft) to fuzz the API.

Quick start

To get started with fuzzing, first make sure you have an API running locally:

cargo run -p aptos -- node run-local-testnet --with-faucet --faucet-port 8081 --force-restart --assume-yes

And ensure that you have Docker running on your system. Then, run the following commands from the root of aptos-core:

api/fuzzing/fuzz_api.py -d compile
api/fuzzing/fuzz_api.py -d test --suite lean

The second command here should tell you where to look for the output of the fuzzing run.

From here, it is probably good to get familiar with RESTler before going further. The README and this guide are good places to start.

Compiling

To fuzz with RESTler, it must first compile your OpenAPI spec. All the configuration that is used for this step is in the configs/ directory. Some notes about these configs:

• The paths referenced in the configs, e.g. CustomDictionaryFilePath in compiler_config.json refer to paths that we mount inside the container. You should not need to change these.
• The configuration generated by the compiler in Compile/ should not be modified. If you want to make changes to these, make changes to the files in configs/ instead.
• To understand compiler_config.json, see CompilerConfig.md.
• To understand fuzzing_dictionary.json, see FuzzingDictionary.md. The file in configs/ originally came from Compile/dict.json as output by the compile command with no additional configuration.
• To understand engine_settings.json, see SettingsFile.md.
• To see what checkers are available + what configuration settings they each offer, see Checkers.md

To see what this step did, check out the various files in Compile/. For example, in StdOut.txt you can see which types the compiler struggled with:

found unsupported format: hex
found unsupported format: uint64

This happens when using the default compiler (meaning, using none of the configs in configs/). Though note, this still happens today too: microsoft/restler-fuzzer#629.

You can verify the configured checkers exist by running --suite lean / full and then running this in the results output directory:

$ rg 'Checker: .*' | grep 'kicks in' | grep -o 'Checker: \w*' | sort -u
Checker: ExamplesChecker
Checker: InvalidDynamicObjectChecker
Checker: InvalidValueChecker
Checker: LeakageRuleChecker
Checker: PayloadBodyChecker
Checker: ResourceHierarchyChecker
Checker: UseAfterFreeChecker

This is necessary because RESTler won't tell you if you set an invalid checker is configured: microsoft/restler-fuzzer#628.

Fuzzing

Once you have compiled the spec to generate the grammar, configs, etc. you can fuzz the API like this:

api/fuzzing/fuzz_api.py -d test --suite lean

To discover more options, run the above with -h. There are other fuzzing options you can configure in configs/engine_settings.json, see parameters in SettingsFile.md such as fuzzing_mode.