modernize some readmes
RENAME
libdislocator/README.dislocator
libdislocator/README.md
-===================================
-libdislocator, an abusive allocator
-===================================
+# libdislocator, an abusive allocator
(See ../docs/README for the general instruction manual.)
@@ -45,7 +43,9 @@ when fuzzing small, self-contained binaries.
To use this library, run AFL like so:
+```
AFL_PRELOAD=/path/to/libdislocator.so ./afl-fuzz [...other params...]
+```
You *have* to specify path, even if it's just ./libdislocator.so or
$PWD/libdislocator.so.

RENAME
libtokencap/README.tokencap
libtokencap/README.md
-=========================================
-strcmp() / memcmp() token capture library
-=========================================
+# strcmp() / memcmp() token capture library
(See ../docs/README for the general instruction manual.)
-This Linux-only companion library allows you to instrument strcmp(), memcmp(),
+This Linux-only companion library allows you to instrument `strcmp()`, `memcmp()`,
and related functions to automatically extract syntax tokens passed to any of
these libcalls. The resulting list of tokens may be then given as a starting
dictionary to afl-fuzz (the -x option) to improve coverage on subsequent
@@ -31,15 +29,18 @@ with -fno-builtin and is linked dynamically. If you wish to automate the first
part without mucking with CFLAGS in Makefiles, you can set AFL_NO_BUILTIN=1
when using afl-gcc. This setting specifically adds the following flags:
+```
-fno-builtin-strcmp -fno-builtin-strncmp -fno-builtin-strcasecmp
-fno-builtin-strcasencmp -fno-builtin-memcmp -fno-builtin-strstr
-fno-builtin-strcasestr
+```
The next step is simply loading this library via LD_PRELOAD. The optimal usage
pattern is to allow afl-fuzz to fuzz normally for a while and build up a corpus,
and then fire off the target binary, with libtokencap.so loaded, on every file
found by AFL in that earlier run. This demonstrates the basic principle:
+```
export AFL_TOKEN_FILE=$PWD/temp_output.txt
for i in <out_dir>/queue/id*; do
@@ -48,6 +49,7 @@ found by AFL in that earlier run. This demonstrates the basic principle:
done
sort -u temp_output.txt >afl_dictionary.txt
+```
If you don't get any results, the target library is probably not using strcmp()
and memcmp() to parse input; or you haven't compiled it with -fno-builtin; or
@@ -55,7 +57,7 @@ the whole thing isn't dynamically linked, and LD_PRELOAD is having no effect.
PS. The library is Linux-only because there is probably no particularly portable
and non-invasive way to distinguish between read-only and read-write memory
-mappings. The __tokencap_load_mappings() function is the only thing that would
+mappings. The `__tokencap_load_mappings()` function is the only thing that would
need to be changed for other OSes. Porting to platforms with /proc/<pid>/maps
(e.g., FreeBSD) should be trivial.

RENAME
qemu_mode/libcompcov/README.compcov
qemu_mode/libcompcov/README.md
-================================================================
-strcmp() / memcmp() CompareCoverage library for AFLplusplus-QEMU
-================================================================
+# strcmp() / memcmp() CompareCoverage library for afl++ QEMU
Written by Andrea Fioraldi <andreafioraldi@gmail.com>
-This Linux-only companion library allows you to instrument strcmp(), memcmp(),
+This Linux-only companion library allows you to instrument `strcmp()`, `memcmp()`,
and related functions to log the CompareCoverage of these libcalls.
Use this with caution. While this can speedup a lot the bypass of hard
@@ -22,10 +20,12 @@ library and QEMU but build it with afl-clang-fast and the laf-intel options.
To use this library make sure to preload it with AFL_PRELOAD.
+```
export AFL_PRELOAD=/path/to/libcompcov.so
export AFL_COMPCOV_LEVEL=1
afl-fuzz -Q -i input -o output <your options> -- <target args>
+```
The AFL_COMPCOV_LEVEL tells to QEMU and libcompcov how to log comaprisons.
Level 1 logs just comparison with immediates / read-only memory and level 2

modernize some readmes