diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 707a0fd79c1252..7be07374114354 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -64,6 +64,7 @@ argv armeabi ARMmbed armv +ASAN asdk AssertionError ASYNC @@ -143,6 +144,7 @@ capacitive CatalogVendorId CBB cbd +ccf CCMP CCS CCSTUDIO @@ -302,6 +304,7 @@ DevKitC DevKitM df dfu +DgDxsfHx dhclient DHCP DHCPC @@ -413,6 +416,7 @@ ffeebaefa FFF fffe fffff +fHtcwcAAAAAAAAAwQAAAAAAXPMlAAAAAAA Fi filepath fini @@ -429,6 +433,7 @@ fstab fsync ftd fullclean +fuzzer gbl gcloud GDB @@ -571,6 +576,7 @@ libdbus LIBDIR libegl libffi +libfuzzer libgirepository libglib libical @@ -1134,7 +1140,9 @@ WSTK xa xab xaver +xb xbef +xc xcd Xcode xcodeproj @@ -1143,6 +1151,7 @@ xd xdeadbeefcafe xds xdsdfu +xed xef xF xFFFF diff --git a/examples/all-clusters-app/linux/README.md b/examples/all-clusters-app/linux/README.md new file mode 100644 index 00000000000000..c7e72959cbc11b --- /dev/null +++ b/examples/all-clusters-app/linux/README.md @@ -0,0 +1,58 @@ +# Matter Linux/Mac All Clusters Example + +## Fuzzing integration + +This example supports compilation with libfuzzer enabled. + +### Compiling with fuzzing enabled + +To compile with libfuzzer enabled on Mac, run: + + $ ./scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target darwin-x64-all-clusters-no-ble-asan-libfuzzer build" + +at the top level of the Matter tree. + +Similarly, to compile on Linux run: + + $ ./scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target linux-x64-all-clusters-no-ble-asan-libfuzzer build" + +### Running libfuzzer-enabled binaries + +#### Initial run + +To run the resulting binary with no particular inputs do: + + $ ./out/darwin-x64-all-clusters-no-ble-asan-libfuzzer/chip-all-clusters-app-fuzzing + +or + + $ ./out/linux-x64-all-clusters-no-ble-asan-libfuzzer/chip-all-clusters-app-fuzzing + +If this crashes, it will output the input that caused the crash in a variety of +formats, looking something like this: + + 0xe,0x0,0xf1,0xb1,0xf1,0xf1,0xf1,0xf1,0xed,0x73,0x7,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0xc1,0x0,0x0,0x0,0x0,0x0,0x5c,0xf3,0x25,0x0,0x0,0x0,0x0,0x0, + \016\000\361\261\361\361\361\361\355s\007\000\000\000\000\000\000\000\301\000\000\000\000\000\\\363%\000\000\000\000\000 + artifact_prefix='./'; Test unit written to ./crash-c9fd2434ccf4a33a7f49765dcc519e1fd529a8e5 + Base64: DgDxsfHx8fHtcwcAAAAAAAAAwQAAAAAAXPMlAAAAAAA= + +Note that this creates a file holding the input that caused the crash. + +#### Run with a fixed input + +To run the binary with a specific input, place the input bytes in a file (which +a crashing run of the fuzzer does automatically). If `$(INPUT_FILE)` is the name +of that file, then run: + + $ ./out/darwin-x64-all-clusters-no-ble-asan-libfuzzer/chip-all-clusters-app-fuzzing $(INPUT_FILE) + +or + + $ ./out/linux-x64-all-clusters-no-ble-asan-libfuzzer/chip-all-clusters-app-fuzzing $(INPUT_FILE) + +#### Additional execution options. + +The binary can be run with `-help=1` to see more available options. + +Running with `ASAN_OPTIONS="handle_abort=2"` set in the environment may produce +nicer stack traces.