diff --git a/README.md b/README.md
index 84110ad3d62152fbd59bd7ba99d3c69b89ebf964..960c78aea3a3ac9324c52ec691fccf5fa22ed851 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,3 @@
-
# ZAFL: Zipr-based AFL
Welcome to **ZAFL**: a project to extend compiler-quality instrumentation speed *and* transformation support to the fuzzing of x86-64 binary programs. The key features of ZAFL include:
* Fast, space-efficient, and inlined binary fuzzing instrumentation via the Zipr binary rewriting infrastructure.
@@ -9,7 +8,7 @@ Welcome to **ZAFL**: a project to extend compiler-quality instrumentation speed
<tr><td><b>Citing this repository:</b></td>
<td><code class="rich-diff-level-one">@inproceedings{nagy:breakingthrough, title = {Breaking Through Binaries: Compiler-quality Instrumentation for Better Binary-only Fuzzing}, author = {Stefan Nagy and Anh Nguyen-Tuong and Jason D. Hiser and Jack W. Davidson and Matthew Hicks}, booktitle = {{USENIX} Security Symposium (USENIX)}, year = {2021},}</code></td></tr>
<tr><td><b>License:</b></td><td><a href="https://git.zephyr-software.com/opensrc/zafl/-/blob/master/LICENSE">BSD 3-Clause License</a></td></tr>
- <tr><td><b>Disclaimer:</b></td><td><i>This software is strictly a research prototype.</i></td></tr></table>
+ <tr><td><b>Disclaimer:</b></td><td><i>This software is provided as-is with no warranty.</i></td></tr></table>
## Prerequisites
* **Install environment**: ZAFL's installation currently supports recent 64-bit Linux environments (i.e., Ubuntu 16.04 and up).
@@ -24,13 +23,16 @@ To install the Docker-based installation, please see the [install and use direct
Installing from source is recommended only for those intending to bug-fix or develop new features for ZAFL. **The following instructions assume you are running a compatible Linux environment** (i.e., Ubuntu 16.04 and up) **with AFL installed**.
#### Step 0: Install the Zipr binary rewriting infrastructure
-See directions for this at https://git.zephyr-software.com/opensrc/zipr
+See https://git.zephyr-software.com/opensrc/zipr.
+Before continuing, be sure to prepare Zipr's environment by doing the following:
+```bash
+cd /path/to/zipr && . set_env_vars
+```
#### Step 1: Testing Zipr
-Test the binary rewriting infrastructure by rewriting /bin/ls
+Test the binary rewriting infrastructure by rewriting Linux's `ls` binary:
```bash
-cd /tmp
-$PSZ /bin/ls ls.zipr -c rida
+$PSZ /bin/ls /tmp/ls.zipr -c rida
```
Your terminal's output should look like this:
```
@@ -46,30 +48,21 @@ Performing step fix_calls [dependencies=mandatory] ...Done. Successful.
Program not detected in signature database.
Performing step zipr [dependencies=clone,fill_in_indtargs,fill_in_cfg,pdb_register] ...Done. Successful.
```
-Invoke the rewritten version of /bin/ls and make sure it runs normally:
+Invoke the rewritten version and make sure it runs normally:
```
-./ls.zipr
+./tmp/ls.zipr
```
-#### Step 2: Download and set environment for IRDB-SDK and IRDB-libs
-**Option 1 (recommended)**: If you built Zipr from source, run its `set_env_vars` to prepare the environment.
-**Option 2**: Manually download and configure the SDK:
-```bash
-git clone --recurse-submodules http://git.zephyr-software.com:opensrc/irdb-sdk.git
-export IRDB_SDK=$PWD/irdb-sdk
-```
-
-#### Step 3: Download and build ZAFL
-Once Zipr has been installed, clone the repo for ZAFL and build.
+#### Step 2: Download and build ZAFL
+First, clone ZAFL's repository:
```bash
git clone --recurse-submodules http://git.zephyr-software.com:opensrc/zafl.git
-cd zafl
```
-Prepare ZAFL's environment:
+Second, prepare ZAFL's environment:
```bash
-. set_env_vars
+cd /path/to/zafl && . set_env_vars
```
-Build ZAFL:
+Lastly, build ZAFL:
```bash
scons
# or scons debug=1
@@ -77,16 +70,16 @@ scons
# or scons debug=1 -j3
```
-## Using ZAFL for Binary Fuzzing
-Before running ZAFL, always make sure to prepare both it and Zipr's environments:
+## Using ZAFL for Linux Binary Fuzzing
+Before running ZAFL, **always make sure to prepare both it and Zipr's environments**:
```bash
-cd ~/zipr && . set_env_vars
-cd ~/zafl && . set_env_vars
+cd /path/to/zipr && . set_env_vars
+cd /path/to/zafl && . set_env_vars
```
#### Step 0: Ensure ZAFL's smoke tests succeed
```bash
-cd ~/zafl/test/bc && ./test_bc.sh
+cd /path/to/zafl/test/bc && ./test_bc.sh
```
This test will instrument and fuzz a copy of Linux's `bc` binary. If successful, the final output should contain something like:
```bash
@@ -101,25 +94,27 @@ zafl.sh /bin/ls /tmp/ls.zafl
```
The output should contain the following:
```
+Zafl: main exec is PIE... use entry point address (0x5850) for fork server
+Zafl: Transforming input binary /bin/ls into ./tmp/ls.zafl
+Zafl: Issuing command: ~/zipr/installed/tools/ps_zipr.sh /bin/ls ./tmp/ls.zafl -c rida -s move_globals -c zax -o move_globals:--elftables-only -o move_globals:--no-use-stars -o zax:--stars -o zax:--enable-floating-instrumentation -o zax:'-e 0x5850'
Using Zipr backend.
-Detected ELF file.
-Performing step gather_libraries [dependencies=mandatory] ...Done. Successful.
-Performing step meds_static [dependencies=mandatory] ...Done. Successful.
-Performing step pdb_register [dependencies=mandatory] ...Done. Successful.
-Performing step fill_in_cfg [dependencies=mandatory] ...Done. Successful.
-Performing step fill_in_indtargs [dependencies=mandatory] ...Done. Successful.
-Performing step clone [dependencies=mandatory] ...Done. Successful.
-Performing step fix_calls [dependencies=mandatory] ...Done. Successful.
-Program not detected in signature database.
-Performing step move_globals [dependencies=none] ...Done. Successful.
-Performing step zafl [dependencies=none] ...Done. Successful.
-Performing step zipr [dependencies=clone,fill_in_indtargs,fill_in_cfg,pdb_register] ...Done. Successful.
+Detected ELF shared object.
+Performing step rida [dependencies=mandatory] ...Done. Successful.
+Performing step pdb_register [dependencies=mandatory] ...Done. Successful.
+Performing step fill_in_cfg [dependencies=unknown] ...Done. Successful.
+Performing step fill_in_indtargs [dependencies=unknown] ...Done. Successful.
+Performing step fix_calls [dependencies=unknown] ...Done. Successful.
+Performing step move_globals [dependencies=unknown] ...Done. Successful.
+Performing step zax [dependencies=none] ...Done. Successful.
+Performing step zipr [dependencies=none] ...Done. Successful.
+Zafl: success. Output file is: ./tmp/ls.zafl
+
```
#### Step 2: Running an instrumented binary
-All ZAFL'd binaries can be run normally just as their original uninstrumented versions: ```./tmp/ls.zafl```.
+All ZAFL'd binaries can be run normally just as their original uninstrumented versions, e.g.: ```./tmp/ls.zafl```.
-To ensure the binary has been instrumented properly: ```ZAFL_DEBUG=1 ./tmp/ls.zafl```
+To ensure the binary has been instrumented properly, run: ```ZAFL_DEBUG=1 ./tmp/ls.zafl```.
The output should start with:
```
Error getting shm environment variable - fake allocate AFL trace map
@@ -130,21 +125,28 @@ libautozafl: auto-initialize fork server
#### Step 3: Fuzzing an instrumented binary
Let's prep a seed directory for fuzzing:
```bash
-mkdir in && echo "hello" > in/seed
+mkdir in_dir && echo "hello" > in_dir/seed
```
Let's now run the ZAFL'd binary with AFL:
```bash
-afl-fuzz -i in -o out -- ./tmp/ls.zafl @@
+afl-fuzz -i in_dir -o out_dir -- ./tmp/ls.zafl @@
```
-If AFL complains about `missing instrumentation`, you'll need to set the following environment variable before fuzzing:
+If AFL complains about `Looks like the target binary is not instrumented!`, you'll need to set the following environment variable before fuzzing:
```bash
export AFL_SKIP_BIN_CHECK=1
```
ZAFL's instrumentation also supports AFL's other utilities, e.g.:
```bash
afl-showmap -o map.out -- ./tmp/ls.zafl
-afl-cmin -i out/queue/ -o cmin.out -- ./tmp/ls.zafl @@
+afl-cmin -i out_dir/queue/ -o cmin.out -- ./tmp/ls.zafl @@
+```
+
+## Using ZAFL for Windows Binaries
+ZAFL offers preliminary instrumentation support for Windows 7 PE32+ binaries, though WinAFL-compatible fuzzing instrumentation is not yet supported at this time. Instrumenting Windows binaries must be performed with a *Linux-based* ZAFL install. **This mode requires IDA Pro and the following modified command**:
+```bash
+zafl.sh <target_binary> <zafl_output_binary> -F --ida --no-stars
```
+We hope to improve our Windows support in the near future.
# TL;DR
Once everything is installed properly, you can prepare a binary for fuzzing with the simple command:
@@ -153,4 +155,4 @@ zafl.sh <target_binary> <zafl_output_binary>
```
To see what transformations ZAFL currently supports, simply run ```zafl.sh --help```.
-**We welcome any community contributions, and ideas for improvements and new fuzzing transformations!** Feel free to contact us by opening up an `Issue`, or submitting new features through a `Merge Request`. **Happy fuzzing!**
+**We welcome any community contributions, and ideas for improvements and new fuzzing transformations!** To open an issue or merge request, please contact one of the developers (`hiser@virginia.edu`, `an7s@virginia.edu`, `jwd@virginia.edu`, or `snagy2@vt.edu`). **Happy fuzzing!**