mirror of
https://github.com/AFLplusplus/AFLplusplus.git
synced 2025-06-08 00:01:33 +00:00
125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
# Unicorn-based binary-only instrumentation for afl-fuzz
|
|
|
|
The idea and much of the original implementation comes from Nathan Voss <njvoss299@gmail.com>.
|
|
|
|
The port to afl++ is by Dominik Maier <mail@dmnk.co>.
|
|
|
|
The CompareCoverage and NeverZero counters features are by Andrea Fioraldi <andreafioraldi@gmail.com>.
|
|
|
|
## 1) Introduction
|
|
|
|
The code in ./unicorn_mode allows you to build a standalone feature that
|
|
leverages the Unicorn Engine and allows callers to 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
|
|
with afl-gcc or used in QEMU mode, or with other extensions such as
|
|
TriforceAFL.
|
|
|
|
There is a significant performance penalty compared to native AFL,
|
|
but at least we're able to use AFL++ on these binaries, right?
|
|
|
|
## 2) How to use
|
|
|
|
Requirements: you need an installed python environment.
|
|
|
|
### Building AFL++'s Unicorn Mode
|
|
|
|
First, make afl++ as usual.
|
|
Once that completes successfully you need to build and add in the Unicorn Mode
|
|
features:
|
|
|
|
```
|
|
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 master.
|
|
|
|
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
|
|
|
|
To really 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 quality of starting
|
|
samples
|
|
+ See AFL's guidance on how to create a sample corpus
|
|
* Unicornafl-based test harness which:
|
|
+ Adds memory map regions
|
|
+ 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
|
|
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 after the file is loaded. If a constraint
|
|
fails, just exit the test harness. AFL will treat the input as
|
|
'uninteresting' and move on.
|
|
+ Sets up registers and memory state for beginning of test
|
|
+ Emulates the interested code from beginning to end
|
|
+ If a crash is detected, the test harness must 'crash' by
|
|
throwing a signal (SIGSEGV, SIGKILL, SIGABORT, etc.)
|
|
|
|
Once you have all those things ready to go you just need to run afl-fuzz in
|
|
'unicorn-mode' by passing in the '-U' flag:
|
|
|
|
```
|
|
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 goes over the basics 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' 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.
|
|
|
|
A example use of AFL-Unicorn mode is discussed in the paper Unicorefuzz:
|
|
[https://www.usenix.org/conference/woot19/presentation/maier](https://www.usenix.org/conference/woot19/presentation/maier)
|
|
|
|
## 3) Options
|
|
|
|
As for the QEMU-based instrumentation, the afl-unicorn twist of afl++
|
|
comes with a sub-instruction based instrumentation similar in purpose to laf-intel.
|
|
|
|
The options that enable Unicorn CompareCoverage are the same used for QEMU.
|
|
AFL_COMPCOV_LEVEL=1 is to instrument comparisons with only immediate values.
|
|
|
|
AFL_COMPCOV_LEVEL=2 instruments all comparison instructions.
|
|
|
|
Comparison instructions are currently instrumented only for the x86, x86_64 and ARM targets.
|
|
|
|
## 4) Gotchas, feedback, bugs
|
|
|
|
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:
|
|
|
|
```python
|
|
import unicornafl
|
|
unicornafl.monkeypatch()
|
|
```
|
|
|
|
This will replace all unicorn imports with unicornafl inputs.
|
|
|
|
Refer to the [samples/arm_example/arm_tester.c](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
|
|
load any mutated inputs and your fuzzing will be useless!
|