Merge pull request #1259 from dmell/unicorn_docs

Adjustments to unicorn docs and speedtest sample

4 files changed, 23 insertions, 55 deletions

diff --git a/unicorn_mode/README.md b/unicorn_mode/README.md
index 0f28cf96..392a3254 100644
--- a/unicorn_mode/README.md
+++ b/unicorn_mode/README.md
@@ -9,7 +9,7 @@ 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.
+[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
@@ -62,7 +62,7 @@ To use unicorn-mode effectively you need to prepare the following:
 			+ 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
+		+ Sets up registers and memory state to start testing
 		+ Emulates the interesting code from beginning to end
 		+ 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.
@@ -104,7 +104,7 @@ 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
+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,
@@ -119,18 +119,18 @@ unicornafl.monkeypatch()
 
 This will replace all unicorn imports with unicornafl inputs.
 
-5) Examples
+## 5) Examples
 
-Apart from reading the documentation in `afl.c` and the python bindings of unicornafl, the best documentation are the [samples/](./samples).
+Apart from reading the documentation in `afl.c` and the Python bindings of unicornafl, the best documentation are the [samples/](./samples).
 The following examples exist at the time of writing:
 
-- c: A simple example how to use the c bindings
-- compcov_x64: A python example that uses compcov to traverse hard-to-reach blocks
-- persistent: A c example using persistent mode for maximum speed, and resetting the target state between each iteration
-- simple: A simple python example
-- speedtest/c: The c harness for an example target, used to compare c, python, and rust bindings and fix speed issues
-- speedtest/python: Fuzzing the same target in python
-- speedtest/rust: Fuzzing the same target using a rust harness
+- c: A simple example on how to use the C bindings
+- compcov_x64: A Python example that uses compcov to traverse hard-to-reach blocks
+- persistent: A C example using persistent mode for maximum speed, and resetting the target state between each iteration
+- simple: A simple Python example
+- speedtest/c: The C harness for an example target, used to compare C, Python, and Rust bindings and fix speed issues
+- speedtest/python: Fuzzing the same target in Python
+- speedtest/rust: Fuzzing the same target using a Rust harness
 
 Usually, the place to look at is the `harness` in each folder. The source code in each harness is pretty well documented.
 Most harnesses also have the `afl-fuzz` commandline, or even offer a `make fuzz` Makefile target.
diff --git a/unicorn_mode/samples/speedtest/README.md b/unicorn_mode/samples/speedtest/README.md
index bd5ba8d0..f46a5772 100644
--- a/unicorn_mode/samples/speedtest/README.md
+++ b/unicorn_mode/samples/speedtest/README.md
@@ -5,7 +5,11 @@ to show the raw speed of C, Rust, and Python harnesses.
 
 ## Compiling...
 
-Make sure, you built unicornafl first (`../../build_unicorn_support.sh`).
+Make sure you built unicornafl first (`../../build_unicorn_support.sh`).
+Build the target using the provided Makefile.
+This will also run the [./get_offsets.py](./get_offsets.py) script,
+which finds some relevant addresses in the target binary using `objdump`,
+and dumps them to different files.
 Then, follow these individual steps:
 
 ### Rust
@@ -13,7 +17,7 @@ Then, follow these individual steps:
 ```bash
 cd rust
 cargo build --release
-../../../afl-fuzz -i ../sample_inputs -o out -- ./target/release/harness @@
+../../../../afl-fuzz -i ../sample_inputs -o out -U -- ./target/release/harness @@
 ```
 
 ### C
@@ -21,52 +25,16 @@ cargo build --release
 ```bash
 cd c
 make
-../../../afl-fuzz -i ../sample_inputs -o out -- ./harness @@
+../../../../afl-fuzz -i ../sample_inputs -o out -U -- ./harness @@
 ```
 
 ### python
 
 ```bash
 cd python
-../../../afl-fuzz -i ../sample_inputs -o out -U -- python3 ./harness.py @@
+../../../../afl-fuzz -i ../sample_inputs -o out -U -- python3 ./harness.py @@
 ```
 
 ## Results
 
 TODO: add results here.
-
-## Compiling speedtest_target.c
-
-You shouldn't need to compile simple_target.c since a X86_64 binary version is
-pre-built and shipped in this sample folder. This file documents how the binary
-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.
-
-Then load the binary and execute the main function directly.
-
-## 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
diff --git a/unicorn_mode/samples/speedtest/c/harness.c b/unicorn_mode/samples/speedtest/c/harness.c
index e8de3d80..9eb05257 100644
--- a/unicorn_mode/samples/speedtest/c/harness.c
+++ b/unicorn_mode/samples/speedtest/c/harness.c
@@ -8,9 +8,9 @@
 
    Run under AFL as follows:
 
-   $ cd <afl_path>/unicorn_mode/samples/simple/
+   $ cd <afl_path>/unicorn_mode/samples/speedtest/c
    $ make
-   $ ../../../afl-fuzz -m none -i sample_inputs -o out -- ./harness @@
+   $ ../../../../afl-fuzz -i ../sample_inputs -o out -U -- ./harness @@
 */
 
 // This is not your everyday Unicorn.
diff --git a/unicorn_mode/samples/speedtest/rust/Cargo.toml b/unicorn_mode/samples/speedtest/rust/Cargo.toml
index 9b81be0b..766b2f27 100644
--- a/unicorn_mode/samples/speedtest/rust/Cargo.toml
+++ b/unicorn_mode/samples/speedtest/rust/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "unicornafl_harness"
+name = "harness"
 version = "0.1.0"
 authors = ["Dominik Maier <domenukk@gmail.com>"]
 edition = "2018"