added man pages

Makefile

@@ -24,11 +24,13 @@ BIN_PATH    = $(PREFIX)/bin
 HELPER_PATH = $(PREFIX)/lib/afl
 DOC_PATH    = $(PREFIX)/share/doc/afl
 MISC_PATH   = $(PREFIX)/share/afl
+MAN_PATH    = $(PREFIX)/man/man8
 
 # PROGS intentionally omit afl-as, which gets installed elsewhere.
 
 PROGS       = afl-gcc afl-fuzz afl-showmap afl-tmin afl-gotcpu afl-analyze
 SH_PROGS    = afl-plot afl-cmin afl-whatsup afl-system-config
+MANPAGES=$(foreach p, $(PROGS) $(SH_PROGS), $(p).8)
 
 CFLAGS     ?= -O3 -funroll-loops
 CFLAGS     += -Wall -D_FORTIFY_SOURCE=2 -g -Wno-pointer-sign -I include/ \
@@ -203,13 +205,33 @@ all_done: test_build
 .NOTPARALLEL: clean
 
 clean:
-	rm -f $(PROGS) afl-as as afl-g++ afl-clang afl-clang++ *.o *~ a.out core core.[1-9][0-9]* *.stackdump test .test .test1 .test2 test-instr .test-instr0 .test-instr1 qemu_mode/qemu-3.1.0.tar.xz afl-qemu-trace afl-gcc-fast  afl-gcc-pass.so  afl-gcc-rt.o  afl-g++-fast
+	rm -f $(PROGS) afl-as as afl-g++ afl-clang afl-clang++ *.o *~ a.out core core.[1-9][0-9]* *.stackdump test .test .test1 .test2 test-instr .test-instr0 .test-instr1 qemu_mode/qemu-3.1.0.tar.xz afl-qemu-trace afl-gcc-fast afl-gcc-pass.so afl-gcc-rt.o afl-g++-fast *.so unicorn_mode/24f55a7973278f20f0de21b904851d99d4716263.tar.gz *.8
-	rm -rf out_dir qemu_mode/qemu-3.1.0
+	rm -rf out_dir qemu_mode/qemu-3.1.0 unicorn_mode/unicorn
 	$(MAKE) -C llvm_mode clean
 	$(MAKE) -C libdislocator clean
 	$(MAKE) -C libtokencap clean
+	$(MAKE) -C qemu_mode/libcompcov clean
 
-install: all
+%.8:	%
+	@echo .TH $* 8 `date --iso-8601` "afl++" > $@
+	@echo .SH NAME >> $@
+	@echo .B $* >> $@
+	@echo >> $@
+	@echo .SH SYNOPSIS >> $@
+	@./$* -h 2>&1 | head -n 3 | tail -n 1 | sed 's/^\.\///' >> $@
+	@echo >> $@
+	@echo .SH OPTIONS >> $@
+	@echo .nf >> $@
+	@./$* -h 2>&1 | tail -n +4 >> $@
+	@echo >> $@
+	@echo .SH AUTHOR >> $@
+	@echo "afl++ was written by Michal \"lcamtuf\" Zalewski and is maintained by Marc \"van Hauser\" Heuse <mh@mh-sec.de>, Heiko \"hexc0der\" Eissfeldt <heiko.eissfeldt@hexco.de> and Andrea Fioraldi <andreafioraldi@gmail.com>" >> $@
+	@echo  The homepage of afl++ is: https://github.com/vanhauser-thc/AFLplusplus >> $@
+	@echo >> $@
+	@echo .SH LICENSE >> $@
+	@echo Apache License Version 2.0, January 2004 >> $@
+
+install: all $(MANPAGES)
 	mkdir -p -m 755 $${DESTDIR}$(BIN_PATH) $${DESTDIR}$(HELPER_PATH) $${DESTDIR}$(DOC_PATH) $${DESTDIR}$(MISC_PATH)
 	rm -f $${DESTDIR}$(BIN_PATH)/afl-plot.sh
 	install -m 755 $(PROGS) $(SH_PROGS) $${DESTDIR}$(BIN_PATH)
