diff options
Diffstat (limited to 'unicorn_mode')
| -rw-r--r-- | unicorn_mode/README.md | 45 | ||||
| -rw-r--r-- | unicorn_mode/samples/c/COMPILE.md | 3 | ||||
| -rw-r--r-- | unicorn_mode/samples/persistent/COMPILE.md | 4 | ||||
| -rw-r--r-- | unicorn_mode/samples/speedtest/README.md | 15 |
4 files changed, 37 insertions, 30 deletions
diff --git a/unicorn_mode/README.md b/unicorn_mode/README.md index d2b7d16f..ee4a7b22 100644 --- a/unicorn_mode/README.md +++ b/unicorn_mode/README.md @@ -8,10 +8,11 @@ The CompareCoverage and NeverZero counters features are by Andrea Fioraldi <andr ## 1) Introduction -The code in ./unicorn_mode allows you to build the (Unicorn Engine)[https://github.com/unicorn-engine/unicorn] with AFL support. +The code in ./unicorn_mode allows you to build the +(Unicorn Engine)[https://github.com/unicorn-engine/unicorn] with AFL++ support. This means, you can run anything that can be emulated in unicorn and obtain instrumentation -output for black-box, closed-source binary code snippets. This mechanism -can be then used by afl-fuzz to stress-test targets that couldn't be built +output for black-box, closed-source binary code snippets. This mechanism +can be then used by afl-fuzz to stress-test targets that couldn't be built with afl-cc or used in QEMU mode. There is a significant performance penalty compared to native AFL, @@ -25,7 +26,7 @@ For some pointers for more advanced emulation, take a look at [BaseSAFE](https:/ ### Building AFL++'s Unicorn Mode First, make AFL++ as usual. -Once that completes successfully you need to build and add in the Unicorn Mode +Once that completes successfully you need to build and add in the Unicorn Mode features: ``` @@ -33,10 +34,10 @@ cd unicorn_mode ./build_unicorn_support.sh ``` -NOTE: This script checks out a Unicorn Engine fork as submodule that has been tested -and is stable-ish, based on the unicorn engine `next` branch. +NOTE: This script checks out a Unicorn Engine fork as submodule that has been tested +and is stable-ish, based on the unicorn engine `next` branch. -Building Unicorn will take a little bit (~5-10 minutes). Once it completes +Building Unicorn will take a little bit (~5-10 minutes). Once it completes it automatically compiles a sample application and verifies that it works. ### Fuzzing with Unicorn Mode @@ -46,25 +47,24 @@ To use unicorn-mode effectively you need to prepare the following: * Relevant binary code to be fuzzed * Knowledge of the memory map and good starting state * Folder containing sample inputs to start fuzzing with - + Same ideas as any other AFL inputs - + Quality/speed of results will depend greatly on the quality of starting + + Same ideas as any other AFL++ inputs + + Quality/speed of results will depend greatly on the quality of starting samples + See AFL's guidance on how to create a sample corpus * Unicornafl-based test harness in Rust, C, or Python, which: + Adds memory map regions - + Loads binary code into memory + + Loads binary code into memory + Calls uc.afl_fuzz() / uc.afl_start_forkserver + Loads and verifies data to fuzz from a command-line specified file - + AFL will provide mutated inputs by changing the file passed to + + AFL++ will provide mutated inputs by changing the file passed to the test harness + Presumably the data to be fuzzed is at a fixed buffer address - + If input constraints (size, invalid bytes, etc.) are known they - should be checked in the place_input handler. If a constraint - fails, just return false from the handler. AFL will treat the input as - 'uninteresting' and move on. + + If input constraints (size, invalid bytes, etc.) are known they + should be checked in the place_input handler. If a constraint + fails, just return false from the handler. AFL++ will treat the input as 'uninteresting' and move on. + Sets up registers and memory state for beginning of test + Emulates the interesting code from beginning to end - + If a crash is detected, the test harness must 'crash' by + + If a crash is detected, the test harness must 'crash' by throwing a signal (SIGSEGV, SIGKILL, SIGABORT, etc.), or indicate a crash in the crash validation callback. Once you have all those things ready to go you just need to run afl-fuzz in @@ -77,14 +77,13 @@ afl-fuzz -U -m none -i /path/to/inputs -o /path/to/results -- ./test_harness @@ The normal afl-fuzz command line format applies to everything here. Refer to AFL's main documentation for more info about how to use afl-fuzz effectively. -For a much clearer vision of what all of this looks like, please refer to the -sample provided in the 'unicorn_mode/samples' directory. There is also a blog -post that uses slightly older concepts, but describes the general ideas, at: +For a much clearer vision of what all of this looks like, refer to the sample +provided in the 'unicorn_mode/samples' directory. There is also a blog post that +uses slightly older concepts, but describes the general ideas, at: [https://medium.com/@njvoss299/afl-unicorn-fuzzing-arbitrary-binary-code-563ca28936bf](https://medium.com/@njvoss299/afl-unicorn-fuzzing-arbitrary-binary-code-563ca28936bf) - -The ['helper_scripts'](./helper_scripts) directory also contains several helper scripts that allow you +The ['helper_scripts'](./helper_scripts) directory also contains several helper scripts that allow you to dump context from a running process, load it, and hook heap allocations. For details on how to use this check out the follow-up blog post to the one linked above. @@ -105,8 +104,8 @@ Comparison instructions are currently instrumented only for the x86, x86_64 and ## 4) Gotchas, feedback, bugs -Running the build script builds Unicornafl and its python bindings and installs -them on your system. +Running the build script builds Unicornafl and its python bindings and installs +them on your system. This installation will leave any existing Unicorn installations untouched. If you want to use unicornafl instead of unicorn in a script, replace all `unicorn` imports with `unicornafl` inputs, everything else should "just work". diff --git a/unicorn_mode/samples/c/COMPILE.md b/unicorn_mode/samples/c/COMPILE.md index 7da140f7..e5265071 100644 --- a/unicorn_mode/samples/c/COMPILE.md +++ b/unicorn_mode/samples/c/COMPILE.md @@ -6,6 +6,7 @@ This shows a simple harness for unicornafl in C The target can be built using the `make` command. Just make sure you have built unicorn support first: + ```bash cd /path/to/afl/unicorn_mode ./build_unicorn_support.sh @@ -19,4 +20,4 @@ was built in case you want to rebuild it or recompile it for any reason. The pre-built binary (persistent_target_x86_64) was built using -g -O0 in gcc. -We then load the binary and execute the main function directly. +Then load the binary and execute the main function directly. diff --git a/unicorn_mode/samples/persistent/COMPILE.md b/unicorn_mode/samples/persistent/COMPILE.md index 9f2ae718..5e607aef 100644 --- a/unicorn_mode/samples/persistent/COMPILE.md +++ b/unicorn_mode/samples/persistent/COMPILE.md @@ -3,7 +3,7 @@ This shows a simple persistent harness for unicornafl in C. In contrast to the normal c harness, this harness manually resets the unicorn state on each new input. -Thanks to this, we can rerun the test case in unicorn multiple times, without +Thanks to this, you can rerun the test case in unicorn multiple times, without the need to fork again. ## Compiling sample.c @@ -25,4 +25,4 @@ was built in case you want to rebuild it or recompile it for any reason. The pre-built binary (persistent_target_x86_64.bin) was built using -g -O0 in gcc. -We then load the binary and we execute the main function directly. \ No newline at end of file +Then load the binary and execute the main function directly. \ No newline at end of file diff --git a/unicorn_mode/samples/speedtest/README.md b/unicorn_mode/samples/speedtest/README.md index 3c1184a2..bd5ba8d0 100644 --- a/unicorn_mode/samples/speedtest/README.md +++ b/unicorn_mode/samples/speedtest/README.md @@ -35,7 +35,6 @@ cd python TODO: add results here. - ## Compiling speedtest_target.c You shouldn't need to compile simple_target.c since a X86_64 binary version is @@ -44,22 +43,30 @@ was built in case you want to rebuild it or recompile it for any reason. The pre-built binary (simple_target_x86_64.bin) was built using -g -O0 in gcc. -We then load the binary and execute the main function directly. +Then load the binary and execute the main function directly. + +## Addresses for the harness -## Addresses for the harness: To find the address (in hex) of main, run: + ```bash objdump -M intel -D target | grep '<main>:' | cut -d" " -f1 ``` + To find all call sites to magicfn, run: + ```bash objdump -M intel -D target | grep '<magicfn>$' | cut -d":" -f1 ``` + For malloc callsites: + ```bash objdump -M intel -D target | grep '<malloc@plt>$' | cut -d":" -f1 ``` + And free callsites: + ```bash objdump -M intel -D target | grep '<free@plt>$' | cut -d":" -f1 -``` +``` \ No newline at end of file |