From 49c9b68e4e69654c09c8a2ce4e4d86a02411fc96 Mon Sep 17 00:00:00 2001 From: Dominik Maier Date: Sun, 15 Dec 2019 05:03:32 +0100 Subject: Moved unicorn_mode to unicornafl --- unicorn_mode/README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'unicorn_mode/README.md') diff --git a/unicorn_mode/README.md b/unicorn_mode/README.md index 8f381b59..904ea624 100644 --- a/unicorn_mode/README.md +++ b/unicorn_mode/README.md @@ -20,7 +20,7 @@ but at least we're able to use AFL on these binaries, right? ## 2) How to use -Requirements: you need an installed python2 environment. +Requirements: you need an installed python environment. ### Building AFL's Unicorn Mode @@ -31,11 +31,8 @@ features: $ cd unicorn_mode $ ./build_unicorn_support.sh -NOTE: This script downloads a Unicorn Engine commit that has been tested -and is stable-ish from the Unicorn github page. If you are offline, you'll need -to hack up this script a little bit and supply your own copy of Unicorn's latest -stable release. It's not very hard, just check out the beginning of the -build_unicorn_support.sh script and adjust as necessary. +NOTE: This script checks out a Unicorn Engine fork as submodule that has been tested +and is stable-ish, based on the unicorn engine master. Building Unicorn will take a little bit (~5-10 minutes). Once it completes it automatically compiles a sample application and verify that it works. @@ -51,11 +48,10 @@ To really use unicorn-mode effectively you need to prepare the following: + Quality/speed of results will depend greatly on quality of starting samples + See AFL's guidance on how to create a sample corpus - * Unicorn-based test harness which: + * Unicornafl-based test harness which: + Adds memory map regions + Loads binary code into memory - + Emulates at least one instruction* - + Yeah, this is lame. See 'Gotchas' section below for more info + + 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 the test harness @@ -103,16 +99,20 @@ for the x86, x86_64 and ARM targets. ## 4) Gotchas, feedback, bugs -To make sure that AFL's fork server starts up correctly the Unicorn test -harness script must emulate at least one instruction before loading the -data that will be fuzzed from the input file. It doesn't matter what the -instruction is, nor if it is valid. This is an artifact of how the fork-server -is started and could likely be fixed with some clever re-arranging of the -patches applied to Unicorn. +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". +If you use 3rd party code depending on unicorn, you can use unicornafl monkeypatching: +Before importing anything that depends on unicorn, do: -Running the build script builds Unicorn and its python bindings and installs -them on your system. This installation will supersede any existing Unicorn -installation with the patched afl-unicorn version. +```python +import unicornafl +unicornafl.monkeypatch() +``` + +This will replace all unicorn imports with unicornafl inputs. Refer to the unicorn_mode/samples/arm_example/arm_tester.c for an example of how to do this properly! If you don't get this right, AFL will not -- cgit 1.4.1