@@ -226,10 +248,14 @@ endif
 	if [ -f compare-transform-pass.so ]; then set -e; install -m 755 compare-transform-pass.so $${DESTDIR}$(HELPER_PATH); fi
 	if [ -f split-compares-pass.so ]; then set -e; install -m 755 split-compares-pass.so $${DESTDIR}$(HELPER_PATH); fi
 	if [ -f split-switches-pass.so ]; then set -e; install -m 755 split-switches-pass.so $${DESTDIR}$(HELPER_PATH); fi
+	if [ -f libcompcov.so ]; then set -e; install -m 755 libcompcov.so $${DESTDIR}$(HELPER_PATH); fi
 
 	set -e; ln -sf afl-gcc $${DESTDIR}$(BIN_PATH)/afl-g++
 	set -e; if [ -f afl-clang-fast ] ; then ln -sf afl-clang-fast $${DESTDIR}$(BIN_PATH)/afl-clang ; ln -sf afl-clang-fast $${DESTDIR}$(BIN_PATH)/afl-clang++ ; else ln -sf afl-gcc $${DESTDIR}$(BIN_PATH)/afl-clang ; ln -sf afl-gcc $${DESTDIR}$(BIN_PATH)/afl-clang++; fi
 
+	mkdir -m 0755 -p $(MAN_PATH)
+	install -m0644 -D *.8 $(MAN_PATH)
+
 	install -m 755 afl-as $${DESTDIR}$(HELPER_PATH)
 	ln -sf afl-as $${DESTDIR}$(HELPER_PATH)/as
 	install -m 644 docs/README.md docs/ChangeLog docs/*.txt $${DESTDIR}$(DOC_PATH)

TODO

@@ -4,6 +4,9 @@ Roadmap 2.53d:
 afl-fuzz:
  - custom mutator lib: example and readme
 
+man:
+ - man page for afl-clang-fast
+
 
 Roadmap 2.54d:
 ==============

afl-cmin

@@ -51,10 +51,13 @@ TIMEOUT=none
 unset IN_DIR OUT_DIR STDIN_FILE EXTRA_PAR MEM_LIMIT_GIVEN \
   AFL_CMIN_CRASHES_ONLY AFL_CMIN_ALLOW_ANY QEMU_MODE UNICORN_MODE
 
-while getopts "+i:o:f:m:t:eQUC" opt; do
+while getopts "+i:o:f:m:t:eQUCh" opt; do
 
   case "$opt" in 
 
+    "h")
+	;;
+
     "i")
          IN_DIR="$OPTARG"
          ;;

afl-plot

@@ -21,10 +21,10 @@ echo
 if [ ! "$#" = "2" ]; then
 
   cat 1>&2 <<_EOF_
-This program generates gnuplot images from afl-fuzz output data. Usage:
-
 $0 afl_state_dir graph_output_dir
 
+This program generates gnuplot images from afl-fuzz output data. Usage:
+
 The afl_state_dir parameter should point to an existing state directory for any
 active or stopped instance of afl-fuzz; while graph_output_dir should point to
 an empty directory where this tool can write the resulting plots to.

afl-system-config

@@ -1,4 +1,17 @@
 #!/bin/sh
+test "$1" = "-h" && {
+  echo afl-system-config by Marc Heuse
+  echo
+  echo $0
+  echo
+  echo afl-system-config has no command line options
+  echo
+  echo afl-system reconfigures the system to a high performance fuzzing state
+  echo WARNING: this reduces the security of the system
+  echo
+  exit 1
+}
+
 PLATFORM=`uname -s`
 echo This reconfigures the system to have a better fuzzing performance
 if [ '!' "$EUID" = 0 ] && [ '!' `id -u` = 0 ] ; then

afl-whatsup

@@ -19,6 +19,13 @@
 
 echo "status check tool for afl-fuzz by <lcamtuf@google.com>"
 echo
+test "$1" = "-h" && {
+  echo $0
+  echo
+  echo afl-whatsup has no command line options
+  echo
+  exit 1
+}
 
 if [ "$1" = "-s" ]; then
 

docs/ChangeLog

@@ -19,11 +19,12 @@ Version ++2.53d (dev):
 
   - big code refactoring:
     * all includes are now in include/
-    * all afl sources are now in src/ - see src/README
+    * all afl sources are now in src/ - see src/README.src
     * afl-fuzz was splitted up in various individual files for including
       functionality in other programs (e.g. forkserver, memory map, etc.)
-      or better readability.
+      for better readability.
     * new code indention everywhere
+  - auto-generating man pages for all (main) tools
   - added AFL_FORCE_UI to show the UI even if the terminal is not detected
   - llvm 9 is now supported (still needs testing)
   - Android is now supported (thank to JoeyJiao!) - still need to modify the Makefile though

qemu_mode/build_qemu_support.sh

@@ -112,7 +112,8 @@ if [ "$CKSUM" = "$QEMU_SHA384" ]; then
 
 else
 
-  echo "[-] Error: signature mismatch on $ARCHIVE (perhaps download error?)."
+  echo "[-] Error: signature mismatch on $ARCHIVE (perhaps download error?), removing archive ..."
+  rm -f "$ARCHIVE"
   exit 1
 
 fi
@@ -200,6 +201,8 @@ if [ "$ORIG_CPU_TARGET" = "" ]; then
   echo "[+] Instrumentation tests passed. "
   echo "[+] All set, you can now use the -Q mode in afl-fuzz!"
 
+  cd qemu_mode || exit 1
+
 else
 
   echo "[!] Note: can't test instrumentation when CPU_TARGET set."
@@ -207,4 +210,9 @@ else
 
 fi
 
+echo "[+] Building libcompcov ..."
+make -C libcompcov
+echo "[+] libcompcov ready"
+echo "[+] All done for qemu_mode, enjoy!"
+
 exit 0

qemu_mode/libcompcov/Makefile

@@ -25,18 +25,18 @@ LDFLAGS     += -ldl
 all: libcompcov.so compcovtest
 
 libcompcov.so: libcompcov.so.c ../../config.h
-	$(CC) $(CFLAGS) -shared -fPIC $< -o $@ $(LDFLAGS)
+	$(CC) $(CFLAGS) -shared -fPIC $< -o ../../$@ $(LDFLAGS)
 
 .NOTPARALLEL: clean
 
 clean:
 	rm -f *.o *.so *~ a.out core core.[1-9][0-9]*
-	rm -f libcompcov.so compcovtest
+	rm -f ../../libcompcov.so compcovtest
 
 compcovtest:	compcovtest.cc
 	$(CXX) $< -o $@ 
 
 install: all
-	install -m 755 libcompcov.so $${DESTDIR}$(HELPER_PATH)
+	install -m 755 ../../libcompcov.so $${DESTDIR}$(HELPER_PATH)
 	install -m 644 README.compcov $${DESTDIR}$(HELPER_PATH)
 

src/README.src

@@ -0,0 +1,22 @@
+Quick explanation about the files here:
+
+afl-analyze.c		- afl-analyze binary tool
+afl-as.c		- afl-as binary tool
+afl-gotcpu.c		- afl-gotcpu binary tool
+afl-showmap.c		- afl-showmap binary tool
+afl-tmin.c		- afl-tmin binary tool
+afl-fuzz.c		- afl-fuzz binary tool (just main() and usage())
+afl-fuzz-bitmap.c	- afl-fuzz bitmap handling
+afl-fuzz-extras.c	- afl-fuzz the *extra* function calls
+afl-fuzz-globals.c	- afl-fuzz global variables
+afl-fuzz-init.c		- afl-fuzz initialization
+afl-fuzz-misc.c		- afl-fuzz misc functions
+afl-fuzz-one.c          - afl-fuzz fuzzer_one big loop, this is where the mutation is happening
+afl-fuzz-python.c	- afl-fuzz the python mutator extension
+afl-fuzz-queue.c	- afl-fuzz handling the queue
+afl-fuzz-run.c		- afl-fuzz running the target
+afl-fuzz-stats.c	- afl-fuzz writing the statistics file
+afl-gcc.c		- afl-gcc binary tool (deprecated)
+afl-common.c		- common functions, used by afl-analyze, afl-fuzz, afl-showmap and afl-tmin
+afl-forkserver.c	- forkserver implementation, used by afl-fuzz and afl-tmin
+afl-sharedmem.c		- sharedmem implementation, used by afl-fuzz and afl-tmin

src/afl-analyze.c

@@ -900,7 +900,7 @@ int main(int argc, char** argv) {
 
   SAYF(cCYA "afl-analyze" VERSION cRST " by <lcamtuf@google.com>\n");
 
-  while ((opt = getopt(argc, argv, "+i:f:m:t:eQU")) > 0)
+  while ((opt = getopt(argc, argv, "+i:f:m:t:eQUh")) > 0)
 
     switch (opt) {
 
@@ -988,6 +988,11 @@ int main(int argc, char** argv) {
 
         unicorn_mode = 1;
         break;
+        
+      case 'h':
+        usage(argv[0]);
+        return -1;
+        break;
 
       default: usage(argv[0]);
 

src/afl-fuzz.c

@@ -131,7 +131,7 @@ int main(int argc, char** argv) {
   gettimeofday(&tv, &tz);
   init_seed = tv.tv_sec ^ tv.tv_usec ^ getpid();
 
-  while ((opt = getopt(argc, argv, "+i:o:f:m:t:T:dnCB:S:M:x:QUe:p:s:V:E:L:")) >
+  while ((opt = getopt(argc, argv, "+i:o:f:m:t:T:dnCB:S:M:x:QUe:p:s:V:E:L:h")) >
          0)
 
     switch (opt) {
@@ -490,6 +490,11 @@ int main(int argc, char** argv) {
 
       } break;
 
+      case 'h':
+        usage(argv[0]);
+        return -1;
+        break; // not needed
+
       default: usage(argv[0]);
 
     }

src/afl-gcc.c

@@ -333,6 +333,14 @@ static void edit_params(u32 argc, char** argv) {
 
 int main(int argc, char** argv) {
 
+  if (argc == 2 && strcmp(argv[1], "-h") == 0) {
+    printf("afl-cc" VERSION" by <lcamtuf@google.com>\n\n");
+    printf("%s \n\n", argv[0]);
+    printf("afl-gcc has no command line options\n");
+    printf("NOTE: afl-gcc is deprecated, llvm_mode is much faster and has more options\n");
+    return -1;
+  }
+
   if (isatty(2) && !getenv("AFL_QUIET")) {
 
     SAYF(cCYA "afl-cc" VERSION cRST " by <lcamtuf@google.com>\n");

src/afl-gotcpu.c

@@ -127,6 +127,14 @@ repeat_loop:
 
 int main(int argc, char** argv) {
 
+  if (argc > 1) {
+    printf("afl-gotcpu" VERSION " by <lcamtuf@google.com>\n");
+    printf("\n%s \n\n", argv[0]);
+    printf("afl-gotcpu does not have command line options\n");
+    printf("afl-gotcpu prints out which CPUs are available\n");
+    return -1;
+  }
+
 #ifdef HAVE_AFFINITY
 
   u32 cpu_cnt = sysconf(_SC_NPROCESSORS_ONLN), idle_cpus = 0, maybe_cpus = 0, i;

src/afl-showmap.c

@@ -563,7 +563,7 @@ int main(int argc, char** argv) {
 
   doc_path = access(DOC_PATH, F_OK) ? "docs" : DOC_PATH;
 
-  while ((opt = getopt(argc, argv, "+o:m:t:A:eqZQUbcr")) > 0)
+  while ((opt = getopt(argc, argv, "+o:m:t:A:eqZQUbcrh")) > 0)
 
     switch (opt) {
 
@@ -691,6 +691,11 @@ int main(int argc, char** argv) {
         if (edges_only) FATAL("-e and -r are mutually exclusive");
         raw_instr_output = 1;
         break;
+    
+      case 'h':
+        usage(argv[0]);
+        return -1;
+        break;
 
       default: usage(argv[0]);
 

src/afl-tmin.c

@@ -1091,7 +1091,7 @@ int main(int argc, char** argv) {
 
   SAYF(cCYA "afl-tmin" VERSION cRST " by <lcamtuf@google.com>\n");
 
-  while ((opt = getopt(argc, argv, "+i:o:f:m:t:B:xeQU")) > 0)
+  while ((opt = getopt(argc, argv, "+i:o:f:m:t:B:xeQUh")) > 0)
 
     switch (opt) {
 
@@ -1211,6 +1211,11 @@ int main(int argc, char** argv) {
         mask_bitmap = ck_alloc(MAP_SIZE);
         read_bitmap(optarg);
         break;
+      
+      case 'h':
+        usage(argv[0]);
+        return -1;
+        break;
 
       default: usage(argv[0]);