Merge pull request #360 from AFLplusplus/dev

new code formatting + applied

.clang-format

@@ -0,0 +1,148 @@
+---
+Language:        Cpp
+# BasedOnStyle:  Google
+AccessModifierOffset: -1
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: true
+AlignEscapedNewlines: Left
+AlignOperands:   true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: true
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: false
+AllowShortIfStatementsOnASingleLine: true
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: true
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:   
+  AfterClass:      false
+  AfterControlStatement: false
+  AfterEnum:       false
+  AfterFunction:   false
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  AfterExternBlock: false
+  BeforeCatch:     false
+  BeforeElse:      false
+  IndentBraces:    false
+  SplitEmptyFunction: true
+  SplitEmptyRecord: true
+  SplitEmptyNamespace: true
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Attach
+BreakBeforeInheritanceComma: false
+BreakInheritanceList: BeforeColon
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: BeforeColon
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: true
+ColumnLimit:     80
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:   
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeBlocks:   Preserve
+IncludeCategories: 
+  - Regex:           '^<ext/.*\.h>'
+    Priority:        2
+  - Regex:           '^<.*\.h>'
+    Priority:        1
+  - Regex:           '^<.*'
+    Priority:        2
+  - Regex:           '.*'
+    Priority:        3
+IncludeIsMainRegex: '([-_](test|unittest))?$'
+IndentCaseLabels: true
+IndentPPDirectives: BeforeHash
+IndentWidth:     2
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: false
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCBinPackProtocolList: Never
+ObjCBlockIndentWidth: 2
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 1
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyBreakTemplateDeclaration: 10
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 200
+PointerAlignment: Right
+RawStringFormats: 
+  - Language:        Cpp
+    Delimiters:      
+      - cc
+      - CC
+      - cpp
+      - Cpp
+      - CPP
+      - 'c++'
+      - 'C++'
+    CanonicalDelimiter: ''
+    BasedOnStyle:    google
+  - Language:        TextProto
+    Delimiters:      
+      - pb
+      - PB
+      - proto
+      - PROTO
+    EnclosingFunctions: 
+      - EqualsProto
+      - EquivToProto
+      - PARSE_PARTIAL_TEXT_PROTO
+      - PARSE_TEST_PROTO
+      - PARSE_TEXT_PROTO
+      - ParseTextOrDie
+      - ParseTextProtoOrDie
+    CanonicalDelimiter: ''
+    BasedOnStyle:    google
+ReflowComments:  true
+SortIncludes:    false
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+SpacesInAngles:  false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard:        Auto
+TabWidth:        8
+UseTab:          Never
+...
+

.custom-format.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+#
+# american fuzzy lop++ - custom code formatter
+# --------------------------------------------
+#
+# Written and maintaned by Andrea Fioraldi <andreafioraldi@gmail.com>
+#
+# Copyright 2015, 2016, 2017 Google Inc. All rights reserved.
+# Copyright 2019-2020 AFLplusplus Project. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+
+import subprocess
+import sys
+import os
+import re
+
+# string_re = re.compile('(\\"(\\\\.|[^"\\\\])*\\")') # future use
+
+with open(".clang-format") as f:
+    fmt = f.read()
+
+CLANG_FORMAT_BIN = os.getenv("CLANG_FORMAT_BIN")
+if CLANG_FORMAT_BIN is None:
+    o = 0
+    try:
+        p = subprocess.Popen(["clang-format-10", "--version"], stdout=subprocess.PIPE)
+        o, _ = p.communicate()
+        o = str(o, "utf-8")
+        o = o[len("clang-format version "):].strip()
+        o = o[:o.find(".")]
+        o = int(o)
+    except:
+        print ("clang-format-10 is needed. Aborted.")
+        exit(1)
+    #if o < 7:
+    #    if subprocess.call(['which', 'clang-format-7'], stdout=subprocess.PIPE) == 0:
+    #        CLANG_FORMAT_BIN = 'clang-format-7'
+    #    elif subprocess.call(['which', 'clang-format-8'], stdout=subprocess.PIPE) == 0:
+    #        CLANG_FORMAT_BIN = 'clang-format-8'
+    #    elif subprocess.call(['which', 'clang-format-9'], stdout=subprocess.PIPE) == 0:
+    #        CLANG_FORMAT_BIN = 'clang-format-9'
+    #    elif subprocess.call(['which', 'clang-format-10'], stdout=subprocess.PIPE) == 0:
+    #        CLANG_FORMAT_BIN = 'clang-format-10'
+    #    else:
+    #        print ("clang-format 7 or above is needed. Aborted.")
+    #        exit(1)
+    else:
+        CLANG_FORMAT_BIN = 'clang-format-10'
+            
+COLUMN_LIMIT = 80
+for line in fmt.split("\n"):
+    line = line.split(":")
+    if line[0].strip() == "ColumnLimit":
+        COLUMN_LIMIT = int(line[1].strip())
+
+
+def custom_format(filename):
+    p = subprocess.Popen([CLANG_FORMAT_BIN, filename], stdout=subprocess.PIPE)
+    src, _ = p.communicate()
+    src = str(src, "utf-8")
+
+    in_define = False
+    last_line = None
+    out = ""
+    
+    for line in src.split("\n"):
+        if line.lstrip().startswith("#"):
+            if line[line.find("#")+1:].lstrip().startswith("define"):
+                in_define = True
+        
+        if "/*" in line and not line.strip().startswith("/*") and line.endswith("*/") and len(line) < (COLUMN_LIMIT-2):
+            cmt_start = line.rfind("/*")
+            line = line[:cmt_start] + " " * (COLUMN_LIMIT-2 - len(line)) + line[cmt_start:]
+
+        define_padding = 0
+        if last_line is not None and in_define and last_line.endswith("\\"):
+            last_line = last_line[:-1]
+            define_padding = max(0, len(last_line[last_line.rfind("\n")+1:]))
+
+        if last_line is not None and last_line.strip().endswith("{") and line.strip() != "":
+            line = (" " * define_padding + "\\" if in_define else "") + "\n" + line
+        elif last_line is not None and last_line.strip().startswith("}") and line.strip() != "":
+            line = (" " * define_padding + "\\" if in_define else "") + "\n" + line
+        elif line.strip().startswith("}") and last_line is not None and last_line.strip() != "":
+            line = (" " * define_padding + "\\" if in_define else "") + "\n" + line
+
+        if not line.endswith("\\"):
+            in_define = False
+
+        out += line + "\n"
+        last_line = line
+
+    return (out)
+
+args = sys.argv[1:]
+if len(args) == 0:
+    print ("Usage: ./format.py [-i] <filename>")
+    print ()
+    print (" The -i option, if specified, let the script to modify in-place")
+    print (" the source files. By default the results are written to stdout.")
+    print()
+    exit(1)
+
+in_place = False
+if args[0] == "-i":
+    in_place = True
+    args = args[1:]
+
+for filename in args:
+    code = custom_format(filename)
+    if in_place:
+        with open(filename, "w") as f:
+            f.write(code)
+    else:
+        print(code)
+

.gitignore

@@ -1,23 +1,52 @@
+.test
+.test2
 *.o
 *.so
-.gitignore
 afl-analyze
 afl-as
 afl-clang
 afl-clang++
 afl-clang-fast
 afl-clang-fast++
+afl-clang-lto
+afl-clang-lto++
 afl-fuzz
 afl-g++
 afl-gcc
 afl-gcc-fast
 afl-g++-fast
 afl-gotcpu
+afl-ld
 afl-qemu-trace
 afl-showmap
 afl-tmin
+afl-analyze.8
+afl-as.8
+afl-clang-fast++.8
+afl-clang-fast.8
+afl-clang-lto.8
+afl-clang-lto++.8
+afl-cmin.8
+afl-cmin.bash.8
+afl-fuzz.8
+afl-gcc.8
+afl-gcc-fast.8
+afl-g++-fast.8
+afl-gotcpu.8
+afl-plot.8
+afl-showmap.8
+afl-system-config.8
+afl-tmin.8
+afl-whatsup.8
+qemu_mode/libcompcov/compcovtest
 as
-qemu_mode/qemu-3.1.0
-qemu_mode/qemu-3.1.0.tar.xz
-unicorn_mode/unicorn
-unicorn_mode/unicorn-*
+ld
+qemu_mode/qemu-*
+unicorn_mode/samples/*/\.test-*
+unicorn_mode/samples/*/output/
+core\.*
+test/unittests/unit_maybe_alloc
+test/unittests/unit_preallocable
+test/unittests/unit_list
+examples/afl_network_proxy/afl-network-server
+examples/afl_network_proxy/afl-network-client

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "unicorn_mode/unicornafl"]
+	path = unicorn_mode/unicornafl
+	url = https://github.com/AFLplusplus/unicornafl.git

.travis.yml

@@ -1,11 +1,58 @@
 language: c
 
+sudo: required
+
+branches:
+  only:
+    - master
+    - dev
+
+matrix:
+  include:
+  - os: linux
+    dist: focal
+    env: NAME="focal-amd64" MODERN="yes" GCC="9"
+  - os: linux
+    dist: bionic
+    env: NAME="bionic-amd64" MODERN="yes" GCC="7"
+  - os: linux
+    dist: xenial
+    env: NAME="xenial-amd64" MODERN="no" GCC="5" EXTRA="libtool-bin clang-6.0"
+  - os: linux
+    dist: trusty
+    env: NAME="trusty-amd64" MODERN="no" GCC="4.8"
+#  - os: linux # until travis can fix this!
+#    dist: xenial
+#    arch: arm64
+#    env: NAME="xenial-arm64" MODERN="no" GCC="5" EXTRA="libtool-bin clang-6.0" AFL_NO_X86="1" CPU_TARGET="aarch64"
+#  - os: osx
+#    osx_image: xcode11.2
+#    env: NAME="osx" HOMEBREW_NO_ANALYTICS="1" LINK="http://releases.llvm.org/9.0.0/" NAME="clang+llvm-9.0.0-x86_64-darwin-apple"
+
+jobs:
+  allow_failures:
+    - os: osx
+    - arch: arm64
+
 env:
   - AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1 AFL_NO_UI=1
+ # - AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1 AFL_NO_UI=1 AFL_EXIT_WHEN_DONE=1
+ # TODO: test AFL_BENCH_UNTIL_CRASH once we have a target that crashes
+ # - AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1 AFL_NO_UI=1 AFL_BENCH_JUST_ONE=1
+
+before_install:
+  # export LLVM_DIR=${TRAVIS_BUILD_DIR}/${LLVM_PACKAGE}
+  - echo Testing on $NAME
+  - if [ "$TRAVIS_OS_NAME" = "osx" ]; then wget "$LINK""$NAME".tar.xz ; export LLVM_CONFIG=`pwd`/"$NAME" ; tar xJf "$NAME".tar.xz ; fi
+  - if [ "$MODERN" = "yes" ]; then sudo apt update ; sudo apt upgrade ; sudo apt install -y git libtool libtool-bin automake bison libglib2.0-0 build-essential clang gcc-"$GCC" gcc-"$GCC"-plugin-dev libc++-"$GCC"-dev findutils libcmocka-dev python3-setuptools ; fi
+  - if [ "$MODERN" = "no" ]; then sudo apt update ; sudo apt install -y git libtool $EXTRA libpixman-1-dev automake bison libglib2.0 build-essential gcc-"$GCC" gcc-"$GCC"-plugin-dev libc++-dev findutils libcmocka-dev python3-setuptools ; fi
 
 script:
-  - make
-  - ./afl-gcc ./test-instr.c -o test-instr
-  - mkdir seeds; mkdir out
-  - echo "" > seeds/nil_seed
-  - timeout --preserve-status 5s ./afl-fuzz -i seeds -o out/ -- ./test-instr
+  - gcc -v
+  - clang -v
+  - sudo -E ./afl-system-config
+  - if [ "$TRAVIS_OS_NAME" = "osx" ]; then export LLVM_CONFIG=`pwd`/"$NAME" ; make source-only ASAN_BUILD=1 ; fi
+  - if [ "$TRAVIS_OS_NAME" = "linux" -a "$TRAVIS_CPU_ARCH" = "amd64" ]; then make distrib ASAN_BUILD=1 ; fi
+  - if [ "$TRAVIS_CPU_ARCH" = "arm64" ] ; then echo DEBUG ; find / -name llvm-config.h 2>/dev/null; apt-cache search clang | grep clang- ; apt-cache search llvm | grep llvm- ; dpkg -l | egrep 'clang|llvm'; echo DEBUG ; export LLVM_CONFIG=llvm-config-6.0 ; make ASAN_BUILD=1 ; cd qemu_mode && sh ./build_qemu_support.sh ; cd .. ; fi
+  - make tests
+#  - travis_terminate 0

Android.bp

@@ -0,0 +1,141 @@
+cc_defaults {
+  name: "afl-defaults",
+
+  cflags: [
+    "-funroll-loops",
+    "-Wno-pointer-sign",
+    "-Wno-pointer-arith",
+    "-Wno-sign-compare",
+    "-Wno-unused-parameter",
+    "-Wno-unused-function",
+    "-Wno-format",
+    "-Wno-user-defined-warnings",
+    "-DUSE_TRACE_PC=1",
+    "-DBIN_PATH=\"out/host/linux-x86/bin\"",
+    "-DDOC_PATH=\"out/host/linux-x86/shared/doc/afl\"",
+    "-D__USE_GNU",
+  ],
+}
+
+cc_binary {
+  name: "afl-fuzz",
+  static_executable: true,
+  host_supported: true,
+
+  defaults: [
+    "afl-defaults",
+  ],
+
+  srcs: [
+    "afl-fuzz.c",
+  ],
+}
+
+cc_binary {
+  name: "afl-showmap",
+  static_executable: true,
+  host_supported: true,
+
+  defaults: [
+    "afl-defaults",
+  ],
+
+  srcs: [
+    "afl-showmap.c",
+  ],
+}
+
+cc_binary {
+  name: "afl-tmin",
+  static_executable: true,
+  host_supported: true,
+
+  defaults: [
+    "afl-defaults",
+  ],
+
+  srcs: [
+    "afl-tmin.c",
+  ],
+}
+
+cc_binary {
+  name: "afl-analyze",
+  static_executable: true,
+  host_supported: true,
+
+  defaults: [
+    "afl-defaults",
+  ],
+
+  srcs: [
+    "afl-analyze.c",
+  ],
+}
+
+cc_binary {
+  name: "afl-gotcpu",
+  static_executable: true,
+  host_supported: true,
+
+  defaults: [
+    "afl-defaults",
+  ],
+
+  srcs: [
+    "afl-gotcpu.c",
+  ],
+}
+
+cc_binary_host {
+  name: "afl-clang-fast",
+  static_executable: true,
+
+  defaults: [
+    "afl-defaults",
+  ],
+
+  cflags: [
+    "-D__ANDROID__",
+    "-DAFL_PATH=\"out/host/linux-x86/lib64\"",
+  ],
+
+  srcs: [
+    "llvm_mode/afl-clang-fast.c",
+  ],
+}
+
+cc_binary_host {
+  name: "afl-clang-fast++",
+  static_executable: true,
+
+  defaults: [
+    "afl-defaults",
+  ],
+
+  cflags: [
+    "-D__ANDROID__",
+    "-DAFL_PATH=\"out/host/linux-x86/lib64\"",
+  ],
+
+  srcs: [
+    "llvm_mode/afl-clang-fast.c",
+  ],
+}
+
+cc_library_static {
+  name: "afl-llvm-rt",
+  compile_multilib: "both",
+  vendor_available: true,
+  host_supported: true,
+  recovery_available: true,
+  sdk_version: "9",
+
+  defaults: [
+    "afl-defaults",
+  ],
+
+  srcs: [
+    "llvm_mode/afl-llvm-rt.o.c",
+  ],
+}

Android.mk

@@ -0,0 +1 @@
+Makefile

CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# How to submit a Pull Request to AFLplusplus
+
+Each modified source file, before merging, must be formatted.
+
+```
+make code-format
+```
+
+This should be fine if you modified one of the files already present in the
+project, or added a file in a directory we already format, otherwise run:
+
+```
+./.custom-format.py -i file-that-you-have-created.c
+```
+
+Regarding the coding style, please follow the AFL style.
+No camel case at all and use the AFL's macros wherever possible 
+(e.g. WARNF, FATAL, MAP_SIZE, ...).
+
+Remember that AFLplusplus has to build and run on many platforms, so
+generalize your Makefiles (or your patches to our pre-existing Makefiles)
+to be as much generic as possible.

Changelog

@@ -1 +0,0 @@
-docs/ChangeLog

Changelog.md

@@ -0,0 +1 @@
+docs/Changelog.md

Dockerfile

@@ -0,0 +1,37 @@
+FROM ubuntu
+MAINTAINER David Carlier <devnexen@gmail.com>
+LABEL "about"="AFLplusplus docker image"
+RUN apt-get update && apt-get -y install \
+    --no-install-suggests --no-install-recommends \
+    automake \
+    bison \
+    build-essential \
+    clang \
+    clang-9 \
+    flex \
+    git \
+    python3 \
+    python3-dev \
+    python3-setuptools \
+    python-is-python3 \
+    gcc-9 \
+    gcc-9-plugin-dev \
+    gcc-9-multilib \
+    libc++-9-dev \
+    libtool \
+    libtool-bin \
+    libglib2.0-dev \
+    llvm-9-dev \
+    wget \
+    ca-certificates \
+    libpixman-1-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+ARG CC=gcc-9
+ARG CXX=g++-9
+ARG LLVM_CONFIG=llvm-config-9
+
+RUN git clone https://github.com/AFLplusplus/AFLplusplus
+
+RUN cd AFLplusplus && make clean && make distrib && \
+    make install && cd .. && rm -rf AFLplusplus

GNUmakefile

@@ -0,0 +1,563 @@
+#
+# american fuzzy lop++ - makefile
+# -----------------------------
+#
+# Originally written by Michal Zalewski
+#
+# Copyright 2013, 2014, 2015, 2016, 2017 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+
+# For Heiko:
+#TEST_MMAP=1
+# the hash character is treated differently in different make versions
+# so use a variable for '#'
+HASH=\#
+
+PREFIX     ?= /usr/local
+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
+
+PROGNAME    = afl
+VERSION     = $(shell grep '^$(HASH)define VERSION ' ../config.h | cut -d '"' -f2)
+
+# 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-cmin.bash afl-whatsup afl-system-config
+MANPAGES=$(foreach p, $(PROGS) $(SH_PROGS), $(p).8) afl-as.8
+ASAN_OPTIONS=detect_leaks=0
+
+ifeq "$(findstring android, $(shell $(CC) --version 2>/dev/null))" ""
+ifeq "$(shell echo 'int main() {return 0; }' | $(CC) $(CFLAGS) -Werror -x c - -flto=full -o .test 2>/dev/null && echo 1 || echo 0 ; rm -f .test )" "1"
+	CFLAGS_FLTO ?= -flto=full
+else
+ ifeq "$(shell echo 'int main() {return 0; }' | $(CC) $(CFLAGS) -Werror -x c - -flto=thin -o .test 2>/dev/null && echo 1 || echo 0 ; rm -f .test )" "1"
+	CFLAGS_FLTO ?= -flto=thin
+ else
+  ifeq "$(shell echo 'int main() {return 0; }' | $(CC) $(CFLAGS) -Werror -x c - -flto -o .test 2>/dev/null && echo 1 || echo 0 ; rm -f .test )" "1"
+	CFLAGS_FLTO ?= -flto
+  endif
+ endif
+endif
+endif
+
+ifneq "$(shell uname)" "Darwin"
+ ifeq "$(shell echo 'int main() {return 0; }' | $(CC) $(CFLAGS) -Werror -x c - -march=native -o .test 2>/dev/null && echo 1 || echo 0 ; rm -f .test )" "1"
+	CFLAGS_OPT += -march=native
+ endif
+ # OS X does not like _FORTIFY_SOURCE=2
+ CFLAGS_OPT += -D_FORTIFY_SOURCE=2
+endif
+
+ifdef STATIC
+  $(info Compiling static version of binaries)
+  # Disable python for static compilation to simplify things
+  PYTHON_OK=0
+  PYFLAGS=
+
+  CFLAGS_OPT += -static
+  LDFLAGS += -lm -lpthread -lz -lutil
+endif
+
+ifdef PROFILING
+  $(info Compiling with profiling information, for analysis: gprof ./afl-fuzz gmon.out > prof.txt)
+  CFLAGS_OPT += -pg -DPROFILING=1
+  LDFLAGS += -pg
+endif
+
+ifneq "$(shell uname -m)" "x86_64"
+ ifneq "$(patsubst i%86,i386,$(shell uname -m))" "i386"
+  ifneq "$(shell uname -m)" "amd64"
+   ifneq "$(shell uname -m)" "i86pc"
+	AFL_NO_X86=1
+   endif
+  endif
+ endif
+endif
+
+CFLAGS     ?= -O3 -funroll-loops $(CFLAGS_OPT)
+override CFLAGS += -Wall -g -Wno-pointer-sign -Wmissing-declarations\
+			  -I include/ -Werror -DAFL_PATH=\"$(HELPER_PATH)\" \
+			  -DBIN_PATH=\"$(BIN_PATH)\" -DDOC_PATH=\"$(DOC_PATH)\"
+
+ifeq "$(shell uname -s)" "OpenBSD"
+  override CFLAGS  += -I /usr/local/include/
+  LDFLAGS += -L /usr/local/lib/
+endif
+
+ifeq "$(shell uname -s)" "NetBSD"
+  override CFLAGS  += -I /usr/pkg/include/
+  LDFLAGS += -L /usr/pkg/lib/
+endif
+
+AFL_FUZZ_FILES = $(wildcard src/afl-fuzz*.c)
+
+ifneq "$(shell command -v python3m 2>/dev/null)" ""
+  ifneq "$(shell command -v python3m-config 2>/dev/null)" ""
+    PYTHON_INCLUDE  ?= $(shell python3m-config --includes)
+    PYTHON_VERSION  ?= $(strip $(shell python3m --version 2>&1))
+    # Starting with python3.8, we need to pass the `embed` flag. Earlier versions didn't know this flag.
+    ifeq "$(shell python3m-config --embed --libs 2>/dev/null | grep -q lpython && echo 1 )" "1"
+      PYTHON_LIB      ?= $(shell python3m-config --libs --embed --ldflags)
+    else
+      PYTHON_LIB      ?= $(shell python3m-config --ldflags)
+    endif
+  endif
+endif
+
+ifeq "$(PYTHON_INCLUDE)" ""
+  ifneq "$(shell command -v python3 2>/dev/null)" ""
+    ifneq "$(shell command -v python3-config 2>/dev/null)" ""
+      PYTHON_INCLUDE  ?= $(shell python3-config --includes)
+      PYTHON_VERSION  ?= $(strip $(shell python3 --version 2>&1))
+      # Starting with python3.8, we need to pass the `embed` flag. Earier versions didn't know this flag.
+      ifeq "$(shell python3-config --embed --libs 2>/dev/null | grep -q lpython && echo 1 )" "1"
+        PYTHON_LIB      ?= $(shell python3-config --libs --embed --ldflags)
+      else
+        PYTHON_LIB      ?= $(shell python3-config --ldflags)
+      endif
+    endif
+  endif
+endif
+
+ifeq "$(PYTHON_INCLUDE)" ""
+  ifneq "$(shell command -v python 2>/dev/null)" ""
+    ifneq "$(shell command -v python-config 2>/dev/null)" ""
+      PYTHON_INCLUDE  ?= $(shell python-config --includes)
+      PYTHON_LIB      ?= $(shell python-config --ldflags)
+      PYTHON_VERSION  ?= $(strip $(shell python --version 2>&1))
+    endif
+  endif
+endif
+
+# Old Ubuntu and others dont have python/python3-config so we hardcode 3.7
+ifeq "$(PYTHON_INCLUDE)" ""
+  ifneq "$(shell command -v python3.7 2>/dev/null)" ""
+    ifneq "$(shell command -v python3.7-config 2>/dev/null)" ""
+      PYTHON_INCLUDE  ?= $(shell python3.7-config --includes)
+      PYTHON_LIB      ?= $(shell python3.7-config --ldflags)
+      PYTHON_VERSION  ?= $(strip $(shell python3.7 --version 2>&1))
+    endif
+  endif
+endif
+
+# Old Ubuntu and others dont have python/python2-config so we hardcode 2.7
+ifeq "$(PYTHON_INCLUDE)" ""
+  ifneq "$(shell command -v python2.7 2>/dev/null)" ""
+    ifneq "$(shell command -v python2.7-config 2>/dev/null)" ""
+      PYTHON_INCLUDE  ?= $(shell python2.7-config --includes)
+      PYTHON_LIB      ?= $(shell python2.7-config --ldflags)
+      PYTHON_VERSION  ?= $(strip $(shell python2.7 --version 2>&1))
+    endif
+  endif
+endif
+
+ifdef SOURCE_DATE_EPOCH
+    BUILD_DATE ?= $(shell date -u -d "@$(SOURCE_DATE_EPOCH)" "+%Y-%m-%d" 2>/dev/null || date -u -r "$(SOURCE_DATE_EPOCH)" "+%Y-%m-%d" 2>/dev/null || date -u "+%Y-%m-%d")
+else
+    BUILD_DATE ?= $(shell date "+%Y-%m-%d")
+endif
+
+ifneq "$(filter Linux GNU%,$(shell uname))" ""
+  LDFLAGS += -ldl
+endif
+
+ifneq "$(findstring FreeBSD, $(shell uname))" ""
+  CFLAGS  += -pthread
+  LDFLAGS += -lpthread
+endif
+
+ifneq "$(findstring NetBSD, $(shell uname))" ""
+  CFLAGS  += -pthread
+  LDFLAGS += -lpthread
+endif
+
+ifeq "$(findstring clang, $(shell $(CC) --version 2>/dev/null))" ""
+  TEST_CC  = afl-gcc
+else
+  TEST_CC  = afl-clang
+endif
+
+COMM_HDR    = include/alloc-inl.h include/config.h include/debug.h include/types.h
+
+ifeq "$(shell echo '$(HASH)include <Python.h>@int main() {return 0; }' | tr @ '\n' | $(CC) $(CFLAGS) -x c - -o .test $(PYTHON_INCLUDE) $(LDFLAGS) $(PYTHON_LIB) 2>/dev/null && echo 1 || echo 0 ; rm -f .test )" "1"
+	PYTHON_OK=1
+	PYFLAGS=-DUSE_PYTHON $(PYTHON_INCLUDE) $(LDFLAGS) $(PYTHON_LIB) -DPYTHON_VERSION="\"$(PYTHON_VERSION)\""
+else
+	PYTHON_OK=0
+	PYFLAGS=
+endif
+
+ifdef NO_PYTHON
+	PYTHON_OK=0
+	PYFLAGS=
+endif
+
+IN_REPO=0
+ifeq "$(shell command -v git >/dev/null && git status >/dev/null 2>&1 && echo 1 || echo 0)" "1"
+  IN_REPO=1
+endif
+ifeq "$(shell command -v svn >/dev/null && svn proplist . 2>/dev/null && echo 1 || echo 0)" "1"
+  IN_REPO=1
+endif
+
+ifeq "$(shell echo 'int main() { return 0;}' | $(CC) $(CFLAGS) -fsanitize=address -x c - -o .test2 2>/dev/null && echo 1 || echo 0 ; rm -f .test2 )" "1"
+	ASAN_CFLAGS=-fsanitize=address -fstack-protector-all -fno-omit-frame-pointer
+	ASAN_LDFLAGS=-fsanitize=address -fstack-protector-all -fno-omit-frame-pointer
+endif
+
+ifdef ASAN_BUILD
+  $(info Compiling ASAN version of binaries)
+  CFLAGS+=$(ASAN_CFLAGS)
+  LDFLAGS+=$(ASAN_LDFLAGS)
+endif
+
+ifeq "$(shell echo '$(HASH)include <sys/ipc.h>@$(HASH)include <sys/shm.h>@int main() { int _id = shmget(IPC_PRIVATE, 65536, IPC_CREAT | IPC_EXCL | 0600); shmctl(_id, IPC_RMID, 0); return 0;}' | tr @ '\n' | $(CC) $(CFLAGS) -x c - -o .test2 2>/dev/null && echo 1 || echo 0 ; rm -f .test2 )" "1"
+	SHMAT_OK=1
+else
+	SHMAT_OK=0
+	CFLAGS+=-DUSEMMAP=1
+	LDFLAGS+=-Wno-deprecated-declarations
+endif
+
+ifeq "$(TEST_MMAP)" "1"
+	SHMAT_OK=0
+	CFLAGS+=-DUSEMMAP=1
+	LDFLAGS+=-Wno-deprecated-declarations
+endif
+
+all:	test_x86 test_shm test_python ready $(PROGS) afl-as test_build all_done
+
+man:    $(MANPAGES)
+
+tests:	source-only
+	@cd test ; ./test.sh
+	@rm -f test/errors
+
+performance-tests:	performance-test
+test-performance:	performance-test
+
+performance-test:	source-only
+	@cd test ; ./test-performance.sh
+
+
+# hint: make targets are also listed in the top level README.md
+help:
+	@echo "HELP --- the following make targets exist:"
+	@echo "=========================================="
+	@echo "all: just the main afl++ binaries"
+	@echo "binary-only: everything for binary-only fuzzing: qemu_mode, unicorn_mode, libdislocator, libtokencap, radamsa"
+	@echo "source-only: everything for source code fuzzing: llvm_mode, gcc_plugin, libdislocator, libtokencap, radamsa"
+	@echo "distrib: everything (for both binary-only and source code fuzzing)"
+	@echo "man: creates simple man pages from the help option of the programs"
+	@echo "install: installs everything you have compiled with the build option above"
+	@echo "clean: cleans everything compiled (not downloads when on a checkout)"
+	@echo "deepclean: cleans everything including downloads"
+	@echo "code-format: format the code, do this before you commit and send a PR please!"
+	@echo "tests: this runs the test framework. It is more catered for the developers, but if you run into problems this helps pinpointing the problem"
+	@echo "unit: perform unit tests (based on cmocka and GNU linker)"
+	@echo "document: creates afl-fuzz-document which will only do one run and save all manipulated inputs into out/queue/mutations"
+	@echo "help: shows these build options :-)"
+	@echo "=========================================="
+	@echo "Recommended: \"distrib\" or \"source-only\", then \"install\""
+	@echo
+	@echo Known build environment options:
+	@echo "=========================================="
+	@echo STATIC - compile AFL++ static
+	@echo ASAN_BUILD - compiles with memory sanitizer for debug purposes
+	@echo PROFILING - compile afl-fuzz with profiling information
+	@echo AFL_NO_X86 - if compiling on non-intel/amd platforms
+	@echo "=========================================="
+	@echo e.g.: make ASAN_BUILD=1
+
+ifndef AFL_NO_X86
+
+test_x86:
+	@echo "[*] Checking for the default compiler cc..."
+	@type $(CC) >/dev/null || ( echo; echo "Oops, looks like there is no compiler '"$(CC)"' in your path."; echo; echo "Don't panic! You can restart with '"$(_)" CC=<yourCcompiler>'."; echo; exit 1 )
+	@echo "[*] Checking for the ability to compile x86 code..."
+	@echo 'main() { __asm__("xorb %al, %al"); }' | $(CC) $(CFLAGS) -w -x c - -o .test1 || ( echo; echo "Oops, looks like your compiler can't generate x86 code."; echo; echo "Don't panic! You can use the LLVM or QEMU mode, but see docs/INSTALL first."; echo "(To ignore this error, set AFL_NO_X86=1 and try again.)"; echo; exit 1 )
+	@rm -f .test1
+
+else
+
+test_x86:
+	@echo "[!] Note: skipping x86 compilation checks (AFL_NO_X86 set)."
+
+endif
+
+
+ifeq "$(SHMAT_OK)" "1"
+
+test_shm:
+	@echo "[+] shmat seems to be working."
+	@rm -f .test2
+
+else
+
+test_shm:
+	@echo "[-] shmat seems not to be working, switching to mmap implementation"
+
+endif
+
+
+ifeq "$(PYTHON_OK)" "1"
+
+test_python:
+	@rm -f .test 2> /dev/null
+	@echo "[+] $(PYTHON_VERSION) support seems to be working."
+
+else
+
+test_python:
+	@echo "[-] You seem to need to install the package python3-dev, python2-dev or python-dev (and perhaps python[23]-apt), but it is optional so we continue"
+
+endif
+
+
+ready:
+	@echo "[+] Everything seems to be working, ready to compile."
+
+afl-gcc: src/afl-gcc.c $(COMM_HDR) | test_x86
+	$(CC) $(CFLAGS) src/$@.c -o $@ $(LDFLAGS)
+	set -e; for i in afl-g++ afl-clang afl-clang++; do ln -sf afl-gcc $$i; done
+
+afl-as: src/afl-as.c include/afl-as.h $(COMM_HDR) | test_x86
+	$(CC) $(CFLAGS) src/$@.c -o $@ $(LDFLAGS)
+	ln -sf afl-as as
+
+src/afl-common.o : $(COMM_HDR) src/afl-common.c include/common.h
+	$(CC) $(CFLAGS) $(CFLAGS_FLTO) -c src/afl-common.c -o src/afl-common.o
+
+src/afl-forkserver.o : $(COMM_HDR) src/afl-forkserver.c include/forkserver.h
+	$(CC) $(CFLAGS) $(CFLAGS_FLTO) -c src/afl-forkserver.c -o src/afl-forkserver.o
+
+src/afl-sharedmem.o : $(COMM_HDR) src/afl-sharedmem.c include/sharedmem.h
+	$(CC) $(CFLAGS) $(CFLAGS_FLTO) -c src/afl-sharedmem.c -o src/afl-sharedmem.o
+
+radamsa: src/third_party/libradamsa/libradamsa.so
+	cp src/third_party/libradamsa/libradamsa.so .
+
+src/third_party/libradamsa/libradamsa.so: src/third_party/libradamsa/libradamsa.c src/third_party/libradamsa/radamsa.h
+	$(MAKE) -C src/third_party/libradamsa/ CFLAGS="$(CFLAGS)"
+
+afl-fuzz: $(COMM_HDR) include/afl-fuzz.h $(AFL_FUZZ_FILES) src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o | test_x86
+	$(CC) $(CFLAGS) $(COMPILE_STATIC) $(CFLAGS_FLTO) $(AFL_FUZZ_FILES) src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o -o $@ $(PYFLAGS) $(LDFLAGS)
+
+afl-showmap: src/afl-showmap.c src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o $(COMM_HDR) | test_x86
+	$(CC) $(CFLAGS) $(COMPILE_STATIC) $(CFLAGS_FLTO) src/$@.c src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o -o $@ $(LDFLAGS)
+
+afl-tmin: src/afl-tmin.c src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o $(COMM_HDR) | test_x86
+	$(CC) $(CFLAGS) $(COMPILE_STATIC) $(CFLAGS_FLTO) src/$@.c src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o -o $@ $(LDFLAGS)
+
+afl-analyze: src/afl-analyze.c src/afl-common.o src/afl-sharedmem.o $(COMM_HDR) | test_x86
+	$(CC) $(CFLAGS) $(COMPILE_STATIC) $(CFLAGS_FLTO) src/$@.c src/afl-common.o src/afl-sharedmem.o -o $@ $(LDFLAGS)
+
+afl-gotcpu: src/afl-gotcpu.c src/afl-common.o $(COMM_HDR) | test_x86
+	$(CC) $(CFLAGS) $(COMPILE_STATIC) $(CFLAGS_FLTO) src/$@.c src/afl-common.o -o $@ $(LDFLAGS)
+
+
+# document all mutations and only do one run (use with only one input file!)
+document: $(COMM_HDR) include/afl-fuzz.h $(AFL_FUZZ_FILES) src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o | test_x86
+	$(CC) -D_AFL_DOCUMENT_MUTATIONS $(CFLAGS) $(CFLAGS_FLTO) $(AFL_FUZZ_FILES) src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o -o afl-fuzz-document $(PYFLAGS) $(LDFLAGS)
+
+test/unittests/unit_maybe_alloc.o : $(COMM_HDR) include/alloc-inl.h test/unittests/unit_maybe_alloc.c $(AFL_FUZZ_FILES)
+	@$(CC) $(CFLAGS) $(ASAN_CFLAGS) -c test/unittests/unit_maybe_alloc.c -o test/unittests/unit_maybe_alloc.o
+
+test/unittests/unit_preallocable.o : $(COMM_HDR) include/alloc-inl.h test/unittests/unit_preallocable.c $(AFL_FUZZ_FILES)
+	@$(CC) $(CFLAGS) $(ASAN_CFLAGS) -c test/unittests/unit_preallocable.c -o test/unittests/unit_preallocable.o
+
+unit_maybe_alloc: test/unittests/unit_maybe_alloc.o
+	@$(CC) $(CFLAGS) -Wl,--wrap=exit -Wl,--wrap=printf test/unittests/unit_maybe_alloc.o -o test/unittests/unit_maybe_alloc $(LDFLAGS) $(ASAN_LDFLAGS) -lcmocka
+	./test/unittests/unit_maybe_alloc
+
+test/unittests/unit_list.o : $(COMM_HDR) include/list.h test/unittests/unit_list.c $(AFL_FUZZ_FILES)
+	@$(CC) $(CFLAGS) $(ASAN_CFLAGS) -c test/unittests/unit_list.c -o test/unittests/unit_list.o
+
+unit_list: test/unittests/unit_list.o
+	@$(CC) $(CFLAGS) $(ASAN_CFLAGS) -Wl,--wrap=exit -Wl,--wrap=printf test/unittests/unit_list.o -o test/unittests/unit_list  $(LDFLAGS) $(ASAN_LDFLAGS) -lcmocka
+	./test/unittests/unit_list
+
+test/unittests/preallocable.o : $(COMM_HDR) include/afl-prealloc.h test/unittests/preallocable.c $(AFL_FUZZ_FILES)
+	@$(CC) $(CFLAGS) $(ASAN_CFLAGS) $(CFLAGS_FLTO) -c test/unittests/preallocable.c -o test/unittests/preallocable.o
+
+unit_preallocable: test/unittests/unit_preallocable.o
+	@$(CC) $(CFLAGS) $(ASAN_CFLAGS) -Wl,--wrap=exit -Wl,--wrap=printf test/unittests/unit_preallocable.o -o test/unittests/unit_preallocable $(LDFLAGS) $(ASAN_LDFLAGS) -lcmocka
+	./test/unittests/unit_preallocable
+
+unit_clean:
+	@rm -f ./test/unittests/unit_preallocable ./test/unittests/unit_list ./test/unittests/unit_maybe_alloc test/unittests/*.o
+
+ifneq "$(shell uname)" "Darwin"
+
+unit: unit_maybe_alloc unit_preallocable unit_list unit_clean
+
+else
+
+unit:
+	@echo [-] unit tests are skipped on Darwin \(lacks GNU linker feature --wrap\)
+
+endif
+
+code-format:
+	./.custom-format.py -i src/*.c
+	./.custom-format.py -i include/*.h
+	./.custom-format.py -i libdislocator/*.c
+	./.custom-format.py -i libtokencap/*.c
+	./.custom-format.py -i llvm_mode/*.c
+	./.custom-format.py -i llvm_mode/*.h
+	./.custom-format.py -i llvm_mode/*.cc
+	./.custom-format.py -i gcc_plugin/*.c
+	#./.custom-format.py -i gcc_plugin/*.h
+	./.custom-format.py -i gcc_plugin/*.cc
+	./.custom-format.py -i examples/*/*.c
+	./.custom-format.py -i examples/*/*.h
+	./.custom-format.py -i test/*.c
+	./.custom-format.py -i qemu_mode/patches/*.h
+	./.custom-format.py -i qemu_mode/libcompcov/*.c
+	./.custom-format.py -i qemu_mode/libcompcov/*.cc
+	./.custom-format.py -i qemu_mode/libcompcov/*.h
+	./.custom-format.py -i qbdi_mode/*.c
+	./.custom-format.py -i qbdi_mode/*.cpp
+	./.custom-format.py -i *.h
+	./.custom-format.py -i *.c
+
+
+ifndef AFL_NO_X86
+
+test_build: afl-gcc afl-as afl-showmap
+	@echo "[*] Testing the CC wrapper and instrumentation output..."
+	@unset AFL_USE_ASAN AFL_USE_MSAN AFL_CC; AFL_DEBUG=1 AFL_INST_RATIO=100 AFL_PATH=. ./$(TEST_CC) $(CFLAGS) test-instr.c -o test-instr $(LDFLAGS) 2>&1 | grep 'afl-as' >/dev/null || (echo "Oops, afl-as did not get called from "$(TEST_CC)". This is normally achieved by "$(CC)" honoring the -B option."; exit 1 )
+	ASAN_OPTIONS=detect_leaks=0 ./afl-showmap -m none -q -o .test-instr0 ./test-instr < /dev/null
+	echo 1 | ASAN_OPTIONS=detect_leaks=0 ./afl-showmap -m none -q -o .test-instr1 ./test-instr
+	@rm -f test-instr
+	@cmp -s .test-instr0 .test-instr1; DR="$$?"; rm -f .test-instr0 .test-instr1; if [ "$$DR" = "0" ]; then echo; echo "Oops, the instrumentation does not seem to be behaving correctly!"; echo; echo "Please post to https://github.com/AFLplusplus/AFLplusplus/issues to troubleshoot the issue."; echo; exit 1; fi
+	@echo "[+] All right, the instrumentation seems to be working!"
+
+else
+
+test_build: afl-gcc afl-as afl-showmap
+	@echo "[!] Note: skipping build tests (you may need to use LLVM or QEMU mode)."
+
+endif
+
+
+all_done: test_build
+	@if [ ! "`type clang 2>/dev/null`" = "" ]; then echo "[+] LLVM users: see llvm_mode/README.md for a faster alternative to afl-gcc."; fi
+	@echo "[+] All done! Be sure to review the README.md - it's pretty short and useful."
+	@if [ "`uname`" = "Darwin" ]; then printf "\nWARNING: Fuzzing on MacOS X is slow because of the unusually high overhead of\nfork() on this OS. Consider using Linux or *BSD. You can also use VirtualBox\n(virtualbox.org) to put AFL inside a Linux or *BSD VM.\n\n"; fi
+	@! tty <&1 >/dev/null || printf "\033[0;30mNOTE: If you can read this, your terminal probably uses white background.\nThis will make the UI hard to read. See docs/status_screen.md for advice.\033[0m\n" 2>/dev/null
+
+.NOTPARALLEL: clean all
+
+clean:
+	rm -f $(PROGS) libradamsa.so afl-fuzz-document afl-as as afl-g++ afl-clang afl-clang++ *.o src/*.o *~ a.out core core.[1-9][0-9]* *.stackdump .test .test1 .test2 test-instr .test-instr0 .test-instr1 afl-qemu-trace afl-gcc-fast afl-gcc-pass.so afl-gcc-rt.o afl-g++-fast ld *.so *.8 test/unittests/*.o test/unittests/unit_maybe_alloc test/unittests/preallocable .afl-*
+	rm -rf out_dir qemu_mode/qemu-3.1.1 *.dSYM */*.dSYM
+	-$(MAKE) -C llvm_mode clean
+	-$(MAKE) -C gcc_plugin clean
+	$(MAKE) -C libdislocator clean
+	$(MAKE) -C libtokencap clean
+	$(MAKE) -C examples/afl_network_proxy clean
+	$(MAKE) -C examples/socket_fuzzing clean
+	$(MAKE) -C examples/argv_fuzzing clean
+	$(MAKE) -C qemu_mode/unsigaction clean
+	$(MAKE) -C qemu_mode/libcompcov clean
+	$(MAKE) -C src/third_party/libradamsa/ clean
+	rm -rf qemu_mode/qemu-3.1.1
+ifeq "$(IN_REPO)" "1"
+	test -d unicorn_mode/unicornafl && $(MAKE) -C unicorn_mode/unicornafl clean || true
+else
+	rm -rf qemu_mode/qemu-3.1.1.tar.xz
+	rm -rf unicorn_mode/unicornafl
+endif
+
+deepclean:	clean
+	rm -rf qemu_mode/qemu-3.1.1.tar.xz
+	rm -rf unicorn_mode/unicornafl
+	git reset --hard >/dev/null 2>&1 || true
+
+distrib: all radamsa
+	-$(MAKE) -C llvm_mode
+	-$(MAKE) -C gcc_plugin
+	$(MAKE) -C libdislocator
+	$(MAKE) -C libtokencap
+	$(MAKE) -C examples/afl_network_proxy
+	$(MAKE) -C examples/socket_fuzzing
+	$(MAKE) -C examples/argv_fuzzing
+	cd qemu_mode && sh ./build_qemu_support.sh
+	cd unicorn_mode && sh ./build_unicorn_support.sh
+
+binary-only: all radamsa
+	$(MAKE) -C libdislocator
+	$(MAKE) -C libtokencap
+	$(MAKE) -C examples/afl_network_proxy
+	$(MAKE) -C examples/socket_fuzzing
+	$(MAKE) -C examples/argv_fuzzing
+	cd qemu_mode && sh ./build_qemu_support.sh
+	cd unicorn_mode && sh ./build_unicorn_support.sh
+
+source-only: all radamsa
+	-$(MAKE) -C llvm_mode
+	-$(MAKE) -C gcc_plugin
+	$(MAKE) -C libdislocator
+	$(MAKE) -C libtokencap
+	#$(MAKE) -C examples/afl_network_proxy
+	#$(MAKE) -C examples/socket_fuzzing
+	#$(MAKE) -C examples/argv_fuzzing
+
+%.8:	%
+	@echo .TH $* 8 $(BUILD_DATE) "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 >> $@
+	@./$* -hh 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 \"hexcoder-\" Eissfeldt <heiko.eissfeldt@hexco.de>, Andrea Fioraldi <andreafioraldi@gmail.com> and Dominik Maier <domenukk@gmail.com>" >> $@
+	@echo  The homepage of afl++ is: https://github.com/AFLplusplus/AFLplusplus >> $@
+	@echo >> $@
+	@echo .SH LICENSE >> $@
+	@echo Apache License Version 2.0, January 2004 >> $@
+
+install: all $(MANPAGES)
+	install -d -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)
+	rm -f $${DESTDIR}$(BIN_PATH)/afl-as
+	if [ -f afl-qemu-trace ]; then install -m 755 afl-qemu-trace $${DESTDIR}$(BIN_PATH); fi
+	if [ -f afl-gcc-fast ]; then set e; install -m 755 afl-gcc-fast $${DESTDIR}$(BIN_PATH); ln -sf afl-gcc-fast $${DESTDIR}$(BIN_PATH)/afl-g++-fast; install -m 755 afl-gcc-pass.so afl-gcc-rt.o $${DESTDIR}$(HELPER_PATH); fi
+	if [ -f afl-clang-fast ]; then $(MAKE) -C llvm_mode install; fi
+	if [ -f libdislocator.so ]; then set -e; install -m 755 libdislocator.so $${DESTDIR}$(HELPER_PATH); fi
+	if [ -f libtokencap.so ]; then set -e; install -m 755 libtokencap.so $${DESTDIR}$(HELPER_PATH); fi
+	if [ -f libcompcov.so ]; then set -e; install -m 755 libcompcov.so $${DESTDIR}$(HELPER_PATH); fi
+	if [ -f libradamsa.so ]; then set -e; install -m 755 libradamsa.so $${DESTDIR}$(HELPER_PATH); fi
+	if [ -f afl-fuzz-document ]; then set -e; install -m 755 afl-fuzz-document $${DESTDIR}$(BIN_PATH); fi
+	if [ -f socketfuzz32.so -o -f socketfuzz64.so ]; then $(MAKE) -C examples/socket_fuzzing install; fi
+	if [ -f argvfuzz32.so -o -f argvfuzz64.so ]; then $(MAKE) -C examples/argv_fuzzing install; fi
+	if [ -f examples/afl_network_proxy/afl-network-server ]; then $(MAKE) -C examples/afl_network_proxy install; 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 ${DESTDIR}$(MAN_PATH)
+	install -m0644 *.8 ${DESTDIR}$(MAN_PATH)
+
+	install -m 755 afl-as $${DESTDIR}$(HELPER_PATH)
+	ln -sf afl-as $${DESTDIR}$(HELPER_PATH)/as
+	install -m 644 docs/*.md $${DESTDIR}$(DOC_PATH)
+	cp -r testcases/ $${DESTDIR}$(MISC_PATH)
+	cp -r dictionaries/ $${DESTDIR}$(MISC_PATH)

Makefile

@@ -1,230 +1,42 @@
-#
-# american fuzzy lop - makefile
-# -----------------------------
-#
-# Written and maintained by Michal Zalewski <lcamtuf@google.com>
-# 
-# Copyright 2013, 2014, 2015, 2016, 2017 Google Inc. All rights reserved.
-# 
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-# 
-#   http://www.apache.org/licenses/LICENSE-2.0
-#
+all:
+	@echo trying to use GNU make...
+	@gmake all
 
-# For Heiko:
-#TEST_MMAP=1
+source-only:
+	@gmake source-only
 
-PROGNAME    = afl
-VERSION     = $(shell grep '^\#define VERSION ' config.h | cut -d '"' -f2)
+binary-only:
+	@gmake binary-only
 
-PREFIX     ?= /usr/local
-BIN_PATH    = $(PREFIX)/bin
-HELPER_PATH = $(PREFIX)/lib/afl
-DOC_PATH    = $(PREFIX)/share/doc/afl
-MISC_PATH   = $(PREFIX)/share/afl
+distrib:
+	@gmake distrib
 
-# PROGS intentionally omit afl-as, which gets installed elsewhere.
+man:
+	@gmake man
 
-PROGS       = afl-gcc afl-fuzz afl-showmap afl-tmin afl-gotcpu afl-analyze
-SH_PROGS    = afl-plot afl-cmin afl-whatsup afl-system-config
+install:
+	@gmake install
 
-CFLAGS     ?= -O3 -funroll-loops
-CFLAGS     += -Wall -D_FORTIFY_SOURCE=2 -g -Wno-pointer-sign \
-	      -DAFL_PATH=\"$(HELPER_PATH)\" -DDOC_PATH=\"$(DOC_PATH)\" \
-	      -DBIN_PATH=\"$(BIN_PATH)\"
+document:
+	@gmake document
 
-PYTHON_INCLUDE	?= /usr/include/python2.7
+deepclean:
+	@gmake deepclean
 
-ifneq "$(filter Linux GNU%,$(shell uname))" ""
-  LDFLAGS  += -ldl
-endif
+code-format:
+	@gmake code-format
 
-ifeq "$(findstring clang, $(shell $(CC) --version 2>/dev/null))" ""
-  TEST_CC   = afl-gcc
-else
-  TEST_CC   = afl-clang
-endif
+help:
+	@gmake help
 
-COMM_HDR    = alloc-inl.h config.h debug.h types.h
+tests:
+	@gmake tests
 
+unit:
+	@gmake unit
 
-ifeq "$(shell echo '\#include <Python.h>@int main() {return 0; }' | tr @ '\n' | $(CC) -x c - -o .test -I$(PYTHON_INCLUDE) -lpython2.7 2>/dev/null && echo 1 || echo 0 )" "1"
-	PYTHON_OK=1
-	PYFLAGS=-DUSE_PYTHON -I$(PYTHON_INCLUDE) -lpython2.7
-else
-	PYTHON_OK=0
-	PYFLAGS=
-endif
-
-
-ifeq "$(shell echo '\#include <sys/ipc.h>@\#include <sys/shm.h>@int main() { int _id = shmget(IPC_PRIVATE, 65536, IPC_CREAT | IPC_EXCL | 0600); shmctl(_id, IPC_RMID, 0); return 0;}' | tr @ '\n' | $(CC) -x c - -o .test2 2>/dev/null && echo 1 || echo 0 )" "1"
-	SHMAT_OK=1
-else
-	SHMAT_OK=0
-	CFLAGS+=-DUSEMMAP=1
-	LDFLAGS+=-Wno-deprecated-declarations -lrt
-endif
-
-ifeq "$(TEST_MMAP)" "1"
-	SHMAT_OK=0
-	CFLAGS+=-DUSEMMAP=1
-	LDFLAGS+=-Wno-deprecated-declarations -lrt
-endif
-
-
-all:	test_x86 test_shm test_python27 ready $(PROGS) afl-as test_build all_done
-
-
-ifndef AFL_NO_X86
-
-test_x86:
-	@echo "[*] Checking for the ability to compile x86 code..."
-	@echo 'main() { __asm__("xorb %al, %al"); }' | $(CC) -w -x c - -o .test1 || ( echo; echo "Oops, looks like your compiler can't generate x86 code."; echo; echo "Don't panic! You can use the LLVM or QEMU mode, but see docs/INSTALL first."; echo "(To ignore this error, set AFL_NO_X86=1 and try again.)"; echo; exit 1 )
-	@rm -f .test1
-
-else
-
-test_x86:
-	@echo "[!] Note: skipping x86 compilation checks (AFL_NO_X86 set)."
-
-endif
-
-
-ifeq "$(SHMAT_OK)" "1"
-
-test_shm:
-	@echo "[+] shmat seems to be working."
-	@rm -f .test2
-
-else
-
-test_shm:
-	@echo "[-] shmat seems not to be working, switching to mmap implementation"
-
-endif
-
-
-ifeq "$(PYTHON_OK)" "1"
-
-test_python27:
-	@rm -f .test 2> /dev/null
-	@echo "[+] Python 2.7 support seems to be working."
-
-else
-
-test_python27:
-	@echo "[-] You seem to need to install the package python2.7-dev, but it is optional so we continue"
-
-endif
-
-
-ready:
-	@echo "[+] Everything seems to be working, ready to compile."
-
-afl-gcc: afl-gcc.c $(COMM_HDR) | test_x86
-	$(CC) $(CFLAGS) $@.c -o $@ $(LDFLAGS)
-	set -e; for i in afl-g++ afl-clang afl-clang++; do ln -sf afl-gcc $$i; done
-
-afl-as: afl-as.c afl-as.h $(COMM_HDR) | test_x86
-	$(CC) $(CFLAGS) $@.c -o $@ $(LDFLAGS)
-	ln -sf afl-as as
-
-afl-common.o : afl-common.c
-	$(CC) $(CFLAGS) -c afl-common.c
-
-sharedmem.o : sharedmem.c
-	$(CC) $(CFLAGS) -c sharedmem.c
-
-afl-fuzz: afl-fuzz.c afl-common.o sharedmem.o $(COMM_HDR) | test_x86
-	$(CC) $(CFLAGS) $@.c afl-common.o sharedmem.o -o $@ $(LDFLAGS) $(PYFLAGS)
-
-afl-showmap: afl-showmap.c afl-common.o sharedmem.o $(COMM_HDR) | test_x86
-	$(CC) $(CFLAGS) $@.c afl-common.o sharedmem.o -o $@ $(LDFLAGS)
-
-afl-tmin: afl-tmin.c afl-common.o sharedmem.o $(COMM_HDR) | test_x86
-	$(CC) $(CFLAGS) $@.c afl-common.o sharedmem.o -o $@ $(LDFLAGS)
-
-afl-analyze: afl-analyze.c afl-common.o sharedmem.o $(COMM_HDR) | test_x86
-	$(CC) $(CFLAGS) $@.c afl-common.o sharedmem.o -o $@ $(LDFLAGS)
-
-afl-gotcpu: afl-gotcpu.c $(COMM_HDR) | test_x86
-	$(CC) $(CFLAGS) $@.c -o $@ $(LDFLAGS)
-
-
-ifndef AFL_NO_X86
-
-test_build: afl-gcc afl-as afl-showmap
-	@echo "[*] Testing the CC wrapper and instrumentation output..."
-	unset AFL_USE_ASAN AFL_USE_MSAN; AFL_QUIET=1 AFL_INST_RATIO=100 AFL_PATH=. ./$(TEST_CC) $(CFLAGS) test-instr.c -o test-instr $(LDFLAGS)
-	echo 0 | ./afl-showmap -m none -q -o .test-instr0 ./test-instr
-	echo 1 | ./afl-showmap -m none -q -o .test-instr1 ./test-instr
-	@rm -f test-instr
-	@cmp -s .test-instr0 .test-instr1; DR="$$?"; rm -f .test-instr0 .test-instr1; if [ "$$DR" = "0" ]; then echo; echo "Oops, the instrumentation does not seem to be behaving correctly!"; echo; echo "Please ping <lcamtuf@google.com> to troubleshoot the issue."; echo; exit 1; fi
-	@echo "[+] All right, the instrumentation seems to be working!"
-
-else
-
-test_build: afl-gcc afl-as afl-showmap
-	@echo "[!] Note: skipping build tests (you may need to use LLVM or QEMU mode)."
-
-endif
-
-
-all_done: test_build
-	@if [ ! "`which clang 2>/dev/null`" = "" ]; then echo "[+] LLVM users: see llvm_mode/README.llvm for a faster alternative to afl-gcc."; fi
-	@echo "[+] All done! Be sure to review the README.md - it's pretty short and useful."
-	@if [ "`uname`" = "Darwin" ]; then printf "\nWARNING: Fuzzing on MacOS X is slow because of the unusually high overhead of\nfork() on this OS. Consider using Linux or *BSD. You can also use VirtualBox\n(virtualbox.org) to put AFL inside a Linux or *BSD VM.\n\n"; fi
-	@! tty <&1 >/dev/null || printf "\033[0;30mNOTE: If you can read this, your terminal probably uses white background.\nThis will make the UI hard to read. See docs/status_screen.txt for advice.\033[0m\n" 2>/dev/null
-
-.NOTPARALLEL: clean
+unit_clean:
+	@gmake unit_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 -rf out_dir qemu_mode/qemu-3.1.0
-	$(MAKE) -C llvm_mode clean
-	$(MAKE) -C libdislocator clean
-	$(MAKE) -C libtokencap clean
-
-install: all
-	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)
-	rm -f $${DESTDIR}$(BIN_PATH)/afl-as
-	if [ -f afl-qemu-trace ]; then install -m 755 afl-qemu-trace $${DESTDIR}$(BIN_PATH); fi
-	#if [ -f afl-gcc-fast ]; then set e; install -m 755 afl-gcc-fast $${DESTDIR}$(BIN_PATH); ln -sf afl-gcc-fast $${DESTDIR}$(BIN_PATH)/afl-g++-fast; install -m 755 afl-gcc-pass.so afl-gcc-rt.o $${DESTDIR}$(HELPER_PATH); fi
-ifndef AFL_TRACE_PC
-	if [ -f afl-clang-fast -a -f libLLVMInsTrim.so -a -f afl-llvm-rt.o ]; then set -e; install -m 755 afl-clang-fast $${DESTDIR}$(BIN_PATH); ln -sf afl-clang-fast $${DESTDIR}$(BIN_PATH)/afl-clang-fast++; install -m 755 libLLVMInsTrim.so afl-llvm-pass.so afl-llvm-rt.o $${DESTDIR}$(HELPER_PATH); fi
-else
-	if [ -f afl-clang-fast -a -f afl-llvm-rt.o ]; then set -e; install -m 755 afl-clang-fast $${DESTDIR}$(BIN_PATH); ln -sf afl-clang-fast $${DESTDIR}$(BIN_PATH)/afl-clang-fast++; install -m 755 afl-llvm-rt.o $${DESTDIR}$(HELPER_PATH); fi
-endif
-	if [ -f afl-llvm-rt-32.o ]; then set -e; install -m 755 afl-llvm-rt-32.o $${DESTDIR}$(HELPER_PATH); fi
-	if [ -f afl-llvm-rt-64.o ]; then set -e; install -m 755 afl-llvm-rt-64.o $${DESTDIR}$(HELPER_PATH); fi
-	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
-
-	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
-
-	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)
-	cp -r testcases/ $${DESTDIR}$(MISC_PATH)
-	cp -r dictionaries/ $${DESTDIR}$(MISC_PATH)
-
-publish: clean
-#	test "`basename $$PWD`" = "afl" || exit 1
-#	test -f ~/www/afl/releases/$(PROGNAME)-$(VERSION).tgz; if [ "$$?" = "0" ]; then echo; echo "Change program version in config.h, mmkay?"; echo; exit 1; fi
-#	cd ..; rm -rf $(PROGNAME)-$(VERSION); cp -pr $(PROGNAME) $(PROGNAME)-$(VERSION); \
-#	  tar -cvz -f ~/www/afl/releases/$(PROGNAME)-$(VERSION).tgz $(PROGNAME)-$(VERSION)
-#	chmod 644 ~/www/afl/releases/$(PROGNAME)-$(VERSION).tgz
-#	( cd ~/www/afl/releases/; ln -s -f $(PROGNAME)-$(VERSION).tgz $(PROGNAME)-latest.tgz )
-#	cat docs/README.md >~/www/afl/README.txt
-#	cat docs/status_screen.txt >~/www/afl/status_screen.txt
-#	cat docs/historical_notes.txt >~/www/afl/historical_notes.txt
-#	cat docs/technical_details.txt >~/www/afl/technical_details.txt
-#	cat docs/ChangeLog >~/www/afl/ChangeLog.txt
-#	cat docs/QuickStartGuide.txt >~/www/afl/QuickStartGuide.txt
-#	echo -n "$(VERSION)" >~/www/afl/version.txt
+	@gmake clean

PATCHES

@@ -1 +0,0 @@
-docs/PATCHES

QuickStartGuide.md

@@ -0,0 +1 @@
+docs/QuickStartGuide.md

QuickStartGuide.txt

@@ -1 +0,0 @@
-docs/QuickStartGuide.txt

README.md

@@ -1,49 +1,202 @@
 # american fuzzy lop plus plus (afl++)
 
+  <img align="right" src="https://raw.githubusercontent.com/andreafioraldi/AFLplusplus-website/master/static/logo_256x256.png" alt="AFL++ Logo">
+
+  ![Travis State](https://api.travis-ci.com/AFLplusplus/AFLplusplus.svg?branch=master)
+
+  Release Version: [2.65c](https://github.com/AFLplusplus/AFLplusplus/releases)
+
+  Github Version: 2.65d
+
+  includes all necessary/interesting changes from Google's afl 2.56b
+
   Originally developed by Michal "lcamtuf" Zalewski.
 
-  Repository: [https://github.com/vanhauser-thc/AFLplusplus](https://github.com/vanhauser-thc/AFLplusplus)
+  Repository: [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus)
 
-  afl++ is maintained by Marc Heuse <mh@mh-sec.de>, Heiko Eissfeldt
-  <heiko.eissfeldt@hexco.de> and Andrea Fioraldi <andreafioraldi@gmail.com>.
+  afl++ is maintained by:
+    * Marc "van Hauser" Heuse <mh@mh-sec.de>,
+    * Heiko "hexcoder-" Eißfeldt <heiko.eissfeldt@hexco.de>,
+    * Andrea Fioraldi <andreafioraldi@gmail.com> and
+    * Dominik Maier <mail@dmnk.co>.
+
+  Note that although afl now has a Google afl repository [https://github.com/Google/afl](https://github.com/Google/afl),
+  it is unlikely to receive any notable enhancements: [https://twitter.com/Dor3s/status/1154737061787660288](https://twitter.com/Dor3s/status/1154737061787660288)
 
 ## The enhancements compared to the original stock afl
 
   Many improvements were made over the official afl release - which did not
-  get any improvements since November 2017.
+  get any feature improvements since November 2017.
 
-  Among others afl++ has, e.g. more performant llvm_mode, supporting
-  llvm up to version 8, Qemu 3.1, more speed and crashfixes for Qemu,
-  laf-intel feature for Qemu (with libcompcov) and more.
+  Among other changes afl++ has a more performant llvm_mode, supports
+  llvm up to version 11, QEMU 3.1, more speed and crashfixes for QEMU,
+  better *BSD and Android support and much, much more.
 
-  Additionally the following patches have been integrated:
+  Additionally the following features and patches have been integrated:
 
-  * AFLfast's power schedules by Marcel Boehme: [https://github.com/mboehme/aflfast](https://github.com/mboehme/aflfast)
+  * AFLfast's power schedules by Marcel Böhme: [https://github.com/mboehme/aflfast](https://github.com/mboehme/aflfast)
 
-  * C. Hollers afl-fuzz Python mutator module and llvm_mode whitelist support: [https://github.com/choller/afl](https://github.com/choller/afl)
+  * The new excellent MOpt mutator: [https://github.com/puppet-meteor/MOpt-AFL](https://github.com/puppet-meteor/MOpt-AFL)
 
-  * the new excellent MOpt mutator: [https://github.com/puppet-meteor/MOpt-AFL](https://github.com/puppet-meteor/MOpt-AFL)
+  * InsTrim, a very effective CFG llvm_mode instrumentation implementation for large targets: [https://github.com/csienslab/instrim](https://github.com/csienslab/instrim)
 
-  * instrim, a very effective CFG llvm_mode instrumentation implementation for large targets: [https://github.com/csienslab/instrim](https://github.com/csienslab/instrim)
+  * C. Holler's afl-fuzz Python mutator module and llvm_mode whitelist support: [https://github.com/choller/afl](https://github.com/choller/afl)
 
-  * unicorn_mode which allows fuzzing of binaries from completely different platforms (integration provided by domenukk)
+  * Custom mutator by a library (instead of Python) by kyakdan
+
+  * Unicorn mode which allows fuzzing of binaries from completely different platforms (integration provided by domenukk)
+
+  * LAF-Intel or CompCov support for llvm_mode, qemu_mode and unicorn_mode
+
+  * NeverZero patch for afl-gcc, llvm_mode, qemu_mode and unicorn_mode which prevents a wrapping map value to zero, increases coverage
+  
+  * Persistent mode and deferred forkserver for qemu_mode
+  
+  * Win32 PE binary-only fuzzing with QEMU and Wine
+
+  * Radamsa mutator (enable with `-R` to add or `-RR` to run it exclusively).
+
+  * QBDI mode to fuzz android native libraries via QBDI framework
+
+  * The new CmpLog instrumentation for LLVM and QEMU inspired by [Redqueen](https://www.syssec.ruhr-uni-bochum.de/media/emma/veroeffentlichungen/2018/12/17/NDSS19-Redqueen.pdf)
+
+  * LLVM mode Ngram coverage by Adrian Herrera [https://github.com/adrianherrera/afl-ngram-pass](https://github.com/adrianherrera/afl-ngram-pass)
 
   A more thorough list is available in the PATCHES file.
 
-  So all in all this is the best-of AFL that is currently out there :-)
+  | Feature/Instrumentation | afl-gcc | llvm_mode | gcc_plugin | qemu_mode        | unicorn_mode |
+  | ----------------------- |:-------:|:---------:|:----------:|:----------------:|:------------:|
+  | NeverZero               |    x    |     x(1)  |      (2)   |         x        |       x      |
+  | Persistent mode         |         |     x     |     x      | x86[_64]/arm[64] |       x      |
+  | LAF-Intel / CompCov     |         |     x     |            | x86[_64]/arm[64] | x86[_64]/arm |
+  | CmpLog                  |         |     x     |            | x86[_64]/arm[64] |              |
+  | Whitelist               |         |     x     |     x      |        (x)(3)    |              |
+  | Non-colliding coverage  |         |     x(4)  |            |        (x)(5)    |              |
+  | InsTrim                 |         |     x     |            |                  |              |
+  | Ngram prev_loc coverage |         |     x(6)  |            |                  |              |
+  | Context coverage        |         |     x     |            |                  |              |
+  | Snapshot LKM support    |         |     x     |            |        (x)(5)    |              |
+
+  neverZero:
+
+  (1) default for LLVM >= 9.0, env var for older version due an efficiency bug in llvm <= 8
+
+  (2) GCC creates non-performant code, hence it is disabled in gcc_plugin
+
+  (3) partially via AFL_CODE_START/AFL_CODE_END
+
+  (4) Only for LLVM >= 11 and not all targets compile
+
+  (5) upcoming, development in the branch
+
+  (6) not compatible with LTO and InsTrim and needs at least LLVM >= 4.1
+
+  So all in all this is the best-of afl that is currently out there :-)
 
   For new versions and additional information, check out:
-  [https://github.com/vanhauser-thc/AFLplusplus](https://github.com/vanhauser-thc/AFLplusplus)
+  [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus)
 
   To compare notes with other users or get notified about major new features,
   send a mail to <afl-users+subscribe@googlegroups.com>.
 
-  See [docs/QuickStartGuide.txt](docs/QuickStartGuide.txt) if you don't have time to
+  See [docs/QuickStartGuide.md](docs/QuickStartGuide.md) if you don't have time to
   read this file.
 
+## Branches
 
-## 1) Challenges of guided fuzzing
--------------------------------
+  The following branches exist:
+
+  * [master/trunk](https://github.com/AFLplusplus/AFLplusplus/) : stable state of afl++ - it is synced from dev from time to
+    time when we are satisfied with it's stability
+  * [dev](https://github.com/AFLplusplus/AFLplusplus/tree/dev) : development state of afl++ - bleeding edge and you might catch a
+    checkout which does not compile or has a bug. *We only accept PRs in dev!!*
+  * (any other) : experimental branches to work on specific features or testing
+    new functionality or changes.
+
+  For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab.
+
+## Google Summer of Code 2020 (and any other students and enthusiast developers)
+
+We are happy to be part of [Google Summer of Code 2020](https://summerofcode.withgoogle.com/organizations/5100744400699392/)! :-)
+
+We have several ideas we would like to see in AFL++ to make it even better.
+However, we already work on so many things that we do not have the time for
+all the big ideas.
+
+This can be your way to support and contribute to AFL++ - extend it to
+something cool.
+
+We have an idea list in [docs/ideas.md](docs/ideas.md).
+
+For everyone who wants to contribute (and send pull requests) please read
+[CONTRIBUTING.md](CONTRIBUTING.md) before your submit.
+
+## Building and installing afl++
+
+afl++ has many build options.
+The easiest is to build and install everything:
+
+```shell
+$ sudo apt install build-essential libtool-bin python3-dev automake flex bison libglib2.0-dev libpixman-1-dev clang python3-setuptools llvm
+$ make distrib
+$ sudo make install
+```
+
+Note that "make distrib" also builds llvm_mode, qemu_mode, unicorn_mode and
+more. If you just want plain afl then do "make all", however compiling and
+using at least llvm_mode is highly recommended for much better results -
+hence in this case
+
+```shell
+$ make source-only
+```
+is what you should choose.
+
+These build targets exist:
+
+* all: just the main afl++ binaries
+* binary-only: everything for binary-only fuzzing: qemu_mode, unicorn_mode, libdislocator, libtokencap, radamsa
+* source-only: everything for source code fuzzing: llvm_mode, libdislocator, libtokencap, radamsa
+* distrib: everything (for both binary-only and source code fuzzing)
+* man: creates simple man pages from the help option of the programs
+* install: installs everything you have compiled with the build options above
+* clean: cleans everything compiled, not downloads (unless not on a checkout)
+* deepclean: cleans everything including downloads
+* code-format: format the code, do this before you commit and send a PR please!
+* tests: runs test cases to ensure that all features are still working as they should
+* unit: perform unit tests (based on cmocka)
+* help: shows these build options
+
+[Unless you are on Mac OS X](https://developer.apple.com/library/archive/qa/qa1118/_index.html) you can also build statically linked versions of the 
+afl++ binaries by passing the STATIC=1 argument to make:
+
+```shell
+$ make all STATIC=1
+```
+
+These build options exist:
+
+* STATIC - compile AFL++ static
+* ASAN_BUILD - compiles with memory sanitizer for debug purposes
+* PROFILING - compile with profiling information (gprof)
+* NO_PYTHON - disable python support
+* AFL_NO_X86 - if compiling on non-intel/amd platforms
+* LLVM_CONFIG - if your distro doesn't use the standard name for llvm-config (e.g. Debian)
+
+e.g.: make ASAN_BUILD=1
+
+
+Note that afl++ is faster and better the newer the compilers used are.
+Hence at least gcc-9 and especially llvm-9 should be the compilers of choice.
+If your distribution does not have them, you can use the Dockerfile:
+
+```shell
+$ cd AFLplusplus
+$ sudo docker build -t aflplusplus .
+```
+
+
+## Challenges of guided fuzzing
 
 Fuzzing is one of the most powerful and proven strategies for identifying
 security issues in real-world software; it is responsible for the vast
@@ -58,9 +211,9 @@ There have been numerous attempts to solve this problem. One of the early
 approaches - pioneered by Tavis Ormandy - is corpus distillation. The method
 relies on coverage signals to select a subset of interesting seeds from a
 massive, high-quality corpus of candidate files, and then fuzz them by
-traditional means. The approach works exceptionally well, but requires such
+traditional means. The approach works exceptionally well but requires such
 a corpus to be readily available. In addition, block coverage measurements
-provide only a very simplistic understanding of program state, and are less
+provide only a very simplistic understanding of the program state and are less
 useful for guiding the fuzzing effort in the long haul.
 
 Other, more sophisticated research has focused on techniques such as program
@@ -70,7 +223,7 @@ to suffer from reliability and performance problems in practical uses - and
 currently do not offer a viable alternative to "dumb" fuzzing techniques.
 
 
-## 2) The afl-fuzz approach
+## The afl-fuzz approach
 
 American Fuzzy Lop is a brute-force fuzzer coupled with an exceedingly simple
 but rock-solid instrumentation-guided genetic algorithm. It uses a modified
@@ -81,7 +234,7 @@ Simplifying a bit, the overall algorithm can be summed up as:
 
   1) Load user-supplied initial test cases into the queue,
 
-  2) Take next input file from the queue,
+  2) Take the next input file from the queue,
 
   3) Attempt to trim the test case to the smallest size that doesn't alter
      the measured behavior of the program,
@@ -109,12 +262,12 @@ The fuzzer is thoroughly tested to deliver out-of-the-box performance far
 superior to blind fuzzing or coverage-only tools.
 
 
-## 3) Instrumenting programs for use with AFL
+## Instrumenting programs for use with AFL
 
 PLEASE NOTE: llvm_mode compilation with afl-clang-fast/afl-clang-fast++
-instead of afl-gcc/afl-g++ is much faster and has a few cool features.
+instead of afl-gcc/afl-g++ is much faster and has many cool features.
 See llvm_mode/ - however few code does not compile with llvm.
-We support llvm versions 4.0 to 8.
+We support llvm versions 3.8.0 to 11.
 
 When source code is available, instrumentation can be injected by a companion
 tool that works as a drop-in replacement for gcc or clang in any standard build
@@ -136,19 +289,19 @@ For C++ programs, you'd would also want to set `CXX=/path/to/afl/afl-g++`.
 
 The clang wrappers (afl-clang and afl-clang++) can be used in the same way;
 clang users may also opt to leverage a higher-performance instrumentation mode,
-as described in [llvm_mode/README.llvm](llvm_mode/README.llvm).
-Clang/LLVM has a much better performance and works with LLVM version 4.0 to 8.
+as described in [llvm_mode/README.md](llvm_mode/README.md).
+Clang/LLVM has a much better performance and works with LLVM version 3.8.0 to 11.
 
 Using the LAF Intel performance enhancements are also recommended, see 
-[llvm_mode/README.laf-intel](llvm_mode/README.laf-intel)
+[llvm_mode/README.laf-intel.md](llvm_mode/README.laf-intel.md)
 
 Using partial instrumentation is also recommended, see
-[llvm_mode/README.whitelist](llvm_mode/README.whitelist)
+[llvm_mode/README.whitelist.md](llvm_mode/README.whitelist.md)
 
 When testing libraries, you need to find or write a simple program that reads
 data from stdin or from a file and passes it to the tested library. In such a
 case, it is essential to link this executable against a static version of the
-instrumented library, or to make sure that the correct .so file is loaded at
+instrumented library or to make sure that the correct .so file is loaded at
 runtime (usually by setting `LD_LIBRARY_PATH`). The simplest option is a static
 build, usually possible via:
 
@@ -159,14 +312,13 @@ $ CC=/path/to/afl/afl-gcc ./configure --disable-shared
 Setting `AFL_HARDEN=1` when calling 'make' will cause the CC wrapper to
 automatically enable code hardening options that make it easier to detect
 simple memory bugs. Libdislocator, a helper library included with AFL (see
-[libdislocator/README.dislocator](libdislocator/README.dislocator)) can help uncover heap corruption issues, too.
+[libdislocator/README.md](libdislocator/README.md)) can help uncover heap corruption issues, too.
 
-PS. ASAN users are advised to review [docs/notes_for_asan.txt](docs/notes_for_asan.txt)
+PS. ASAN users are advised to review [docs/notes_for_asan.md](docs/notes_for_asan.md)
 file for important caveats.
 
 
-## 4) Instrumenting binary-only apps
----------------------------------
+## Instrumenting binary-only apps
 
 When source code is *NOT* available, the fuzzer offers experimental support for
 fast, on-the-fly instrumentation of black-box binaries. This is accomplished
@@ -180,25 +332,41 @@ $ cd qemu_mode
 $ ./build_qemu_support.sh
 ```
 
-For additional instructions and caveats, see [qemu_mode/README.qemu](qemu_mode/README.qemu).
+For additional instructions and caveats, see [qemu_mode/README.md](qemu_mode/README.md).
+
+If possible you should use the persistent mode, see [qemu_mode/README.persistent.md](qemu_mode/README.persistent.md).
 
 The mode is approximately 2-5x slower than compile-time instrumentation, is
-less conductive to parallelization, and may have some other quirks.
+less conducive to parallelization, and may have some other quirks.
 
 If [afl-dyninst](https://github.com/vanhauser-thc/afl-dyninst) works for
 your binary, then you can use afl-fuzz normally and it will have twice
 the speed compared to qemu_mode.
 
 A more comprehensive description of these and other options can be found in
-[docs/binaryonly_fuzzing.txt](docs/binaryonly_fuzzing.txt)
+[docs/binaryonly_fuzzing.md](docs/binaryonly_fuzzing.md)
 
+## Good examples and writeups
 
-## 5) Power schedules
-------------------
+Here are some good writeups to show how to effectively use AFL++:
+
+ * [https://aflplus.plus/docs/tutorials/libxml2_tutorial/](https://aflplus.plus/docs/tutorials/libxml2_tutorial/)
+ * [https://bananamafia.dev/post/gb-fuzz/](https://bananamafia.dev/post/gb-fuzz/)
+ * [https://securitylab.github.com/research/fuzzing-challenges-solutions-1](https://securitylab.github.com/research/fuzzing-challenges-solutions-1)
+ * [https://securitylab.github.com/research/fuzzing-sockets-FTP](https://securitylab.github.com/research/fuzzing-sockets-FTP)
+
+If you are interested in fuzzing structured data (where you define what the
+structure is), these two links have you covered:
+ * [https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator](https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator)
+ * [https://github.com/thebabush/afl-libprotobuf-mutator](https://github.com/thebabush/afl-libprotobuf-mutator)
+
+If you find other good ones, please send them to us :-)
+
+## Power schedules
 
 The power schedules were copied from Marcel Böhme's excellent AFLfast
-implementation and expands on the ability to discover new paths and
-therefore the coverage.
+implementation and expand on the ability to discover new paths and
+therefore may increase the code coverage.
 
 The available schedules are:
  
@@ -208,32 +376,31 @@ The available schedules are:
  - quad
  - lin
  - exploit
+ - mmopt (experimental)
+ - rare (experimental)
 
-In parallel mode (-M/-S, several instances with shared queue), we suggest to
-run the master using the exploit schedule (-p exploit) and the slaves with a
-combination of cut-off-exponential (-p coe), exponential (-p fast; default),
-and explore (-p explore) schedules.
+In parallel mode (-M/-S, several instances with the shared queue), we suggest to
+run the master using the explore or fast schedule (-p explore) and the slaves
+with a combination of cut-off-exponential (-p coe), exponential (-p fast),
+explore (-p explore) and mmopt (-p mmopt) schedules. If a schedule does
+not perform well for a target, restart the slave with a different schedule.
 
-In single mode, using -p fast is usually more beneficial than the default
-explore mode.
-(We don't want to change the default behaviour of afl, so "fast" has not been
+In single mode, using -p fast is usually slightly more beneficial than the
+default explore mode.
+(We don't want to change the default behavior of afl, so "fast" has not been
 made the default mode).
 
 More details can be found in the paper published at the 23rd ACM Conference on
-Computer and Communications Security (CCS'16):
- 
- (https://www.sigsac.org/ccs/CCS2016/accepted-papers/)[https://www.sigsac.org/ccs/CCS2016/accepted-papers/]
+Computer and Communications Security [CCS'16](https://www.sigsac.org/ccs/CCS2016/accepted-papers/)
 
-
-## 6) Choosing initial test cases
-------------------------------
+## Choosing initial test cases
 
 To operate correctly, the fuzzer requires one or more starting file that
 contains a good example of the input data normally expected by the targeted
 application. There are two basic rules:
 
   - Keep the files small. Under 1 kB is ideal, although not strictly necessary.
-    For a discussion of why size matters, see [perf_tips.txt](docs/perf_tips.txt).
+    For a discussion of why size matters, see [perf_tips.md](docs/perf_tips.md).
 
   - Use multiple test cases only if they are functionally different from
     each other. There is no point in using fifty different vacation photos
@@ -247,8 +414,7 @@ the afl-cmin utility to identify a subset of functionally distinct files that
 exercise different code paths in the target binary.
 
 
-## 7) Fuzzing binaries
--------------------
+## Fuzzing binaries
 
 The fuzzing process itself is carried out by the afl-fuzz utility. This program
 requires a read-only directory with initial test cases, a separate place to
@@ -278,27 +444,25 @@ You can use -t and -m to override the default timeout and memory limit for the
 executed process; rare examples of targets that may need these settings touched
 include compilers and video decoders.
 
-Tips for optimizing fuzzing performance are discussed in [perf_tips.txt](docs/perf_tips.txt).
+Tips for optimizing fuzzing performance are discussed in [perf_tips.md](docs/perf_tips.md).
 
 Note that afl-fuzz starts by performing an array of deterministic fuzzing
 steps, which can take several days, but tend to produce neat test cases. If you
 want quick & dirty results right away - akin to zzuf and other traditional
 fuzzers - add the -d option to the command line.
 
+## Interpreting output
 
-## 8) Interpreting output
-----------------------
-
-See the [docs/status_screen.txt](docs/status_screen.txt) file for information on
+See the [docs/status_screen.md](docs/status_screen.md) file for information on
 how to interpret the displayed stats and monitor the health of the process. Be
 sure to consult this file especially if any UI elements are highlighted in red.
 
-The fuzzing process will continue until you press Ctrl-C. At minimum, you want
+The fuzzing process will continue until you press Ctrl-C. At a minimum, you want
 to allow the fuzzer to complete one queue cycle, which may take anywhere from a
 couple of hours to a week or so.
 
 There are three subdirectories created within the output directory and updated
-in real time:
+in real-time:
 
   - queue/   - test cases for every distinctive execution path, plus all the
                starting files given by the user. This is the synthesized corpus
@@ -323,7 +487,7 @@ involve any state transitions not seen in previously-recorded faults. If a
 single bug can be reached in multiple ways, there will be some count inflation
 early in the process, but this should quickly taper off.
 
-The file names for crashes and hangs are correlated with parent, non-faulting
+The file names for crashes and hangs are correlated with the parent, non-faulting
 queue entries. This should help with debugging.
 
 When you can't reproduce a crash found by afl-fuzz, the most likely cause is
@@ -347,22 +511,18 @@ If you have gnuplot installed, you can also generate some pretty graphs for any
 active fuzzing task using afl-plot. For an example of how this looks like,
 see [http://lcamtuf.coredump.cx/afl/plot/](http://lcamtuf.coredump.cx/afl/plot/).
 
-
-## 9) Parallelized fuzzing
------------------------
+## Parallelized fuzzing
 
 Every instance of afl-fuzz takes up roughly one core. This means that on
 multi-core systems, parallelization is necessary to fully utilize the hardware.
 For tips on how to fuzz a common target on multiple cores or multiple networked
-machines, please refer to [docs/parallel_fuzzing.txt](docs/parallel_fuzzing.txt).
+machines, please refer to [docs/parallel_fuzzing.md](docs/parallel_fuzzing.md).
 
 The parallel fuzzing mode also offers a simple way for interfacing AFL to other
 fuzzers, to symbolic or concolic execution engines, and so forth; again, see the
-last section of [docs/parallel_fuzzing.txt](docs/parallel_fuzzing.txt) for tips.
+last section of [docs/parallel_fuzzing.md](docs/parallel_fuzzing.md) for tips.
 
-
-## 10) Fuzzer dictionaries
-----------------------
+## Fuzzer dictionaries
 
 By default, afl-fuzz mutation engine is optimized for compact data formats -
 say, images, multimedia, compressed data, regular expression syntax, or shell
@@ -377,7 +537,7 @@ magic headers, or other special tokens associated with the targeted data type
   [http://lcamtuf.blogspot.com/2015/01/afl-fuzz-making-up-grammar-with.html](http://lcamtuf.blogspot.com/2015/01/afl-fuzz-making-up-grammar-with.html)
 
 To use this feature, you first need to create a dictionary in one of the two
-formats discussed in [dictionaries/README.dictionaries](ictionaries/README.dictionaries);
+formats discussed in [dictionaries/README.md](dictionaries/README.md);
 and then point the fuzzer to it via the -x option in the command line.
 
 (Several common dictionaries are already provided in that subdirectory, too.)
@@ -391,15 +551,13 @@ instrumentation feedback alone. This actually works in practice, say:
 PS. Even when no explicit dictionary is given, afl-fuzz will try to extract
 existing syntax tokens in the input corpus by watching the instrumentation
 very closely during deterministic byte flips. This works for some types of
-parsers and grammars, but isn't nearly as good as the -x mode.
+parsers and grammars but isn't nearly as good as the -x mode.
 
 If a dictionary is really hard to come by, another option is to let AFL run
-for a while, and then use the token capture library that comes as a companion
-utility with AFL. For that, see [libtokencap/README.tokencap](libtokencap/README.tokencap).
+for a while and then use the token capture library that comes as a companion
+utility with AFL. For that, see [libtokencap/README.md](libtokencap/README.tokencap.md).
 
-
-## 11) Crash triage
-----------------
+## Crash triage
 
 The coverage-based grouping of crashes usually produces a small data set that
 can be quickly triaged manually or with a very simple GDB or Valgrind script.
@@ -411,7 +569,7 @@ difficult to quickly evaluate for exploitability without a lot of debugging and
 code analysis work. To assist with this task, afl-fuzz supports a very unique
 "crash exploration" mode enabled with the -C flag.
 
-In this mode, the fuzzer takes one or more crashing test cases as the input,
+In this mode, the fuzzer takes one or more crashing test cases as the input
 and uses its feedback-driven fuzzing strategies to very quickly enumerate all
 code paths that can be reached in the program while keeping it in the
 crashing state.
@@ -444,15 +602,13 @@ file, attempts to sequentially flip bytes, and observes the behavior of the
 tested program. It then color-codes the input based on which sections appear to
 be critical, and which are not; while not bulletproof, it can often offer quick
 insights into complex file formats. More info about its operation can be found
-near the end of [docs/technical_details.txt](docs/technical_details.txt).
+near the end of [docs/technical_details.md](docs/technical_details.md).
 
-
-## 12) Going beyond crashes
-------------------------
+## Going beyond crashes
 
 Fuzzing is a wonderful and underutilized technique for discovering non-crashing
 design and implementation errors, too. Quite a few interesting bugs have been
-found by modifying the target programs to call abort() when, say:
+found by modifying the target programs to call abort() when say:
 
   - Two bignum libraries produce different outputs when given the same
     fuzzer-generated input,
@@ -471,12 +627,10 @@ if you are the maintainer of a particular package, you can make this code
 conditional with `#ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION` (a flag also
 shared with libfuzzer) or `#ifdef __AFL_COMPILER` (this one is just for AFL).
 
-
-## 13) Common-sense risks
-----------------------
+## Common-sense risks
 
 Please keep in mind that, similarly to many other computationally-intensive
-tasks, fuzzing may put strain on your hardware and on the OS. In particular:
+tasks, fuzzing may put a strain on your hardware and on the OS. In particular:
 
   - Your CPU will run hot and will need adequate cooling. In most cases, if
     cooling is insufficient or stops working properly, CPU speeds will be
@@ -502,16 +656,14 @@ tasks, fuzzing may put strain on your hardware and on the OS. In particular:
     $ iostat -d 3 -x -k [...optional disk ID...]
 ```
 
-
-## 14) Known limitations & areas for improvement
----------------------------------------------
+## Known limitations & areas for improvement
 
 Here are some of the most important caveats for AFL:
 
   - AFL detects faults by checking for the first spawned process dying due to
     a signal (SIGSEGV, SIGABRT, etc). Programs that install custom handlers for
     these signals may need to have the relevant code commented out. In the same
-    vein, faults in child processed spawned by the fuzzed target may evade
+    vein, faults in child processes spawned by the fuzzed target may evade
     detection unless you manually add some code to catch that.
 
   - As with any other brute-force tool, the fuzzer offers limited coverage if
@@ -519,12 +671,13 @@ Here are some of the most important caveats for AFL:
     wholly wrap the actual data format to be tested.
 
     To work around this, you can comment out the relevant checks (see
-    experimental/libpng_no_checksum/ for inspiration); if this is not possible,
-    you can also write a postprocessor, as explained in
-    experimental/post_library/ (with AFL_POST_LIBRARY)
+    examples/libpng_no_checksum/ for inspiration); if this is not possible,
+    you can also write a postprocessor, one of the hooks of custom mutators.
+    See [docs/custom_mutators.md](docs/custom_mutators.md) on how to use
+    `AFL_CUSTOM_MUTATOR_LIBRARY`
 
   - There are some unfortunate trade-offs with ASAN and 64-bit binaries. This
-    isn't due to any specific fault of afl-fuzz; see [docs/notes_for_asan.txt](docs/notes_for_asan.txt)
+    isn't due to any specific fault of afl-fuzz; see [docs/notes_for_asan.md](docs/notes_for_asan.md)
     for tips.
 
   - There is no direct support for fuzzing network services, background
@@ -544,12 +697,10 @@ Here are some of the most important caveats for AFL:
 
 Beyond this, see INSTALL for platform-specific tips.
 
+## Special thanks
 
-## 15) Special thanks
-------------------
-
-Many of the improvements to the original afl wouldn't be possible without
-feedback, bug reports, or patches from:
+Many of the improvements to the original afl and afl++ wouldn't be possible
+without feedback, bug reports, or patches from:
 
 ```
   Jann Horn                             Hanno Boeck
@@ -566,7 +717,7 @@ feedback, bug reports, or patches from:
   Jonathan Gray                         Filipe Cabecinhas
   Nico Weber                            Jodie Cunningham
   Andrew Griffiths                      Parker Thompson
-  Jonathan Neuschfer                    Tyler Nighswander
+  Jonathan Neuschaefer                  Tyler Nighswander
   Ben Nagy                              Samir Aguiar
   Aidan Thornton                        Aleksandar Nikolich
   Sam Hakim                             Laszlo Szekeres
@@ -585,23 +736,25 @@ feedback, bug reports, or patches from:
   Austin Seipp                          Daniel Komaromy
   Daniel Binderman                      Jonathan Metzman
   Vegard Nossum                         Jan Kneschke
-  Kurt Roeckx                           Marcel Bohme
+  Kurt Roeckx                           Marcel Boehme
   Van-Thuan Pham                        Abhik Roychoudhury
   Joshua J. Drake                       Toby Hutton
   Rene Freingruber                      Sergey Davidoff
   Sami Liedes                           Craig Young
   Andrzej Jackowski                     Daniel Hodson
-  Nathan Voss				Dominik Maier
+  Nathan Voss                           Dominik Maier
+  Andrea Biondo                         Vincent Le Garrec
+  Khaled Yakdan                         Kuang-che Wu
+  Josephine Calliotte                   Konrad Welc
 ```
 
 Thank you!
+(For people sending pull requests - please add yourself to this list :-)
 
-
-## 16) Contact
------------
+## Contact
 
 Questions? Concerns? Bug reports? The contributors can be reached via
-[https://github.com/vanhauser-thc/AFLplusplus](https://github.com/vanhauser-thc/AFLplusplus)
+[https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus)
 
 There is also a mailing list for the afl project; to join, send a mail to
 <afl-users+subscribe@googlegroups.com>. Or, if you prefer to browse

TODO

@@ -1,34 +0,0 @@
-Roadmap 2.53d:
-==============
- - indent all the code: clang-format -style=Google
-
- - update docs/sister_projects.txt
-
-afl-fuzz:
- - put mutator, scheduler, forkserver and input channels in individual files
- - reuse forkserver for showmap, afl-cmin, etc.
-
-gcc_plugin:
- - needs to be rewritten
- - fix crashes when compiling :(
- - whitelist support
- - skip over uninteresting blocks
- - laf-intel
- - neverZero
-
-qemu_mode:
- - deferred mode with AFL_DEFERRED_QEMU=0xaddress
-
-unit testing / or large testcase campaign
-
-
-Roadmap 2.54d:
-==============
- - expand MAP size to 256k (current L2 cache size on processors)
-   -> 18 bit map
- - llvm_mode: dynamic map size and collission free basic block IDs
-
-qemu_mode:
- - persistent mode patching the return address (WinAFL style)
- - instrument only comparison with immediate values by default when using compcov
-

TODO.md

@@ -0,0 +1,34 @@
+# TODO list for AFL++
+
+## Roadmap 2.65+
+
+ - sync_fuzzers(): only masters sync from all, slaves only sync from master
+   (@andrea: be careful, often people run all slaves)
+ - AFL_MAP_SIZE for qemu_mode and unicorn_mode
+ - random crc32 HASH_CONST per run? because with 65536 paths we have collisions
+ - namespace for targets? e.g. network
+ - libradamsa as a custom module?
+ - focal for travis
+
+## Further down the road
+
+afl-fuzz:
+ - ascii_only mode for mutation output - or use a custom mutator for this?
+ - setting min_len/max_len/start_offset/end_offset limits for mutation output
+
+llvm_mode:
+ - better whitelist solution for LTO
+
+gcc_plugin:
+ - laf-intel
+ - better instrumentation (seems to be better with gcc-9+)
+
+qemu_mode:
+ - update to 5.x (if the performance bug if gone)
+ - non colliding instrumentation
+ - rename qemu specific envs to AFL_QEMU (AFL_ENTRYPOINT, AFL_CODE_START/END,
+   AFL_COMPCOV_LEVEL?)
+ - add AFL_QEMU_EXITPOINT (maybe multiple?), maybe pointless as we have
+   persistent mode
+ - add/implement AFL_QEMU_INST_LIBLIST and AFL_QEMU_NOINST_PROGRAM
+ - add/implement AFL_QEMU_INST_REGIONS as a list of _START/_END addresses

afl-cmin

@@ -1,467 +1,509 @@
-#!/usr/bin/env bash
+#!/usr/bin/env sh
+export AFL_QUIET=1
+export ASAN_OPTIONS=detect_leaks=0
+THISPATH=`dirname ${0}`
+export PATH="${THISPATH}:$PATH"
+awk -f - -- ${@+"$@"} <<'EOF'
+#!/usr/bin/awk -f
+
+# awk script to minimize a test corpus of input files
 #
-# american fuzzy lop - corpus minimization tool
-# ---------------------------------------------
+# based on afl-cmin bash script written by Michal Zalewski
+# rewritten by Heiko Eißfeldt (hexcoder-)
+# tested with:
+#   gnu awk (x86 Linux)
+#   bsd awk (x86 *BSD)
+#   mawk (arm32 raspbian)
 #
-# Written and maintained by Michal Zalewski <lcamtuf@google.com>
-#
-# Copyright 2014, 2015 Google Inc. All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#   http://www.apache.org/licenses/LICENSE-2.0
-#
-# This tool tries to find the smallest subset of files in the input directory
-# that still trigger the full range of instrumentation data points seen in
-# the starting corpus. This has two uses:
-#
-#   - Screening large corpora of input files before using them as a seed for
-#     afl-fuzz. The tool will remove functionally redundant files and likely
-#     leave you with a much smaller set.
-#
-#     (In this case, you probably also want to consider running afl-tmin on
-#     the individual files later on to reduce their size.)
-#
-#   - Minimizing the corpus generated organically by afl-fuzz, perhaps when
-#     planning to feed it to more resource-intensive tools. The tool achieves
-#     this by removing all entries that used to trigger unique behaviors in the
-#     past, but have been made obsolete by later finds.
-#
-# Note that the tool doesn't modify the files themselves. For that, you want
-# afl-tmin.
-#
-# This script must use bash because other shells may have hardcoded limits on
-# array sizes.
+# uses getopt.awk package from Arnold Robbins
 #
+# external tools used by this script:
+# test
+# grep
+# rm
+# mkdir
+# ln
+# cp
+# pwd
+# type
+# cd
+# find
+# stat
+# sort
+# cut
+# and afl-showmap from this project :-)
 
-echo "corpus minimization tool for afl-fuzz by <lcamtuf@google.com>"
-echo
+# getopt.awk --- Do C library getopt(3) function in awk
 
-#########
-# SETUP #
-#########
+# External variables:
+#    Optind -- index in ARGV of first nonoption argument
+#    Optarg -- string value of argument to current option
+#    Opterr -- if nonzero, print our own diagnostic
+#    Optopt -- current option letter
 
-# Process command-line options...
+# Returns:
+#    -1     at end of options
+#    "?"    for unrecognized option
+#    <c>    a character representing the current option
 
-MEM_LIMIT=100
-TIMEOUT=none
+# Private Data:
+#    _opti  -- index in multiflag option, e.g., -abc
 
-unset IN_DIR OUT_DIR STDIN_FILE EXTRA_PAR MEM_LIMIT_GIVEN \
-  AFL_CMIN_CRASHES_ONLY AFL_CMIN_ALLOW_ANY QEMU_MODE UNICORN_MODE
+function getopt(argc, argv, options,    thisopt, i)
+{
+    if (length(options) == 0)    # no options given
+        return -1
 
-while getopts "+i:o:f:m:t:eQUC" opt; do
+    if (argv[Optind] == "--") {  # all done
+        Optind++
+        _opti = 0
+        return -1
+    } else if (argv[Optind] !~ /^-[^:\t ]/) {
+        _opti = 0
+        return -1
+    }
+    if (_opti == 0)
+        _opti = 2
+    thisopt = substr(argv[Optind], _opti, 1)
+    Optopt = thisopt
+    i = index(options, thisopt)
+    if (i == 0) {
+        if (Opterr)
+            printf("%c -- invalid option\n", thisopt) > "/dev/stderr"
+        if (_opti >= length(argv[Optind])) {
+            Optind++
+            _opti = 0
+        } else
+            _opti++
+        return "?"
+    }
+    if (substr(options, i + 1, 1) == ":") {
+        # get option argument
+        if (length(substr(argv[Optind], _opti + 1)) > 0)
+            Optarg = substr(argv[Optind], _opti + 1)
+        else
+            Optarg = argv[++Optind]
+        _opti = 0
+    } else
+        Optarg = ""
+    if (_opti == 0 || _opti >= length(argv[Optind])) {
+        Optind++
+        _opti = 0
+    } else
+        _opti++
+    return thisopt
+}
 
-  case "$opt" in 
+function usage() {
+   print \
+"afl-cmin [ options ] -- /path/to/target_app [ ... ]\n" \
+"\n" \
+"Required parameters:\n" \
+"  -i dir        - input directory with starting corpus\n" \
+"  -o dir        - output directory for minimized files\n" \
+"\n" \
+"Execution control settings:\n" \
+"  -f file       - location read by the fuzzed program (stdin)\n" \
+"  -m megs       - memory limit for child process ("mem_limit" MB)\n" \
+"  -t msec       - run time limit for child process (none)\n" \
+"  -Q            - use binary-only instrumentation (QEMU mode)\n" \
+"  -U            - use unicorn-based instrumentation (unicorn mode)\n" \
+"\n" \
+"Minimization settings:\n" \
+"  -C            - keep crashing inputs, reject everything else\n" \
+"  -e            - solve for edge coverage only, ignore hit counts\n" \
+"\n" \
+"For additional tips, please consult docs/README.md\n" \
+"\n" \
+"Environment variables used:\n" \
+"AFL_KEEP_TRACES: leave the temporary <out_dir>/.traces directory\n" \
+"AFL_PATH: path for the afl-showmap binary\n" \
+"AFL_SKIP_BIN_CHECK: skip check for target binary\n" \
+"AFL_ALLOW_TMP: allow unsafe use of input/output directories under {/var}/tmp\n"
+   exit 1
+}
 
-    "i")
-         IN_DIR="$OPTARG"
-         ;;
+function exists_and_is_executable(binarypath) {
+  return 0 == system("test -f "binarypath" -a -x "binarypath)
+}
 
-    "o")
-         OUT_DIR="$OPTARG"
-         ;;
-    "f")
-         STDIN_FILE="$OPTARG"
-         ;;
-    "m")
-         MEM_LIMIT="$OPTARG"
-         MEM_LIMIT_GIVEN=1
-         ;;
-    "t")
-         TIMEOUT="$OPTARG"
-         ;;
-    "e")
-         EXTRA_PAR="$EXTRA_PAR -e"
-         ;;
-    "C")
-         export AFL_CMIN_CRASHES_ONLY=1
-         ;;
-    "Q")
-         EXTRA_PAR="$EXTRA_PAR -Q"
-         test "$MEM_LIMIT_GIVEN" = "" && MEM_LIMIT=250
-         QEMU_MODE=1
-         ;;
-    "U")
-         EXTRA_PAR="$EXTRA_PAR -U"
-         test "$MEM_LIMIT_GIVEN" = "" && MEM_LIMIT=250
-         UNICORN_MODE=1
-         ;;    
-    "?")
-         exit 1
-         ;;
+BEGIN {
+  print "corpus minimization tool for afl++ (awk version)\n"
 
-   esac
+  # defaults
+  extra_par = ""
+  # process options
+  Opterr = 1    # default is to diagnose
+  Optind = 1    # skip ARGV[0]
+  while ((_go_c = getopt(ARGC, ARGV, "hi:o:f:m:t:eCQU?")) != -1) {
+    if (_go_c == "i") {
+      if (!Optarg) usage()
+      if (in_dir) { print "Option "_go_c" is only allowed once" > "/dev/stderr"}
+      in_dir = Optarg
+      continue
+    } else 
+    if (_go_c == "o") {
+      if (!Optarg) usage()
+      if (out_dir) { print "Option "_go_c" is only allowed once" > "/dev/stderr"}
+      out_dir = Optarg
+      continue
+    } else 
+    if (_go_c == "f") {
+      if (!Optarg) usage()
+      if (stdin_file) { print "Option "_go_c" is only allowed once" > "/dev/stderr"}
+      stdin_file = Optarg
+      continue
+    } else 
+    if (_go_c == "m") {
+      if (!Optarg) usage()
+      if (mem_limit) { print "Option "_go_c" is only allowed once" > "/dev/stderr"}
+      mem_limit = Optarg
+      mem_limit_given = 1
+      continue
+    } else 
+    if (_go_c == "t") {
+      if (!Optarg) usage()
+      if (timeout) { print "Option "_go_c" is only allowed once" > "/dev/stderr"}
+      timeout = Optarg
+      continue
+    } else 
+    if (_go_c == "C") {
+      ENVIRON["AFL_CMIN_CRASHES_ONLY"] = 1
+      continue
+    } else 
+    if (_go_c == "e") {
+      extra_par = extra_par " -e"
+      continue
+    } else 
+    if (_go_c == "Q") {
+      if (qemu_mode) { print "Option "_go_c" is only allowed once" > "/dev/stderr"}
+      extra_par = extra_par " -Q"
+      if ( !mem_limit_given ) mem_limit = "250"
+      qemu_mode = 1
+      continue
+    } else 
+    if (_go_c == "U") {
+      if (unicorn_mode) { print "Option "_go_c" is only allowed once" > "/dev/stderr"}
+      extra_par = extra_par " -U"
+      if ( !mem_limit_given ) mem_limit = "250"
+      unicorn_mode = 1
+      continue
+    } else 
+    if (_go_c == "?") {
+      exit 1
+    } else 
+      usage()
+  } # while options
 
-done
+  if (!mem_limit) mem_limit = 200
+  if (!timeout) timeout = "none"
 
-shift $((OPTIND-1))
+  # get program args
+  i = 0
+  prog_args_string = ""
+  for (; Optind < ARGC; Optind++) {
+    prog_args[i++] = ARGV[Optind]
+    if (i > 1)
+      prog_args_string = prog_args_string" "ARGV[Optind]
+  }
 
-TARGET_BIN="$1"
+  # sanity checks
+  if (!prog_args[0] || !in_dir || !out_dir) usage()
 
-if [ "$TARGET_BIN" = "" -o "$IN_DIR" = "" -o "$OUT_DIR" = "" ]; then
+  target_bin = prog_args[0] 
 
-  cat 1>&2 <<_EOF_
-Usage: $0 [ options ] -- /path/to/target_app [ ... ]
+  # Do a sanity check to discourage the use of /tmp, since we can't really
+  # handle this safely from an awk script.
 
-Required parameters:
+  if (!ENVIRON["AFL_ALLOW_TMP"]) {
+    dirlist[0] = in_dir
+    dirlist[1] = target_bin
+    dirlist[2] = out_dir
+    dirlist[3] = stdin_file
+    "pwd" | getline dirlist[4] # current directory
+    for (dirind in dirlist) {
+      dir = dirlist[dirind]
 
-  -i dir        - input directory with the starting corpus
-  -o dir        - output directory for minimized files
+      if (dir ~ /^(\/var)?\/tmp/) {
+        print "[-] Error: do not use this script in /tmp or /var/tmp." > "/dev/stderr"
+        exit 1
+      }
+    }
+    delete dirlist
+  }
 
-Execution control settings:
+  # If @@ is specified, but there's no -f, let's come up with a temporary input
+  # file name.
 
-  -f file       - location read by the fuzzed program (stdin)
-  -m megs       - memory limit for child process ($MEM_LIMIT MB)
-  -t msec       - run time limit for child process (none)
-  -Q            - use binary-only instrumentation (QEMU mode)
-  -U            - use unicorn-based instrumentation (Unicorn mode)
+  trace_dir = out_dir "/.traces"
+
+  if (!stdin_file) {
+    found_atat = 0
+    for (prog_args_ind in prog_args) {
+      if ("@@" == prog_args[prog_args_ind]) {
+        found_atat = 1
+        break
+      }
+    }
+    if (found_atat) {
+      stdin_file = trace_dir "/.cur_input"
+    }
+  }
+
+  # Check for obvious errors.
+
+  if (mem_limit && mem_limit != "none" && mem_limit < 5) {
+    print "[-] Error: dangerously low memory limit." > "/dev/stderr"
+    exit 1
+  }
+
+  if (timeout && timeout != "none" && timeout < 10) {
+    print "[-] Error: dangerously low timeout." > "/dev/stderr"
+    exit 1
+  }
+
+  if (target_bin && !exists_and_is_executable(target_bin)) {
+
+    "command -v "target_bin" 2>/dev/null" | getline tnew
+    if (!tnew || !exists_and_is_executable(tnew)) {
+      print "[-] Error: binary '"target_bin"' not found or not executable." > "/dev/stderr"
+      exit 1
+    }
+    target_bin = tnew
+  }
+
+  if (!ENVIRON["AFL_SKIP_BIN_CHECK"] && !qemu_mode && !unicorn_mode) {
+    if (0 != system( "grep -q __AFL_SHM_ID "target_bin )) {
+      print "[-] Error: binary '"target_bin"' doesn't appear to be instrumented." > "/dev/stderr"
+      exit 1
+    }
+  }
+
+  if (0 != system( "test -d "in_dir )) {
+    print "[-] Error: directory '"in_dir"' not found." > "/dev/stderr"
+    exit 1
+  }
+
+  if (0 == system( "test -d "in_dir"/queue" )) {
+    in_dir = in_dir "/queue"
+  }
+
+  system("rm -rf "trace_dir" 2>/dev/null");
+  system("rm "out_dir"/id[:_]* 2>/dev/null")
+
+  "ls "out_dir"/* 2>/dev/null | wc -l" | getline noofentries
+  if (0 == system( "test -d "out_dir" -a "noofentries" -gt 0" )) {
+    print "[-] Error: directory '"out_dir"' exists and is not empty - delete it first." > "/dev/stderr"
+    exit 1
+  }
+
+  # Check for the more efficient way to copy files...
+  if (0 != system("mkdir -p -m 0700 "trace_dir)) {
+    print "[-] Error: Cannot create directory "trace_dir > "/dev/stderr"
+    exit 1
+  }
+
+  if (stdin_file) {
+    # truncate input file
+    printf "" > stdin_file
+    close( stdin_file )
+  }
+
+  if (!ENVIRON["AFL_PATH"]) {
+    if (0 == system("test -f afl-cmin")) {
+      showmap = "./afl-showmap"
+    } else {
+      "command -v afl-showmap 2>/dev/null" | getline showmap
+    }
+  } else {
+    showmap = ENVIRON["AFL_PATH"] "/afl-showmap"
+  }
+
+  if (!showmap || 0 != system("test -x "showmap )) {
+    print "[-] Error: can't find 'afl-showmap' - please set AFL_PATH." > "/dev/stderr"
+    exit 1
+  }
+
+  # get list of input filenames sorted by size
+  i = 0
+  # yuck, gnu stat is option incompatible to bsd stat
+  # we use a heuristic to differentiate between
+  # GNU stat and other stats
+  "stat --version 2>/dev/null" | getline statversion
+  if (statversion ~ /GNU coreutils/) {
+    stat_format = "-c '%s %n'" # GNU
+  } else {
+    stat_format = "-f '%z %N'" # *BSD, MacOS
+  }
+  cmdline = "cd "in_dir" && find . \\( ! -name . -a -type d -prune \\) -o -type f -exec stat "stat_format" \\{\\} \\; | sort -k1n -k2r"
+  cmdline = "ls "in_dir" | (cd "in_dir" && xargs stat "stat_format") | sort -k1n -k2r"
+  while (cmdline | getline) {
+    sub(/^[0-9]+ (\.\/)?/,"",$0)
+    infilesSmallToBig[i++] = $0
+  }
+  in_count = i
+
+  first_file = infilesSmallToBig[0]
   
-Minimization settings:
+  # Make sure that we're not dealing with a directory.
 
-  -C            - keep crashing inputs, reject everything else
-  -e            - solve for edge coverage only, ignore hit counts
-
-For additional tips, please consult docs/README.
-
-_EOF_
-  exit 1
-fi
-
-# Do a sanity check to discourage the use of /tmp, since we can't really
-# handle this safely from a shell script.
-
-if [ "$AFL_ALLOW_TMP" = "" ]; then
-
-  echo "$IN_DIR" | grep -qE '^(/var)?/tmp/'
-  T1="$?"
-
-  echo "$TARGET_BIN" | grep -qE '^(/var)?/tmp/'
-  T2="$?"
-
-  echo "$OUT_DIR" | grep -qE '^(/var)?/tmp/'
-  T3="$?"
-
-  echo "$STDIN_FILE" | grep -qE '^(/var)?/tmp/'
-  T4="$?"
-
-  echo "$PWD" | grep -qE '^(/var)?/tmp/'
-  T5="$?"
-
-  if [ "$T1" = "0" -o "$T2" = "0" -o "$T3" = "0" -o "$T4" = "0" -o "$T5" = "0" ]; then
-    echo "[-] Error: do not use this script in /tmp or /var/tmp." 1>&2
+  if (0 == system("test -d "in_dir"/"first_file)) {
+    print "[-] Error: The input directory contains subdirectories - please fix." > "/dev/stderr"
     exit 1
-  fi
+  }
 
-fi
+  if (0 == system("ln "in_dir"/"first_file" "trace_dir"/.link_test")) {
+    cp_tool = "ln"
+  } else {
+    cp_tool = "cp"
+  }
 
-# If @@ is specified, but there's no -f, let's come up with a temporary input
-# file name.
+  # Make sure that we can actually get anything out of afl-showmap before we
+  # waste too much time.
 
-TRACE_DIR="$OUT_DIR/.traces"
+  print "[*] Testing the target binary..."
 
-if [ "$STDIN_FILE" = "" ]; then
+  if (!stdin_file) {
+    system( "AFL_CMIN_ALLOW_ANY=1 \""showmap"\" -m "mem_limit" -t "timeout" -o \""trace_dir"/.run_test\" -Z "extra_par" -- \""target_bin"\" "prog_args_string" <\""in_dir"/"first_file"\"")
+  } else {
+    system("cp "in_dir"/"first_file" "stdin_file)
+    system( "AFL_CMIN_ALLOW_ANY=1 \""showmap"\" -m "mem_limit" -t "timeout" -o \""trace_dir"/.run_test\" -Z "extra_par" -A \""stdin_file"\" -- \""target_bin"\" "prog_args_string" </dev/null")
+  }
 
-  if echo "$*" | grep -qF '@@'; then
-    STDIN_FILE="$TRACE_DIR/.cur_input"
-  fi
+  first_count = 0
 
-fi
+  runtest = trace_dir"/.run_test"
+  while ((getline < runtest) > 0) {
+    ++first_count
+  }
 
-# Check for obvious errors.
-
-if [ ! "$MEM_LIMIT" = "none" ]; then
-
-  if [ "$MEM_LIMIT" -lt "5" ]; then
-    echo "[-] Error: dangerously low memory limit." 1>&2
+  if (first_count) {
+    print "[+] OK, "first_count" tuples recorded."
+  } else {
+    print "[-] Error: no instrumentation output detected (perhaps crash or timeout)." > "/dev/stderr"
+    if (!ENVIRON["AFL_KEEP_TRACES"]) {
+      system("rm -rf "trace_dir" 2>/dev/null")
+    }
     exit 1
-  fi
-
-fi
-
-if [ ! "$TIMEOUT" = "none" ]; then
-
-  if [ "$TIMEOUT" -lt "10" ]; then
-    echo "[-] Error: dangerously low timeout." 1>&2
-    exit 1
-  fi
-
-fi
-
-if [ ! -f "$TARGET_BIN" -o ! -x "$TARGET_BIN" ]; then
-
-  TNEW="`which "$TARGET_BIN" 2>/dev/null`"
-
-  if [ ! -f "$TNEW" -o ! -x "$TNEW" ]; then
-    echo "[-] Error: binary '$TARGET_BIN' not found or not executable." 1>&2
-    exit 1
-  fi
-
-  TARGET_BIN="$TNEW"
-
-fi
-
-if [ "$AFL_SKIP_BIN_CHECK" = "" -a "$QEMU_MODE" = "" -a "$UNICORN_MODE" = "" ]; then
-
-  if ! grep -qF "__AFL_SHM_ID" "$TARGET_BIN"; then
-    echo "[-] Error: binary '$TARGET_BIN' doesn't appear to be instrumented." 1>&2
-    exit 1
-  fi
-
-fi
-
-if [ ! -d "$IN_DIR" ]; then
-  echo "[-] Error: directory '$IN_DIR' not found." 1>&2
-  exit 1
-fi
-
-test -d "$IN_DIR/queue" && IN_DIR="$IN_DIR/queue"
-
-find "$OUT_DIR" -name 'id[:_]*' -maxdepth 1 -exec rm -- {} \; 2>/dev/null
-rm -rf "$TRACE_DIR" 2>/dev/null
-
-rmdir "$OUT_DIR" 2>/dev/null
-
-if [ -d "$OUT_DIR" ]; then
-  echo "[-] Error: directory '$OUT_DIR' exists and is not empty - delete it first." 1>&2
-  exit 1
-fi
-
-mkdir -m 700 -p "$TRACE_DIR" || exit 1
-
-if [ ! "$STDIN_FILE" = "" ]; then
-  rm -f "$STDIN_FILE" || exit 1
-  touch "$STDIN_FILE" || exit 1
-fi
-
-if [ "$AFL_PATH" = "" ]; then
-  SHOWMAP="${0%/afl-cmin}/afl-showmap"
-else
-  SHOWMAP="$AFL_PATH/afl-showmap"
-fi
-
-if [ ! -x "$SHOWMAP" ]; then
-  echo "[-] Error: can't find 'afl-showmap' - please set AFL_PATH." 1>&2
-  rm -rf "$TRACE_DIR"
-  exit 1
-fi
-
-IN_COUNT=$((`ls -- "$IN_DIR" 2>/dev/null | wc -l`))
-
-if [ "$IN_COUNT" = "0" ]; then
-  echo "[+] Hmm, no inputs in the target directory. Nothing to be done."
-  rm -rf "$TRACE_DIR"
-  exit 1
-fi
-
-FIRST_FILE=`ls "$IN_DIR" | head -1`
-
-# Make sure that we're not dealing with a directory.
-
-if [ -d "$IN_DIR/$FIRST_FILE" ]; then
-  echo "[-] Error: The target directory contains subdirectories - please fix." 1>&2
-  rm -rf "$TRACE_DIR"
-  exit 1
-fi
-
-# Check for the more efficient way to copy files...
-
-if ln "$IN_DIR/$FIRST_FILE" "$TRACE_DIR/.link_test" 2>/dev/null; then
-  CP_TOOL=ln
-else
-  CP_TOOL=cp
-fi
-
-# Make sure that we can actually get anything out of afl-showmap before we
-# waste too much time.
-
-echo "[*] Testing the target binary..."
-
-if [ "$STDIN_FILE" = "" ]; then
-
-  AFL_CMIN_ALLOW_ANY=1 "$SHOWMAP" -m "$MEM_LIMIT" -t "$TIMEOUT" -o "$TRACE_DIR/.run_test" -Z $EXTRA_PAR -- "$@" <"$IN_DIR/$FIRST_FILE"
-
-else
-
-  cp "$IN_DIR/$FIRST_FILE" "$STDIN_FILE"
-  AFL_CMIN_ALLOW_ANY=1 "$SHOWMAP" -m "$MEM_LIMIT" -t "$TIMEOUT" -o "$TRACE_DIR/.run_test" -Z $EXTRA_PAR -A "$STDIN_FILE" -- "$@" </dev/null
-
-fi
-
-FIRST_COUNT=$((`grep -c . "$TRACE_DIR/.run_test"`))
-
-if [ "$FIRST_COUNT" -gt "0" ]; then
-
-  echo "[+] OK, $FIRST_COUNT tuples recorded."
-
-else
-
-  echo "[-] Error: no instrumentation output detected (perhaps crash or timeout)." 1>&2
-  test "$AFL_KEEP_TRACES" = "" && rm -rf "$TRACE_DIR"
-  exit 1
-
-fi
-
-# Let's roll!
-
-#############################
-# STEP 1: COLLECTING TRACES #
-#############################
-
-echo "[*] Obtaining traces for input files in '$IN_DIR'..."
-
-(
-
-  CUR=0
-
-  if [ "$STDIN_FILE" = "" ]; then
-
-    while read -r fn; do
-
-      CUR=$((CUR+1))
-      printf "\\r    Processing file $CUR/$IN_COUNT... "
-
-      "$SHOWMAP" -m "$MEM_LIMIT" -t "$TIMEOUT" -o "$TRACE_DIR/$fn" -Z $EXTRA_PAR -- "$@" <"$IN_DIR/$fn"
-
-    done < <(ls "$IN_DIR")
-
-  else
-
-    while read -r fn; do
-
-      CUR=$((CUR+1))
-      printf "\\r    Processing file $CUR/$IN_COUNT... "
-
-      cp "$IN_DIR/$fn" "$STDIN_FILE"
-
-      "$SHOWMAP" -m "$MEM_LIMIT" -t "$TIMEOUT" -o "$TRACE_DIR/$fn" -Z $EXTRA_PAR -A "$STDIN_FILE" -- "$@" </dev/null
-
-    done < <(ls "$IN_DIR")
-
-
-  fi
-
-)
-
-echo
-
-##########################
-# STEP 2: SORTING TUPLES #
-##########################
-
-# With this out of the way, we sort all tuples by popularity across all
-# datasets. The reasoning here is that we won't be able to avoid the files
-# that trigger unique tuples anyway, so we will want to start with them and
-# see what's left.
-
-echo "[*] Sorting trace sets (this may take a while)..."
-
-ls "$IN_DIR" | sed "s#^#$TRACE_DIR/#" | tr '\n' '\0' | xargs -0 -n 1 cat | \
-  sort | uniq -c | sort -k 1,1 -n >"$TRACE_DIR/.all_uniq"
-
-TUPLE_COUNT=$((`grep -c . "$TRACE_DIR/.all_uniq"`))
-
-echo "[+] Found $TUPLE_COUNT unique tuples across $IN_COUNT files."
-
-#####################################
-# STEP 3: SELECTING CANDIDATE FILES #
-#####################################
-
-# The next step is to find the best candidate for each tuple. The "best"
-# part is understood simply as the smallest input that includes a particular
-# tuple in its trace. Empirical evidence suggests that this produces smaller
-# datasets than more involved algorithms that could be still pulled off in
-# a shell script.
-
-echo "[*] Finding best candidates for each tuple..."
-
-CUR=0
-
-while read -r fn; do
-
-  CUR=$((CUR+1))
-  printf "\\r    Processing file $CUR/$IN_COUNT... "
-
-  sed "s#\$# $fn#" "$TRACE_DIR/$fn" >>"$TRACE_DIR/.candidate_list"
-
-done < <(ls -rS "$IN_DIR")
-
-echo
-
-##############################
-# STEP 4: LOADING CANDIDATES #
-##############################
-
-# At this point, we have a file of tuple-file pairs, sorted by file size
-# in ascending order (as a consequence of ls -rS). By doing sort keyed
-# only by tuple (-k 1,1) and configured to output only the first line for
-# every key (-s -u), we end up with the smallest file for each tuple.
-
-echo "[*] Sorting candidate list (be patient)..."
-
-sort -k1,1 -s -u "$TRACE_DIR/.candidate_list" | \
-  sed 's/^/BEST_FILE[/;s/ /]="/;s/$/"/' >"$TRACE_DIR/.candidate_script"
-
-if [ ! -s "$TRACE_DIR/.candidate_script" ]; then
-  echo "[-] Error: no traces obtained from test cases, check syntax!" 1>&2
-  test "$AFL_KEEP_TRACES" = "" && rm -rf "$TRACE_DIR"
-  exit 1
-fi
-
-# The sed command converted the sorted list to a shell script that populates
-# BEST_FILE[tuple]="fname". Let's load that!
-
-. "$TRACE_DIR/.candidate_script"
-
-##########################
-# STEP 5: WRITING OUTPUT #
-##########################
-
-# The final trick is to grab the top pick for each tuple, unless said tuple is
-# already set due to the inclusion of an earlier candidate; and then put all
-# tuples associated with the newly-added file to the "already have" list. The
-# loop works from least popular tuples and toward the most common ones.
-
-echo "[*] Processing candidates and writing output files..."
-
-CUR=0
-
-touch "$TRACE_DIR/.already_have"
-
-while read -r cnt tuple; do
-
-  CUR=$((CUR+1))
-  printf "\\r    Processing tuple $CUR/$TUPLE_COUNT... "
-
-  # If we already have this tuple, skip it.
-
-  grep -q "^$tuple\$" "$TRACE_DIR/.already_have" && continue
-
-  FN=${BEST_FILE[tuple]}
-
-  $CP_TOOL "$IN_DIR/$FN" "$OUT_DIR/$FN"
-
-  if [ "$((CUR % 5))" = "0" ]; then
-    sort -u "$TRACE_DIR/$FN" "$TRACE_DIR/.already_have" >"$TRACE_DIR/.tmp"
-    mv -f "$TRACE_DIR/.tmp" "$TRACE_DIR/.already_have"
-  else
-    cat "$TRACE_DIR/$FN" >>"$TRACE_DIR/.already_have"
-  fi
-
-done <"$TRACE_DIR/.all_uniq"
-
-echo
-
-OUT_COUNT=`ls -- "$OUT_DIR" | wc -l`
-
-if [ "$OUT_COUNT" = "1" ]; then
-  echo "[!] WARNING: All test cases had the same traces, check syntax!"
-fi
-
-echo "[+] Narrowed down to $OUT_COUNT files, saved in '$OUT_DIR'."
-echo
-
-test "$AFL_KEEP_TRACES" = "" && rm -rf "$TRACE_DIR"
-
-exit 0
+  }
+
+  # Let's roll!
+
+  #############################
+  # STEP 1: Collecting traces #
+  #############################
+
+  print "[*] Obtaining traces for "in_count" input files in '"in_dir"'."
+
+  cur = 0;
+  if (!stdin_file) {
+    print "    Processing "in_count" files (forkserver mode)..."
+    retval = system( "AFL_CMIN_ALLOW_ANY=1 \""showmap"\" -m "mem_limit" -t "timeout" -o \""trace_dir"\" -Z "extra_par" -i \""in_dir"\" -- \""target_bin"\" "prog_args_string)
+  } else {
+    print "    Processing "in_count" files (forkserver mode)..."
+    retval = system( "AFL_CMIN_ALLOW_ANY=1 \""showmap"\" -m "mem_limit" -t "timeout" -o \""trace_dir"\" -Z "extra_par" -i \""in_dir"\" -- \""target_bin"\" "prog_args_string" </dev/null")
+  }
+
+  if (retval) {
+    print "[!]Exit code != 0 received from afl-showmap, terminating..."
+
+    if (!ENVIRON["AFL_KEEP_TRACES"]) {
+      system("rm -rf "trace_dir" 2>/dev/null")
+      system("rmdir "out_dir)
+    }
+    exit retval
+  }
+
+  #######################################################
+  # STEP 2: register smallest input file for each tuple #
+  # STEP 3: copy that file (at most once)               #
+  #######################################################
+
+  print "[*] Processing traces for input files in '"in_dir"'."
+
+  cur = 0
+  out_count = 0
+  tuple_count = 0
+
+  # from rare to frequent new tuples
+  # get the best (smallest) file for it
+  # and copy it
+  while (cur < in_count) {
+    fn = infilesSmallToBig[cur]
+    ++cur
+    printf "\r    Processing file "cur"/"in_count
+    # create path for the trace file from afl-showmap
+    tracefile_path = trace_dir"/"fn
+    # gather all keys, and count them
+    while ((getline line < tracefile_path) > 0) {
+        key = line
+        if (!(key in key_count)) {
+          ++tuple_count
+        }
+        ++key_count[key]
+        if (! (key in best_file)) {
+            # this is the best file for this key
+            best_file[key] = fn
+#printf "BEST_FILE[%d]=\"%s\"\n",key,fn | "sort -t'[' -k2 > "trace_dir"/.candidate_script"
+        }
+#printf "%d %s\n",key,fn > trace_dir"/.candidate_list"
+    }
+    close(tracefile_path)
+  }
+  print ""
+
+  # sort keys
+  sortedKeys = trace_dir"/.all_uniq"
+  sortKeysCmd = "sort -k1n > "sortedKeys
+  for (key in key_count) {
+     printf "%7d %s\n",key_count[key],key | sortKeysCmd
+  }
+  close(sortKeysCmd)
+
+  # iterate over keys from rare to frequent and
+  # copy best file
+  while ((getline < sortedKeys) > 0) {
+
+    # split
+    nrFields = split($0, field, / +/)
+#print nrFields" Felder: '"field[0]"',  '"field[1]"',  '"field[2]"',  '"field[3]"'"
+    key = field[nrFields]
+
+    ++tcnt;
+    printf "\r    Processing tuple "tcnt"/"tuple_count" with count "key_count[key]"..."
+    if (key in keyAlreadyKnown) {
+      continue
+    }
+
+    fn = best_file[key]
+    # gather all tuples from the best file for this key
+    tracedfn = trace_dir"/"fn
+    while ((getline < tracedfn) > 0) {
+      keyAlreadyKnown[$0] = ""
+    }
+    close(tracedfn)
+
+    # copy file unless already done
+    if (! (fn in file_already_copied)) {
+      system(cp_tool" "in_dir"/"fn" "out_dir"/"fn)
+      file_already_copied[fn] = ""
+      ++out_count
+      #printf "tuple nr %d (%d cnt=%d) -> %s\n",tcnt,key,key_count[key],fn > trace_dir"/.log"
+    }
+  }
+  close(sortedKeys)
+  print ""
+  print "[+] Found "tuple_count" unique tuples across "in_count" files."
+
+  if (out_count == 1) {
+    print "[!] WARNING: All test cases had the same traces, check syntax!"
+  }
+  print "[+] Narrowed down to "out_count" files, saved in '"out_dir"'."
+
+  if (!ENVIRON["AFL_KEEP_TRACES"]) {
+    system("rm -rf "trace_dir" 2>/dev/null")
+  }
+
+  exit 0
+}
+EOF

afl-cmin.bash

@@ -0,0 +1,478 @@
+#!/usr/bin/env bash
+#
+# american fuzzy lop++ - corpus minimization tool
+# ---------------------------------------------
+#
+# Originally written by Michal Zalewski
+#
+# Copyright 2014, 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# This tool tries to find the smallest subset of files in the input directory
+# that still trigger the full range of instrumentation data points seen in
+# the starting corpus. This has two uses:
+#
+#   - Screening large corpora of input files before using them as a seed for
+#     afl-fuzz. The tool will remove functionally redundant files and likely
+#     leave you with a much smaller set.
+#
+#     (In this case, you probably also want to consider running afl-tmin on
+#     the individual files later on to reduce their size.)
+#
+#   - Minimizing the corpus generated organically by afl-fuzz, perhaps when
+#     planning to feed it to more resource-intensive tools. The tool achieves
+#     this by removing all entries that used to trigger unique behaviors in the
+#     past, but have been made obsolete by later finds.
+#
+# Note that the tool doesn't modify the files themselves. For that, you want
+# afl-tmin.
+#
+# This script must use bash because other shells may have hardcoded limits on
+# array sizes.
+#
+
+echo "corpus minimization tool for afl-fuzz by Michal Zalewski"
+echo
+
+#########
+# SETUP #
+#########
+
+# Process command-line options...
+
+MEM_LIMIT=200
+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
+
+export AFL_QUIET=1
+
+while getopts "+i:o:f:m:t:eQUCh" opt; do
+
+  case "$opt" in 
+
+    "h")
+	;;
+
+    "i")
+         IN_DIR="$OPTARG"
+         ;;
+
+    "o")
+         OUT_DIR="$OPTARG"
+         ;;
+    "f")
+         STDIN_FILE="$OPTARG"
+         ;;
+    "m")
+         MEM_LIMIT="$OPTARG"
+         MEM_LIMIT_GIVEN=1
+         ;;
+    "t")
+         TIMEOUT="$OPTARG"
+         ;;
+    "e")
+         EXTRA_PAR="$EXTRA_PAR -e"
+         ;;
+    "C")
+         export AFL_CMIN_CRASHES_ONLY=1
+         ;;
+    "Q")
+         EXTRA_PAR="$EXTRA_PAR -Q"
+         test "$MEM_LIMIT_GIVEN" = "" && MEM_LIMIT=250
+         QEMU_MODE=1
+         ;;
+    "U")
+         EXTRA_PAR="$EXTRA_PAR -U"
+         test "$MEM_LIMIT_GIVEN" = "" && MEM_LIMIT=250
+         UNICORN_MODE=1
+         ;;    
+    "?")
+         exit 1
+         ;;
+
+   esac
+
+done
+
+shift $((OPTIND-1))
+
+TARGET_BIN="$1"
+
+if [ "$TARGET_BIN" = "" -o "$IN_DIR" = "" -o "$OUT_DIR" = "" ]; then
+
+  cat 1>&2 <<_EOF_
+Usage: $0 [ options ] -- /path/to/target_app [ ... ]
+
+Required parameters:
+
+  -i dir        - input directory with the starting corpus
+  -o dir        - output directory for minimized files
+
+Execution control settings:
+
+  -f file       - location read by the fuzzed program (stdin)
+  -m megs       - memory limit for child process ($MEM_LIMIT MB)
+  -t msec       - run time limit for child process (none)
+  -Q            - use binary-only instrumentation (QEMU mode)
+  -U            - use unicorn-based instrumentation (Unicorn mode)
+  
+Minimization settings:
+
+  -C            - keep crashing inputs, reject everything else
+  -e            - solve for edge coverage only, ignore hit counts
+
+For additional tips, please consult docs/README.md.
+
+Environment variables used:
+AFL_KEEP_TRACES: leave the temporary <out_dir>\.traces directory
+AFL_PATH: path for the afl-showmap binary
+AFL_SKIP_BIN_CHECK: skip check for target binary
+AFL_ALLOW_TMP: allow unsafe use of input/output directories under {/var}/tmp
+_EOF_
+  exit 1
+fi
+
+# Do a sanity check to discourage the use of /tmp, since we can't really
+# handle this safely from a shell script.
+
+if [ "$AFL_ALLOW_TMP" = "" ]; then
+
+  echo "$IN_DIR" | grep -qE '^(/var)?/tmp/'
+  T1="$?"
+
+  echo "$TARGET_BIN" | grep -qE '^(/var)?/tmp/'
+  T2="$?"
+
+  echo "$OUT_DIR" | grep -qE '^(/var)?/tmp/'
+  T3="$?"
+
+  echo "$STDIN_FILE" | grep -qE '^(/var)?/tmp/'
+  T4="$?"
+
+  echo "$PWD" | grep -qE '^(/var)?/tmp/'
+  T5="$?"
+
+  if [ "$T1" = "0" -o "$T2" = "0" -o "$T3" = "0" -o "$T4" = "0" -o "$T5" = "0" ]; then
+    echo "[-] Error: do not use this script in /tmp or /var/tmp." 1>&2
+    exit 1
+  fi
+
+fi
+
+# If @@ is specified, but there's no -f, let's come up with a temporary input
+# file name.
+
+TRACE_DIR="$OUT_DIR/.traces"
+
+if [ "$STDIN_FILE" = "" ]; then
+
+  if echo "$*" | grep -qF '@@'; then
+    STDIN_FILE="$TRACE_DIR/.cur_input"
+  fi
+
+fi
+
+# Check for obvious errors.
+
+if [ ! "$MEM_LIMIT" = "none" ]; then
+
+  if [ "$MEM_LIMIT" -lt "5" ]; then
+    echo "[-] Error: dangerously low memory limit." 1>&2
+    exit 1
+  fi
+
+fi
+
+if [ ! "$TIMEOUT" = "none" ]; then
+
+  if [ "$TIMEOUT" -lt "10" ]; then
+    echo "[-] Error: dangerously low timeout." 1>&2
+    exit 1
+  fi
+
+fi
+
+if [ ! -f "$TARGET_BIN" -o ! -x "$TARGET_BIN" ]; then
+
+  TNEW="`which "$TARGET_BIN" 2>/dev/null`"
+
+  if [ ! -f "$TNEW" -o ! -x "$TNEW" ]; then
+    echo "[-] Error: binary '$TARGET_BIN' not found or not executable." 1>&2
+    exit 1
+  fi
+
+  TARGET_BIN="$TNEW"
+
+fi
+
+if [ "$AFL_SKIP_BIN_CHECK" = "" -a "$QEMU_MODE" = "" -a "$UNICORN_MODE" = "" ]; then
+
+  if ! grep -qF "__AFL_SHM_ID" "$TARGET_BIN"; then
+    echo "[-] Error: binary '$TARGET_BIN' doesn't appear to be instrumented." 1>&2
+    exit 1
+  fi
+
+fi
+
+if [ ! -d "$IN_DIR" ]; then
+  echo "[-] Error: directory '$IN_DIR' not found." 1>&2
+  exit 1
+fi
+
+test -d "$IN_DIR/queue" && IN_DIR="$IN_DIR/queue"
+
+find "$OUT_DIR" -name 'id[:_]*' -maxdepth 1 -exec rm -- {} \; 2>/dev/null
+rm -rf "$TRACE_DIR" 2>/dev/null
+
+rmdir "$OUT_DIR" 2>/dev/null
+
+if [ -d "$OUT_DIR" ]; then
+  echo "[-] Error: directory '$OUT_DIR' exists and is not empty - delete it first." 1>&2
+  exit 1
+fi
+
+mkdir -m 700 -p "$TRACE_DIR" || exit 1
+
+if [ ! "$STDIN_FILE" = "" ]; then
+  rm -f "$STDIN_FILE" || exit 1
+  touch "$STDIN_FILE" || exit 1
+fi
+
+if [ "$AFL_PATH" = "" ]; then
+  SHOWMAP="${0%/afl-cmin}/afl-showmap"
+else
+  SHOWMAP="$AFL_PATH/afl-showmap"
+fi
+
+if [ ! -x "$SHOWMAP" ]; then
+  echo "[-] Error: can't find 'afl-showmap' - please set AFL_PATH." 1>&2
+  rm -rf "$TRACE_DIR"
+  exit 1
+fi
+
+IN_COUNT=$((`ls -- "$IN_DIR" 2>/dev/null | wc -l`))
+
+if [ "$IN_COUNT" = "0" ]; then
+  echo "[+] Hmm, no inputs in the target directory. Nothing to be done."
+  rm -rf "$TRACE_DIR"
+  exit 1
+fi
+
+FIRST_FILE=`ls "$IN_DIR" | head -1`
+
+# Make sure that we're not dealing with a directory.
+
+if [ -d "$IN_DIR/$FIRST_FILE" ]; then
+  echo "[-] Error: The target directory contains subdirectories - please fix." 1>&2
+  rm -rf "$TRACE_DIR"
+  exit 1
+fi
+
+# Check for the more efficient way to copy files...
+
+if ln "$IN_DIR/$FIRST_FILE" "$TRACE_DIR/.link_test" 2>/dev/null; then
+  CP_TOOL=ln
+else
+  CP_TOOL=cp
+fi
+
+# Make sure that we can actually get anything out of afl-showmap before we
+# waste too much time.
+
+echo "[*] Testing the target binary..."
+
+if [ "$STDIN_FILE" = "" ]; then
+
+  AFL_CMIN_ALLOW_ANY=1 "$SHOWMAP" -m "$MEM_LIMIT" -t "$TIMEOUT" -o "$TRACE_DIR/.run_test" -Z $EXTRA_PAR -- "$@" <"$IN_DIR/$FIRST_FILE"
+
+else
+
+  cp "$IN_DIR/$FIRST_FILE" "$STDIN_FILE"
+  AFL_CMIN_ALLOW_ANY=1 "$SHOWMAP" -m "$MEM_LIMIT" -t "$TIMEOUT" -o "$TRACE_DIR/.run_test" -Z $EXTRA_PAR -A "$STDIN_FILE" -- "$@" </dev/null
+
+fi
+
+FIRST_COUNT=$((`grep -c . "$TRACE_DIR/.run_test"`))
+
+if [ "$FIRST_COUNT" -gt "0" ]; then
+
+  echo "[+] OK, $FIRST_COUNT tuples recorded."
+
+else
+
+  echo "[-] Error: no instrumentation output detected (perhaps crash or timeout)." 1>&2
+  test "$AFL_KEEP_TRACES" = "" && rm -rf "$TRACE_DIR"
+  exit 1
+
+fi
+
+# Let's roll!
+
+#############################
+# STEP 1: COLLECTING TRACES #
+#############################
+
+echo "[*] Obtaining traces for input files in '$IN_DIR'..."
+
+(
+
+  CUR=0
+
+  if [ "$STDIN_FILE" = "" ]; then
+
+    ls "$IN_DIR" | while read -r fn; do
+
+      CUR=$((CUR+1))
+      printf "\\r    Processing file $CUR/$IN_COUNT... "
+
+      "$SHOWMAP" -m "$MEM_LIMIT" -t "$TIMEOUT" -o "$TRACE_DIR/$fn" -Z $EXTRA_PAR -- "$@" <"$IN_DIR/$fn"
+
+    done
+
+  else
+
+    ls "$IN_DIR" | while read -r fn; do
+
+      CUR=$((CUR+1))
+      printf "\\r    Processing file $CUR/$IN_COUNT... "
+
+      cp "$IN_DIR/$fn" "$STDIN_FILE"
+
+      "$SHOWMAP" -m "$MEM_LIMIT" -t "$TIMEOUT" -o "$TRACE_DIR/$fn" -Z $EXTRA_PAR -A "$STDIN_FILE" -- "$@" </dev/null
+
+    done
+
+
+  fi
+
+)
+
+echo
+
+##########################
+# STEP 2: SORTING TUPLES #
+##########################
+
+# With this out of the way, we sort all tuples by popularity across all
+# datasets. The reasoning here is that we won't be able to avoid the files
+# that trigger unique tuples anyway, so we will want to start with them and
+# see what's left.
+
+echo "[*] Sorting trace sets (this may take a while)..."
+
+ls "$IN_DIR" | sed "s#^#$TRACE_DIR/#" | tr '\n' '\0' | xargs -0 -n 1 cat | \
+  sort | uniq -c | sort -k 1,1 -n >"$TRACE_DIR/.all_uniq"
+
+TUPLE_COUNT=$((`grep -c . "$TRACE_DIR/.all_uniq"`))
+
+echo "[+] Found $TUPLE_COUNT unique tuples across $IN_COUNT files."
+
+#####################################
+# STEP 3: SELECTING CANDIDATE FILES #
+#####################################
+
+# The next step is to find the best candidate for each tuple. The "best"
+# part is understood simply as the smallest input that includes a particular
+# tuple in its trace. Empirical evidence suggests that this produces smaller
+# datasets than more involved algorithms that could be still pulled off in
+# a shell script.
+
+echo "[*] Finding best candidates for each tuple..."
+
+CUR=0
+
+ls -rS "$IN_DIR" | while read -r fn; do
+
+  CUR=$((CUR+1))
+  printf "\\r    Processing file $CUR/$IN_COUNT... "
+
+  sed "s#\$# $fn#" "$TRACE_DIR/$fn" >>"$TRACE_DIR/.candidate_list"
+
+done
+
+echo
+
+##############################
+# STEP 4: LOADING CANDIDATES #
+##############################
+
+# At this point, we have a file of tuple-file pairs, sorted by file size
+# in ascending order (as a consequence of ls -rS). By doing sort keyed
+# only by tuple (-k 1,1) and configured to output only the first line for
+# every key (-s -u), we end up with the smallest file for each tuple.
+
+echo "[*] Sorting candidate list (be patient)..."
+
+sort -k1,1 -s -u "$TRACE_DIR/.candidate_list" | \
+  sed 's/^/BEST_FILE[/;s/ /]="/;s/$/"/' >"$TRACE_DIR/.candidate_script"
+
+if [ ! -s "$TRACE_DIR/.candidate_script" ]; then
+  echo "[-] Error: no traces obtained from test cases, check syntax!" 1>&2
+  test "$AFL_KEEP_TRACES" = "" && rm -rf "$TRACE_DIR"
+  exit 1
+fi
+
+# The sed command converted the sorted list to a shell script that populates
+# BEST_FILE[tuple]="fname". Let's load that!
+
+. "$TRACE_DIR/.candidate_script"
+
+##########################
+# STEP 5: WRITING OUTPUT #
+##########################
+
+# The final trick is to grab the top pick for each tuple, unless said tuple is
+# already set due to the inclusion of an earlier candidate; and then put all
+# tuples associated with the newly-added file to the "already have" list. The
+# loop works from least popular tuples and toward the most common ones.
+
+echo "[*] Processing candidates and writing output files..."
+
+CUR=0
+
+touch "$TRACE_DIR/.already_have"
+
+while read -r cnt tuple; do
+
+  CUR=$((CUR+1))
+  printf "\\r    Processing tuple $CUR/$TUPLE_COUNT with count $cnt... "
+
+  # If we already have this tuple, skip it.
+
+  grep -q "^$tuple\$" "$TRACE_DIR/.already_have" && continue
+
+  FN=${BEST_FILE[tuple]}
+
+#  echo "tuple nr $CUR ($tuple cnt=$cnt) -> $FN" >> "$TRACE_DIR/.log"
+  $CP_TOOL "$IN_DIR/$FN" "$OUT_DIR/$FN"
+
+  if [ "$((CUR % 5))" = "0" ]; then
+    sort -u "$TRACE_DIR/$FN" "$TRACE_DIR/.already_have" >"$TRACE_DIR/.tmp"
+    mv -f "$TRACE_DIR/.tmp" "$TRACE_DIR/.already_have"
+  else
+    cat "$TRACE_DIR/$FN" >>"$TRACE_DIR/.already_have"
+  fi
+
+done <"$TRACE_DIR/.all_uniq"
+
+echo
+
+OUT_COUNT=`ls -- "$OUT_DIR" | wc -l`
+
+if [ "$OUT_COUNT" = "1" ]; then
+  echo "[!] WARNING: All test cases had the same traces, check syntax!"
+fi
+
+echo "[+] Narrowed down to $OUT_COUNT files, saved in '$OUT_DIR'."
+echo
+
+test "$AFL_KEEP_TRACES" = "" && rm -rf "$TRACE_DIR"
+
+exit 0

afl-common.c

@@ -1,69 +0,0 @@
-/*
- gather some functions common to multiple executables
-
- detect_file_args
- */
-
-#include <stdlib.h>
-#include <stdio.h>
-#include <strings.h>
-
-#include "debug.h"
-#include "alloc-inl.h"
-
-/* Detect @@ in args. */
-#ifndef __glibc__
-#include <unistd.h>
-#endif
-void detect_file_args(char** argv, u8* prog_in) {
-
-  u32 i = 0;
-#ifdef __GLIBC__
-  u8* cwd = getcwd(NULL, 0); /* non portable glibc extension */
-#else
-  u8* cwd;
-  char *buf;
-  long size = pathconf(".", _PC_PATH_MAX);
-  if ((buf = (char *)malloc((size_t)size)) != NULL) {
-    cwd = getcwd(buf, (size_t)size); /* portable version */
-  } else {
-    PFATAL("getcwd() failed");
-  }
-#endif
-
-  if (!cwd) PFATAL("getcwd() failed");
-
-  while (argv[i]) {
-
-    u8* aa_loc = strstr(argv[i], "@@");
-
-    if (aa_loc) {
-
-      u8 *aa_subst, *n_arg;
-
-      if (!prog_in) FATAL("@@ syntax is not supported by this tool.");
-
-      /* Be sure that we're always using fully-qualified paths. */
-
-      if (prog_in[0] == '/') aa_subst = prog_in;
-      else aa_subst = alloc_printf("%s/%s", cwd, prog_in);
-
-      /* Construct a replacement argv value. */
-
-      *aa_loc = 0;
-      n_arg = alloc_printf("%s%s%s", argv[i], aa_subst, aa_loc + 2);
-      argv[i] = n_arg;
-      *aa_loc = '@';
-
-      if (prog_in[0] != '/') ck_free(aa_subst);
-
-    }
-
-    i++;
-
-  }
-
-  free(cwd); /* not tracked */
-
-}
-

afl-common.h

@@ -1,5 +0,0 @@
-#ifndef __AFLCOMMON_H
-#define __AFLCOMMON_H
-
-void detect_file_args(char **argv, u8 *prog_in);
-#endif

afl-gcc.c

@@ -1,343 +0,0 @@
-/*
-   american fuzzy lop - wrapper for GCC and clang
-   ----------------------------------------------
-
-   Written and maintained by Michal Zalewski <lcamtuf@google.com>
-
-   Copyright 2013, 2014, 2015 Google Inc. All rights reserved.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at:
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
-   This program is a drop-in replacement for GCC or clang. The most common way
-   of using it is to pass the path to afl-gcc or afl-clang via CC when invoking
-   ./configure.
-
-   (Of course, use CXX and point it to afl-g++ / afl-clang++ for C++ code.)
-
-   The wrapper needs to know the path to afl-as (renamed to 'as'). The default
-   is /usr/local/lib/afl/. A convenient way to specify alternative directories
-   would be to set AFL_PATH.
-
-   If AFL_HARDEN is set, the wrapper will compile the target app with various
-   hardening options that may help detect memory management issues more
-   reliably. You can also specify AFL_USE_ASAN to enable ASAN.
-
-   If you want to call a non-default compiler as a next step of the chain,
-   specify its location via AFL_CC or AFL_CXX.
-
- */
-
-#define AFL_MAIN
-
-#include "config.h"
-#include "types.h"
-#include "debug.h"
-#include "alloc-inl.h"
-
-#include <stdio.h>
-#include <unistd.h>
-#include <stdlib.h>
-#include <string.h>
-
-static u8*  as_path;                /* Path to the AFL 'as' wrapper      */
-static u8** cc_params;              /* Parameters passed to the real CC  */
-static u32  cc_par_cnt = 1;         /* Param count, including argv0      */
-static u8   be_quiet,               /* Quiet mode                        */
-            clang_mode;             /* Invoked as afl-clang*?            */
-
-
-/* Try to find our "fake" GNU assembler in AFL_PATH or at the location derived
-   from argv[0]. If that fails, abort. */
-
-static void find_as(u8* argv0) {
-
-  u8 *afl_path = getenv("AFL_PATH");
-  u8 *slash, *tmp;
-
-  if (afl_path) {
-
-    tmp = alloc_printf("%s/as", afl_path);
-
-    if (!access(tmp, X_OK)) {
-      as_path = afl_path;
-      ck_free(tmp);
-      return;
-    }
-
-    ck_free(tmp);
-
-  }
-
-  slash = strrchr(argv0, '/');
-
-  if (slash) {
-
-    u8 *dir;
-
-    *slash = 0;
-    dir = ck_strdup(argv0);
-    *slash = '/';
-
-    tmp = alloc_printf("%s/afl-as", dir);
-
-    if (!access(tmp, X_OK)) {
-      as_path = dir;
-      ck_free(tmp);
-      return;
-    }
-
-    ck_free(tmp);
-    ck_free(dir);
-
-  }
-
-  if (!access(AFL_PATH "/as", X_OK)) {
-    as_path = AFL_PATH;
-    return;
-  }
-
-  FATAL("Unable to find AFL wrapper binary for 'as'. Please set AFL_PATH");
- 
-}
-
-
-/* Copy argv to cc_params, making the necessary edits. */
-
-static void edit_params(u32 argc, char** argv) {
-
-  u8 fortify_set = 0, asan_set = 0;
-  u8 *name;
-
-#if defined(__FreeBSD__) && defined(__x86_64__)
-  u8 m32_set = 0;
-#endif
-
-  cc_params = ck_alloc((argc + 128) * sizeof(u8*));
-
-  name = strrchr(argv[0], '/');
-  if (!name) name = argv[0]; else name++;
-
-  if (!strncmp(name, "afl-clang", 9)) {
-
-    clang_mode = 1;
-
-    setenv(CLANG_ENV_VAR, "1", 1);
-
-    if (!strcmp(name, "afl-clang++")) {
-      u8* alt_cxx = getenv("AFL_CXX");
-      cc_params[0] = alt_cxx ? alt_cxx : (u8*)"clang++";
-    } else {
-      u8* alt_cc = getenv("AFL_CC");
-      cc_params[0] = alt_cc ? alt_cc : (u8*)"clang";
-    }
-
-  } else {
-
-    /* With GCJ and Eclipse installed, you can actually compile Java! The
-       instrumentation will work (amazingly). Alas, unhandled exceptions do
-       not call abort(), so afl-fuzz would need to be modified to equate
-       non-zero exit codes with crash conditions when working with Java
-       binaries. Meh. */
-
-#ifdef __APPLE__
-
-    if (!strcmp(name, "afl-g++")) cc_params[0] = getenv("AFL_CXX");
-    else if (!strcmp(name, "afl-gcj")) cc_params[0] = getenv("AFL_GCJ");
-    else cc_params[0] = getenv("AFL_CC");
-
-    if (!cc_params[0]) {
-
-      SAYF("\n" cLRD "[-] " cRST
-           "On Apple systems, 'gcc' is usually just a wrapper for clang. Please use the\n"
-           "    'afl-clang' utility instead of 'afl-gcc'. If you really have GCC installed,\n"
-           "    set AFL_CC or AFL_CXX to specify the correct path to that compiler.\n");
-
-      FATAL("AFL_CC or AFL_CXX required on MacOS X");
-
-    }
-
-#else
-
-    if (!strcmp(name, "afl-g++")) {
-      u8* alt_cxx = getenv("AFL_CXX");
-      cc_params[0] = alt_cxx ? alt_cxx : (u8*)"g++";
-    } else if (!strcmp(name, "afl-gcj")) {
-      u8* alt_cc = getenv("AFL_GCJ");
-      cc_params[0] = alt_cc ? alt_cc : (u8*)"gcj";
-    } else {
-      u8* alt_cc = getenv("AFL_CC");
-      cc_params[0] = alt_cc ? alt_cc : (u8*)"gcc";
-    }
-
-#endif /* __APPLE__ */
-
-  }
-
-  while (--argc) {
-    u8* cur = *(++argv);
-
-    if (!strncmp(cur, "-B", 2)) {
-
-      if (!be_quiet) WARNF("-B is already set, overriding");
-
-      if (!cur[2] && argc > 1) { argc--; argv++; }
-      continue;
-
-    }
-
-    if (!strcmp(cur, "-integrated-as")) continue;
-
-    if (!strcmp(cur, "-pipe")) continue;
-
-#if defined(__FreeBSD__) && defined(__x86_64__)
-    if (!strcmp(cur, "-m32")) m32_set = 1;
-#endif
-
-    if (!strcmp(cur, "-fsanitize=address") ||
-        !strcmp(cur, "-fsanitize=memory")) asan_set = 1;
-
-    if (strstr(cur, "FORTIFY_SOURCE")) fortify_set = 1;
-
-    cc_params[cc_par_cnt++] = cur;
-
-  }
-
-  cc_params[cc_par_cnt++] = "-B";
-  cc_params[cc_par_cnt++] = as_path;
-
-  if (clang_mode)
-    cc_params[cc_par_cnt++] = "-no-integrated-as";
-
-  if (getenv("AFL_HARDEN")) {
-
-    cc_params[cc_par_cnt++] = "-fstack-protector-all";
-
-    if (!fortify_set)
-      cc_params[cc_par_cnt++] = "-D_FORTIFY_SOURCE=2";
-
-  }
-
-  if (asan_set) {
-
-    /* Pass this on to afl-as to adjust map density. */
-
-    setenv("AFL_USE_ASAN", "1", 1);
-
-  } else if (getenv("AFL_USE_ASAN")) {
-
-    if (getenv("AFL_USE_MSAN"))
-      FATAL("ASAN and MSAN are mutually exclusive");
-
-    if (getenv("AFL_HARDEN"))
-      FATAL("ASAN and AFL_HARDEN are mutually exclusive");
-
-    cc_params[cc_par_cnt++] = "-U_FORTIFY_SOURCE";
-    cc_params[cc_par_cnt++] = "-fsanitize=address";
-
-  } else if (getenv("AFL_USE_MSAN")) {
-
-    if (getenv("AFL_USE_ASAN"))
-      FATAL("ASAN and MSAN are mutually exclusive");
-
-    if (getenv("AFL_HARDEN"))
-      FATAL("MSAN and AFL_HARDEN are mutually exclusive");
-
-    cc_params[cc_par_cnt++] = "-U_FORTIFY_SOURCE";
-    cc_params[cc_par_cnt++] = "-fsanitize=memory";
-
-
-  }
-
-#ifdef USEMMAP
-    cc_params[cc_par_cnt++] = "-lrt";
-#endif
-
-  if (!getenv("AFL_DONT_OPTIMIZE")) {
-
-#if defined(__FreeBSD__) && defined(__x86_64__)
-
-    /* On 64-bit FreeBSD systems, clang -g -m32 is broken, but -m32 itself
-       works OK. This has nothing to do with us, but let's avoid triggering
-       that bug. */
-
-    if (!clang_mode || !m32_set)
-      cc_params[cc_par_cnt++] = "-g";
-
-#else
-
-      cc_params[cc_par_cnt++] = "-g";
-
-#endif
-
-    cc_params[cc_par_cnt++] = "-O3";
-    cc_params[cc_par_cnt++] = "-funroll-loops";
-
-    /* Two indicators that you're building for fuzzing; one of them is
-       AFL-specific, the other is shared with libfuzzer. */
-
-    cc_params[cc_par_cnt++] = "-D__AFL_COMPILER=1";
-    cc_params[cc_par_cnt++] = "-DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION=1";
-
-  }
-
-  if (getenv("AFL_NO_BUILTIN")) {
-
-    cc_params[cc_par_cnt++] = "-fno-builtin-strcmp";
-    cc_params[cc_par_cnt++] = "-fno-builtin-strncmp";
-    cc_params[cc_par_cnt++] = "-fno-builtin-strcasecmp";
-    cc_params[cc_par_cnt++] = "-fno-builtin-strncasecmp";
-    cc_params[cc_par_cnt++] = "-fno-builtin-memcmp";
-    cc_params[cc_par_cnt++] = "-fno-builtin-strstr";
-    cc_params[cc_par_cnt++] = "-fno-builtin-strcasestr";
-
-  }
-
-  cc_params[cc_par_cnt] = NULL;
-
-}
-
-
-/* Main entry point */
-
-int main(int argc, char** argv) {
-
-  if (isatty(2) && !getenv("AFL_QUIET")) {
-
-    SAYF(cCYA "afl-cc" VERSION cRST " by <lcamtuf@google.com>\n");
-    SAYF(cYEL "[!] " cBRI "NOTE: " cRST "afl-gcc is deprecated, llvm_mode is much faster and has more options\n");
-
-  } else be_quiet = 1;
-
-  if (argc < 2) {
-
-    SAYF("\n"
-         "This is a helper application for afl-fuzz. It serves as a drop-in replacement\n"
-         "for gcc or clang, letting you recompile third-party code with the required\n"
-         "runtime instrumentation. A common use pattern would be one of the following:\n\n"
-
-         "  CC=%s/afl-gcc ./configure\n"
-         "  CXX=%s/afl-g++ ./configure\n\n"
-
-         "You can specify custom next-stage toolchain via AFL_CC, AFL_CXX, and AFL_AS.\n"
-         "Setting AFL_HARDEN enables hardening optimizations in the compiled code.\n\n",
-         BIN_PATH, BIN_PATH);
-
-    exit(1);
-
-  }
-
-  find_as(argv[0]);
-
-  edit_params(argc, argv);
-
-  execvp(cc_params[0], (char**)cc_params);
-
-  FATAL("Oops, failed to execute '%s' - check your PATH", cc_params[0]);
-
-  return 0;
-
-}

afl-plot

@@ -1,9 +1,9 @@
 #!/bin/sh
 #
-# american fuzzy lop - Advanced Persistent Graphing
+# american fuzzy lop++ - Advanced Persistent Graphing
 # -------------------------------------------------
 #
-# Written and maintained by Michal Zalewski <lcamtuf@google.com>
+# Originally written by Michal Zalewski
 # Based on a design & prototype by Michael Rash.
 #
 # Copyright 2014, 2015 Google Inc. All rights reserved.
@@ -15,16 +15,16 @@
 #   http://www.apache.org/licenses/LICENSE-2.0
 #
 
-echo "progress plotting utility for afl-fuzz by <lcamtuf@google.com>"
+echo "progress plotting utility for afl-fuzz by Michal Zalewski"
 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.
@@ -32,6 +32,8 @@ an empty directory where this tool can write the resulting plots to.
 The program will put index.html and three PNG images in the output directory;
 you should be able to view it with any web browser of your choice.
 
+Environment variables used:
+AFL_ALLOW_TMP: allow /var/tmp or /tmp for input and output directories
 _EOF_
 
   exit 1
@@ -66,7 +68,7 @@ BANNER="`cat "$1/fuzzer_stats" | grep '^afl_banner ' | cut -d: -f2- | cut -b2-`"
 
 test "$BANNER" = "" && BANNER="(none)"
 
-GNUPLOT=`which gnuplot 2>/dev/null`
+GNUPLOT=`command -v gnuplot 2>/dev/null`
 
 if [ "$GNUPLOT" = "" ]; then
 

afl-showmap.c

@@ -1,709 +0,0 @@
-/*
-   american fuzzy lop - map display utility
-   ----------------------------------------
-
-   Written and maintained by Michal Zalewski <lcamtuf@google.com>
-
-   Copyright 2013, 2014, 2015, 2016, 2017 Google Inc. All rights reserved.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at:
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
-   A very simple tool that runs the targeted binary and displays
-   the contents of the trace bitmap in a human-readable form. Useful in
-   scripts to eliminate redundant inputs and perform other checks.
-
-   Exit code is 2 if the target program crashes; 1 if it times out or
-   there is a problem executing it; or 0 if execution is successful.
-
- */
-
-#define AFL_MAIN
-
-#include "config.h"
-#include "types.h"
-#include "debug.h"
-#include "alloc-inl.h"
-#include "hash.h"
-#include "sharedmem.h"
-#include "afl-common.h"
-
-#include <stdio.h>
-#include <unistd.h>
-#include <stdlib.h>
-#include <string.h>
-#include <time.h>
-#include <errno.h>
-#include <signal.h>
-#include <dirent.h>
-#include <fcntl.h>
-
-#include <sys/wait.h>
-#include <sys/time.h>
-#include <sys/shm.h>
-#include <sys/stat.h>
-#include <sys/types.h>
-#include <sys/resource.h>
-
-static s32 child_pid;                 /* PID of the tested program         */
-
-       u8* trace_bits;                /* SHM with instrumentation bitmap   */
-
-static u8 *out_file,                  /* Trace output file                 */
-          *doc_path,                  /* Path to docs                      */
-          *target_path,               /* Path to target binary             */
-          *at_file;                   /* Substitution string for @@        */
-
-static u32 exec_tmout;                /* Exec timeout (ms)                 */
-
-static u64 mem_limit = MEM_LIMIT;     /* Memory limit (MB)                 */
-
-static u8  quiet_mode,                /* Hide non-essential messages?      */
-           edges_only,                /* Ignore hit counts?                */
-           cmin_mode,                 /* Generate output in afl-cmin mode? */
-           binary_mode,               /* Write output as a binary map      */
-           keep_cores;                /* Allow coredumps?                  */
-
-static volatile u8
-           stop_soon,                 /* Ctrl-C pressed?                   */
-           child_timed_out,           /* Child timed out?                  */
-           child_crashed;             /* Child crashed?                    */
-
-/* Classify tuple counts. Instead of mapping to individual bits, as in
-   afl-fuzz.c, we map to more user-friendly numbers between 1 and 8. */
-
-static const u8 count_class_human[256] = {
-
-  [0]           = 0,
-  [1]           = 1,
-  [2]           = 2,
-  [3]           = 3,
-  [4 ... 7]     = 4,
-  [8 ... 15]    = 5,
-  [16 ... 31]   = 6,
-  [32 ... 127]  = 7,
-  [128 ... 255] = 8
-
-};
-
-static const u8 count_class_binary[256] = {
-
-  [0]           = 0,
-  [1]           = 1,
-  [2]           = 2,
-  [3]           = 4,
-  [4 ... 7]     = 8,
-  [8 ... 15]    = 16,
-  [16 ... 31]   = 32,
-  [32 ... 127]  = 64,
-  [128 ... 255] = 128
-
-};
-
-static void classify_counts(u8* mem, const u8* map) {
-
-  u32 i = MAP_SIZE;
-
-  if (edges_only) {
-
-    while (i--) {
-      if (*mem) *mem = 1;
-      mem++;
-    }
-
-  } else {
-
-    while (i--) {
-      *mem = map[*mem];
-      mem++;
-    }
-
-  }
-
-}
-
-
-/* Write results. */
-
-static u32 write_results(void) {
-
-  s32 fd;
-  u32 i, ret = 0;
-
-  u8  cco = !!getenv("AFL_CMIN_CRASHES_ONLY"),
-      caa = !!getenv("AFL_CMIN_ALLOW_ANY");
-
-  if (!strncmp(out_file, "/dev/", 5)) {
-
-    fd = open(out_file, O_WRONLY, 0600);
-    if (fd < 0) PFATAL("Unable to open '%s'", out_file);
-
-  } else if (!strcmp(out_file, "-")) {
-
-    fd = dup(1);
-    if (fd < 0) PFATAL("Unable to open stdout");
-
-  } else {
-
-    unlink(out_file); /* Ignore errors */
-    fd = open(out_file, O_WRONLY | O_CREAT | O_EXCL, 0600);
-    if (fd < 0) PFATAL("Unable to create '%s'", out_file);
-
-  }
-
-
-  if (binary_mode) {
-
-    for (i = 0; i < MAP_SIZE; i++)
-      if (trace_bits[i]) ret++;
-    
-    ck_write(fd, trace_bits, MAP_SIZE, out_file);
-    close(fd);
-
-  } else {
-
-    FILE* f = fdopen(fd, "w");
-
-    if (!f) PFATAL("fdopen() failed");
-
-    for (i = 0; i < MAP_SIZE; i++) {
-
-      if (!trace_bits[i]) continue;
-      ret++;
-
-      if (cmin_mode) {
-
-        if (child_timed_out) break;
-        if (!caa && child_crashed != cco) break;
-
-        fprintf(f, "%u%u\n", trace_bits[i], i);
-
-      } else fprintf(f, "%06u:%u\n", i, trace_bits[i]);
-
-    }
-  
-    fclose(f);
-
-  }
-
-  return ret;
-
-}
-
-
-/* Handle timeout signal. */
-
-static void handle_timeout(int sig) {
-
-  child_timed_out = 1;
-  if (child_pid > 0) kill(child_pid, SIGKILL);
-
-}
-
-
-/* Execute target application. */
-
-static void run_target(char** argv) {
-
-  static struct itimerval it;
-  int status = 0;
-
-  if (!quiet_mode)
-    SAYF("-- Program output begins --\n" cRST);
-
-  MEM_BARRIER();
-
-  child_pid = fork();
-
-  if (child_pid < 0) PFATAL("fork() failed");
-
-  if (!child_pid) {
-
-    struct rlimit r;
-
-    if (quiet_mode) {
-
-      s32 fd = open("/dev/null", O_RDWR);
-
-      if (fd < 0 || dup2(fd, 1) < 0 || dup2(fd, 2) < 0) {
-        *(u32*)trace_bits = EXEC_FAIL_SIG;
-        PFATAL("Descriptor initialization failed");
-      }
-
-      close(fd);
-
-    }
-
-    if (mem_limit) {
-
-      r.rlim_max = r.rlim_cur = ((rlim_t)mem_limit) << 20;
-
-#ifdef RLIMIT_AS
-
-      setrlimit(RLIMIT_AS, &r); /* Ignore errors */
-
-#else
-
-      setrlimit(RLIMIT_DATA, &r); /* Ignore errors */
-
-#endif /* ^RLIMIT_AS */
-
-    }
-
-    if (!keep_cores) r.rlim_max = r.rlim_cur = 0;
-    else r.rlim_max = r.rlim_cur = RLIM_INFINITY;
-
-    setrlimit(RLIMIT_CORE, &r); /* Ignore errors */
-
-    if (!getenv("LD_BIND_LAZY")) setenv("LD_BIND_NOW", "1", 0);
-
-    setsid();
-
-    execv(target_path, argv);
-
-    *(u32*)trace_bits = EXEC_FAIL_SIG;
-    exit(0);
-
-  }
-
-  /* Configure timeout, wait for child, cancel timeout. */
-
-  if (exec_tmout) {
-
-    child_timed_out = 0;
-    it.it_value.tv_sec = (exec_tmout / 1000);
-    it.it_value.tv_usec = (exec_tmout % 1000) * 1000;
-
-  }
-
-  setitimer(ITIMER_REAL, &it, NULL);
-
-  if (waitpid(child_pid, &status, 0) <= 0) FATAL("waitpid() failed");
-
-  child_pid = 0;
-  it.it_value.tv_sec = 0;
-  it.it_value.tv_usec = 0;
-  setitimer(ITIMER_REAL, &it, NULL);
-
-  MEM_BARRIER();
-
-  /* Clean up bitmap, analyze exit condition, etc. */
-
-  if (*(u32*)trace_bits == EXEC_FAIL_SIG)
-    FATAL("Unable to execute '%s'", argv[0]);
-
-  classify_counts(trace_bits, binary_mode ?
-                  count_class_binary : count_class_human);
-
-  if (!quiet_mode)
-    SAYF(cRST "-- Program output ends --\n");
-
-  if (!child_timed_out && !stop_soon && WIFSIGNALED(status))
-    child_crashed = 1;
-
-  if (!quiet_mode) {
-
-    if (child_timed_out)
-      SAYF(cLRD "\n+++ Program timed off +++\n" cRST);
-    else if (stop_soon)
-      SAYF(cLRD "\n+++ Program aborted by user +++\n" cRST);
-    else if (child_crashed)
-      SAYF(cLRD "\n+++ Program killed by signal %u +++\n" cRST, WTERMSIG(status));
-
-  }
-
-
-}
-
-
-/* Handle Ctrl-C and the like. */
-
-static void handle_stop_sig(int sig) {
-
-  stop_soon = 1;
-
-  if (child_pid > 0) kill(child_pid, SIGKILL);
-
-}
-
-
-/* Do basic preparations - persistent fds, filenames, etc. */
-
-static void set_up_environment(void) {
-
-  setenv("ASAN_OPTIONS", "abort_on_error=1:"
-                         "detect_leaks=0:"
-                         "symbolize=0:"
-                         "allocator_may_return_null=1", 0);
-
-  setenv("MSAN_OPTIONS", "exit_code=" STRINGIFY(MSAN_ERROR) ":"
-                         "symbolize=0:"
-                         "abort_on_error=1:"
-                         "allocator_may_return_null=1:"
-                         "msan_track_origins=0", 0);
-
-  if (getenv("AFL_PRELOAD")) {
-    setenv("LD_PRELOAD", getenv("AFL_PRELOAD"), 1);
-    setenv("DYLD_INSERT_LIBRARIES", getenv("AFL_PRELOAD"), 1);
-  }
-
-}
-
-
-/* Setup signal handlers, duh. */
-
-static void setup_signal_handlers(void) {
-
-  struct sigaction sa;
-
-  sa.sa_handler   = NULL;
-  sa.sa_flags     = SA_RESTART;
-  sa.sa_sigaction = NULL;
-
-  sigemptyset(&sa.sa_mask);
-
-  /* Various ways of saying "stop". */
-
-  sa.sa_handler = handle_stop_sig;
-  sigaction(SIGHUP, &sa, NULL);
-  sigaction(SIGINT, &sa, NULL);
-  sigaction(SIGTERM, &sa, NULL);
-
-  /* Exec timeout notifications. */
-
-  sa.sa_handler = handle_timeout;
-  sigaction(SIGALRM, &sa, NULL);
-
-}
-
-
-/* Show banner. */
-
-static void show_banner(void) {
-
-  SAYF(cCYA "afl-showmap" VERSION cRST " by <lcamtuf@google.com>\n");
-
-}
-
-/* Display usage hints. */
-
-static void usage(u8* argv0) {
-
-  show_banner();
-
-  SAYF("\n%s [ options ] -- /path/to/target_app [ ... ]\n\n"
-
-       "Required parameters:\n\n"
-
-       "  -o file       - file to write the trace data to\n\n"
-
-       "Execution control settings:\n\n"
-
-       "  -t msec       - timeout for each run (none)\n"
-       "  -m megs       - memory limit for child process (%u MB)\n"
-       "  -Q            - use binary-only instrumentation (QEMU mode)\n"
-       "  -U            - use Unicorn-based instrumentation (Unicorn mode)\n"
-       "                  (Not necessary, here for consistency with other afl-* tools)\n\n"  
-
-       "Other settings:\n\n"
-
-       "  -q            - sink program's output and don't show messages\n"
-       "  -e            - show edge coverage only, ignore hit counts\n"
-       "  -c            - allow core dumps\n\n"
-
-       "This tool displays raw tuple data captured by AFL instrumentation.\n"
-       "For additional help, consult %s/README.\n\n" cRST,
-
-       argv0, MEM_LIMIT, doc_path);
-
-  exit(1);
-
-}
-
-
-/* Find binary. */
-
-static void find_binary(u8* fname) {
-
-  u8* env_path = 0;
-  struct stat st;
-
-  if (strchr(fname, '/') || !(env_path = getenv("PATH"))) {
-
-    target_path = ck_strdup(fname);
-
-    if (stat(target_path, &st) || !S_ISREG(st.st_mode) ||
-        !(st.st_mode & 0111) || st.st_size < 4)
-      FATAL("Program '%s' not found or not executable", fname);
-
-  } else {
-
-    while (env_path) {
-
-      u8 *cur_elem, *delim = strchr(env_path, ':');
-
-      if (delim) {
-
-        cur_elem = ck_alloc(delim - env_path + 1);
-        memcpy(cur_elem, env_path, delim - env_path);
-        delim++;
-
-      } else cur_elem = ck_strdup(env_path);
-
-      env_path = delim;
-
-      if (cur_elem[0])
-        target_path = alloc_printf("%s/%s", cur_elem, fname);
-      else
-        target_path = ck_strdup(fname);
-
-      ck_free(cur_elem);
-
-      if (!stat(target_path, &st) && S_ISREG(st.st_mode) &&
-          (st.st_mode & 0111) && st.st_size >= 4) break;
-
-      ck_free(target_path);
-      target_path = 0;
-
-    }
-
-    if (!target_path) FATAL("Program '%s' not found or not executable", fname);
-
-  }
-
-}
-
-
-/* Fix up argv for QEMU. */
-
-static char** get_qemu_argv(u8* own_loc, char** argv, int argc) {
-
-  char** new_argv = ck_alloc(sizeof(char*) * (argc + 4));
-  u8 *tmp, *cp, *rsl, *own_copy;
-
-  memcpy(new_argv + 3, argv + 1, sizeof(char*) * argc);
-
-  new_argv[2] = target_path;
-  new_argv[1] = "--";
-
-  /* Now we need to actually find qemu for argv[0]. */
-
-  tmp = getenv("AFL_PATH");
-
-  if (tmp) {
-
-    cp = alloc_printf("%s/afl-qemu-trace", tmp);
-
-    if (access(cp, X_OK))
-      FATAL("Unable to find '%s'", tmp);
-
-    target_path = new_argv[0] = cp;
-    return new_argv;
-
-  }
-
-  own_copy = ck_strdup(own_loc);
-  rsl = strrchr(own_copy, '/');
-
-  if (rsl) {
-
-    *rsl = 0;
-
-    cp = alloc_printf("%s/afl-qemu-trace", own_copy);
-    ck_free(own_copy);
-
-    if (!access(cp, X_OK)) {
-
-      target_path = new_argv[0] = cp;
-      return new_argv;
-
-    }
-
-  } else ck_free(own_copy);
-
-  if (!access(BIN_PATH "/afl-qemu-trace", X_OK)) {
-
-    target_path = new_argv[0] = BIN_PATH "/afl-qemu-trace";
-    return new_argv;
-
-  }
-
-  FATAL("Unable to find 'afl-qemu-trace'.");
-
-}
-
-/* Main entry point */
-
-int main(int argc, char** argv) {
-
-  s32 opt;
-  u8  mem_limit_given = 0, timeout_given = 0, qemu_mode = 0, unicorn_mode = 0;
-  u32 tcnt;
-  char** use_argv;
-
-  doc_path = access(DOC_PATH, F_OK) ? "docs" : DOC_PATH;
-
-  while ((opt = getopt(argc,argv,"+o:m:t:A:eqZQUbc")) > 0)
-
-    switch (opt) {
-
-      case 'o':
-
-        if (out_file) FATAL("Multiple -o options not supported");
-        out_file = optarg;
-        break;
-
-      case 'm': {
-
-          u8 suffix = 'M';
-
-          if (mem_limit_given) FATAL("Multiple -m options not supported");
-          mem_limit_given = 1;
-
-          if (!strcmp(optarg, "none")) {
-
-            mem_limit = 0;
-            break;
-
-          }
-
-          if (sscanf(optarg, "%llu%c", &mem_limit, &suffix) < 1 ||
-              optarg[0] == '-') FATAL("Bad syntax used for -m");
-
-          switch (suffix) {
-
-            case 'T': mem_limit *= 1024 * 1024; break;
-            case 'G': mem_limit *= 1024; break;
-            case 'k': mem_limit /= 1024; break;
-            case 'M': break;
-
-            default:  FATAL("Unsupported suffix or bad syntax for -m");
-
-          }
-
-          if (mem_limit < 5) FATAL("Dangerously low value of -m");
-
-          if (sizeof(rlim_t) == 4 && mem_limit > 2000)
-            FATAL("Value of -m out of range on 32-bit systems");
-
-        }
-
-        break;
-
-      case 't':
-
-        if (timeout_given) FATAL("Multiple -t options not supported");
-        timeout_given = 1;
-
-        if (strcmp(optarg, "none")) {
-          exec_tmout = atoi(optarg);
-
-          if (exec_tmout < 20 || optarg[0] == '-')
-            FATAL("Dangerously low value of -t");
-
-        }
-
-        break;
-
-      case 'e':
-
-        if (edges_only) FATAL("Multiple -e options not supported");
-        edges_only = 1;
-        break;
-
-      case 'q':
-
-        if (quiet_mode) FATAL("Multiple -q options not supported");
-        quiet_mode = 1;
-        break;
-
-      case 'Z':
-
-        /* This is an undocumented option to write data in the syntax expected
-           by afl-cmin. Nobody else should have any use for this. */
-
-        cmin_mode  = 1;
-        quiet_mode = 1;
-        break;
-
-      case 'A':
-
-        /* Another afl-cmin specific feature. */
-        at_file = optarg;
-        break;
-
-      case 'Q':
-
-        if (qemu_mode) FATAL("Multiple -Q options not supported");
-        if (!mem_limit_given) mem_limit = MEM_LIMIT_QEMU;
-
-        qemu_mode = 1;
-        break;
-
-      case 'U':
-
-        if (unicorn_mode) FATAL("Multiple -U options not supported");
-        if (!mem_limit_given) mem_limit = MEM_LIMIT_UNICORN;
-
-        unicorn_mode = 1;
-        break;
-
-      case 'b':
-
-        /* Secret undocumented mode. Writes output in raw binary format
-           similar to that dumped by afl-fuzz in <out_dir/queue/fuzz_bitmap. */
-
-        binary_mode = 1;
-        break;
-
-      case 'c':
-
-        if (keep_cores) FATAL("Multiple -c options not supported");
-        keep_cores = 1;
-        break;
-
-      default:
-
-        usage(argv[0]);
-
-    }
-
-  if (optind == argc || !out_file) usage(argv[0]);
-
-  setup_shm(0);
-  setup_signal_handlers();
-
-  set_up_environment();
-
-  find_binary(argv[optind]);
-
-  if (!quiet_mode) {
-    show_banner();
-    ACTF("Executing '%s'...\n", target_path);
-  }
-
-  detect_file_args(argv + optind, at_file);
-
-  if (qemu_mode)
-    use_argv = get_qemu_argv(argv[0], argv + optind, argc - optind);
-  else
-    use_argv = argv + optind;
-
-  run_target(use_argv);
-
-  tcnt = write_results();
-
-  if (!quiet_mode) {
-
-    if (!tcnt) FATAL("No instrumentation detected" cRST);
-    OKF("Captured %u tuples in '%s'." cRST, tcnt, out_file);
-
-  }
-
-  exit(child_crashed * 2 + child_timed_out);
-
-}
-

afl-system-config

@@ -1,23 +1,83 @@
 #!/bin/sh
-echo This reconfigures the system to have a better fuzzing performance
+test "$1" = "-h" && {
+  echo 'afl-system-config by Marc Heuse <mh@mh-sec.de>'
+  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
+}
+
+DONE=
+PLATFORM=`uname -s`
+echo This reconfigures the system to have a better fuzzing performance.
 if [ '!' "$EUID" = 0 ] && [ '!' `id -u` = 0 ] ; then
-	echo Error you need to be root to run this
-	exit 1
+	echo "Warning: you need to be root to run this!"
+	# we do not exit as other mechanisms exist that allows to do this than
+	# being root. let the errors speak for themselves.
 fi
-sysctl -w kernel.core_pattern=core
-sysctl -w kernel.randomize_va_space=0
-sysctl -w kernel.sched_child_runs_first=1
-sysctl -w kernel.sched_autogroup_enabled=1
-sysctl -w kernel.sched_migration_cost_ns=50000000
-sysctl -w kernel.sched_latency_ns=250000000
-echo never > /sys/kernel/mm/transparent_hugepage/enabled
-test -e /sys/devices/system/cpu/cpufreq/scaling_governor && echo performance | tee /sys/devices/system/cpu/cpufreq/scaling_governor
-test -e /sys/devices/system/cpu/cpufreq/policy0/scaling_governor && echo performance | tee /sys/devices/system/cpu/cpufreq/policy*/scaling_governor
-test -e /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor && echo performance | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
-test -e /sys/devices/system/cpu/intel_pstate/no_turbo && echo 0 > /sys/devices/system/cpu/intel_pstate/no_turbo
-test -e /sys/devices/system/cpu/cpufreq/boost && echo 1 > /sys/devices/system/cpu/cpufreq/boost
-echo
-echo It is recommended to boot the kernel with lots of security off - if you are running a machine that is in a secured network - so set this:
-echo '/etc/default/grub:GRUB_CMDLINE_LINUX_DEFAULT="ibpb=off ibrs=off kpti=off l1tf=off mds=off mitigations=off no_stf_barrier noibpb noibrs nopcid nopti nospec_store_bypass_disable nospectre_v1 nospectre_v2 pcid=off pti=off spec_store_bypass_disable=off spectre_v2=off stf_barrier=off"'
-echo
-echo Also use AFL_TMPDIR to use a tmpfs for the input file
+if [ "$PLATFORM" = "Linux" ] ; then
+{
+  sysctl -w kernel.core_pattern=core
+  sysctl -w kernel.randomize_va_space=0
+  sysctl -w kernel.sched_child_runs_first=1
+  sysctl -w kernel.sched_autogroup_enabled=1
+  sysctl -w kernel.sched_migration_cost_ns=50000000
+  sysctl -w kernel.sched_latency_ns=250000000
+  echo never > /sys/kernel/mm/transparent_hugepage/enabled
+  test -e /sys/devices/system/cpu/cpufreq/scaling_governor && echo performance | tee /sys/devices/system/cpu/cpufreq/scaling_governor
+  test -e /sys/devices/system/cpu/cpufreq/policy0/scaling_governor && echo performance | tee /sys/devices/system/cpu/cpufreq/policy*/scaling_governor
+  test -e /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor && echo performance | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
+  test -e /sys/devices/system/cpu/intel_pstate/no_turbo && echo 0 > /sys/devices/system/cpu/intel_pstate/no_turbo
+  test -e /sys/devices/system/cpu/cpufreq/boost && echo 1 > /sys/devices/system/cpu/cpufreq/boost
+} > /dev/null
+  echo Settings applied.
+  dmesg | egrep -q 'nospectre_v2|spectre_v2=off' || {
+    echo It is recommended to boot the kernel with lots of security off - if you are running a machine that is in a secured network - so set this:
+    echo '  /etc/default/grub:GRUB_CMDLINE_LINUX_DEFAULT="ibpb=off ibrs=off kpti=off l1tf=off mds=off mitigations=off no_stf_barrier noibpb noibrs nopcid nopti nospec_store_bypass_disable nospectre_v1 nospectre_v2 pcid=off pti=off spec_store_bypass_disable=off spectre_v2=off stf_barrier=off"'
+  }
+  DONE=1
+fi
+if [ "$PLATFORM" = "FreeBSD" ] ; then
+{
+  sysctl kern.elf32.aslr.enable=0
+  sysctl kern.elf64.aslr.enable=0
+} > /dev/null
+  echo Settings applied.
+  echo It is recommended to boot the kernel with lots of security off - if you are running a machine that is in a secured network - so set this:
+  echo '  sysctl hw.ibrs_disable=1'
+  echo 'Setting kern.pmap.pg_ps_enabled=0 into /boot/loader.conf might be helpful too.'
+  DONE=1
+fi
+if [ "$PLATFORM" = "OpenBSD" ] ; then
+  echo
+  echo 'System security features cannot be disabled on OpenBSD.'
+  DONE=1
+fi
+if [ "$PLATFORM" = "NetBSD" ] ; then
+{
+  #echo It is recommended to enable unprivileged users to set cpu affinity
+  #echo to be able to use afl-gotcpu meaningfully.
+  /sbin/sysctl -w security.models.extensions.user_set_cpu_affinity=1
+} > /dev/null
+  echo Settings applied.
+  DONE=1
+fi
+if [ "$PLATFORM" = "Darwin" ] ; then
+  if [ $(launchctl list 2>/dev/null | grep -q '\.ReportCrash$') ] ; then
+    echo We unload the default crash reporter here
+    SL=/System/Library; PL=com.apple.ReportCrash
+    launchctl unload -w ${SL}/LaunchAgents/${PL}.plist
+    sudo launchctl unload -w ${SL}/LaunchDaemons/${PL}.Root.plist
+    echo Settings applied.
+  else
+    echo Nothing to do.
+  fi
+  DONE=1
+fi
+test -z "$DONE" && echo Error: Unknown platform: $PLATFORM
+test -z "$AFL_TMPDIR" && echo Also use AFL_TMPDIR and point it to a tmpfs for the input file caching

afl-whatsup

@@ -1,11 +1,12 @@
 #!/bin/sh
 #
-# american fuzzy lop - status check tool
-# --------------------------------------
+# american fuzzy lop++ - status check tool
+# ----------------------------------------
 #
-# Written and maintained by Michal Zalewski <lcamtuf@google.com>
+# Originally written by Michal Zalewski
 #
 # Copyright 2015 Google Inc. All rights reserved.
+# Copyright 2019-2020 AFLplusplus Project. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,8 +18,16 @@
 # instances of afl-fuzz.
 #
 
-echo "status check tool for afl-fuzz by <lcamtuf@google.com>"
+echo "$0 status check tool for afl-fuzz by Michal Zalewski"
 echo
+test "$1" = "-h" && {
+  echo $0 [-s] output_directory
+  echo
+  echo Options:
+  echo   -s  -  skip details and output summary results only
+  echo
+  exit 1
+}
 
 if [ "$1" = "-s" ]; then
 
@@ -37,7 +46,7 @@ if [ "$DIR" = "" ]; then
   echo "Usage: $0 [ -s ] afl_sync_dir" 1>&2
   echo 1>&2
   echo "The -s option causes the tool to skip all the per-fuzzer trivia and show" 1>&2
-  echo "just the summary results. See docs/parallel_fuzzing.txt for additional tips." 1>&2
+  echo "just the summary results. See docs/parallel_fuzzing.md for additional tips." 1>&2
   echo 1>&2
   exit 1
 
@@ -52,9 +61,16 @@ if [ -d queue ]; then
 
 fi
 
+RED=`tput setaf 9 1 1`
+GREEN=`tput setaf 2 1 1`
+BLUE=`tput setaf 4 1 1`
+YELLOW=`tput setaf 11 1 1`
+NC=`tput sgr0`
+RESET="$NC"
+
 CUR_TIME=`date +%s`
 
-TMP=`mktemp -t .afl-whatsup-XXXXXXXX` || exit 1
+TMP=`mktemp -t .afl-whatsup-XXXXXXXX` || TMP=`mktemp -p /data/local/tmp .afl-whatsup-XXXXXXXX` || TMP=`mktemp -p /data/local/tmp .afl-whatsup-XXXXXXXX` || exit 1
 
 ALIVE_CNT=0
 DEAD_CNT=0
@@ -66,6 +82,12 @@ TOTAL_CRASHES=0
 TOTAL_PFAV=0
 TOTAL_PENDING=0
 
+# Time since last path / crash / hang, formatted as string
+FMT_TIME="0 days 0 hours"
+FMT_PATH="${RED}none seen yet${NC}"
+FMT_CRASH="none seen yet"
+FMT_HANG="none seen yet"
+
 if [ "$SUMMARY_ONLY" = "" ]; then
 
   echo "Individual fuzzers"
@@ -74,6 +96,34 @@ if [ "$SUMMARY_ONLY" = "" ]; then
 
 fi
 
+fmt_duration()
+{
+  DUR_STRING=
+  if [ $1 -eq 0 ]; then
+    return 1
+  fi
+
+  local duration=$((CUR_TIME - $1))
+  local days=$((duration / 60 / 60 / 24))
+  local hours=$(((duration / 60 / 60) % 24))
+  local minutes=$(((duration / 60) % 60))
+  local seconds=$((duration % 60))
+
+  if [ $days -gt 0 ]; then
+    DUR_STRING="$days days, $hours hours"
+  elif [ $hours -gt 0 ]; then
+    DUR_STRING="$hours hours, $minutes minutes"
+  elif [ $minutes -gt 0 ]; then
+    DUR_STRING="$minutes minutes, $seconds seconds"
+  else
+    DUR_STRING="$seconds seconds"
+  fi
+}
+
+FIRST=true
+TOTAL_WCOP=
+TOTAL_LAST_PATH=0
+
 for i in `find . -maxdepth 2 -iname fuzzer_stats | sort`; do
 
   sed 's/^command_line.*$/_skip:1/;s/[ ]*:[ ]*/="/;s/$/"/' "$i" >"$TMP"
@@ -83,9 +133,15 @@ for i in `find . -maxdepth 2 -iname fuzzer_stats | sort`; do
   RUN_DAYS=$((RUN_UNIX / 60 / 60 / 24))
   RUN_HRS=$(((RUN_UNIX / 60 / 60) % 24))
 
+  test -n "$cycles_wo_finds" && {
+    test -z "$FIRST" && TOTAL_WCOP="${TOTAL_WCOP}/"
+    TOTAL_WCOP="${TOTAL_WCOP}${cycles_wo_finds}"
+    FIRST=
+  }
+
   if [ "$SUMMARY_ONLY" = "" ]; then
 
-    echo ">>> $afl_banner ($RUN_DAYS days, $RUN_HRS hrs) <<<"
+    echo ">>> $afl_banner ($RUN_DAYS days, $RUN_HRS hrs) fuzzer PID: $fuzzer_pid <<<"
     echo
 
   fi
@@ -116,8 +172,41 @@ for i in `find . -maxdepth 2 -iname fuzzer_stats | sort`; do
   TOTAL_PENDING=$((TOTAL_PENDING + pending_total))
   TOTAL_PFAV=$((TOTAL_PFAV + pending_favs))
 
+  if [ "$last_path" -gt "$TOTAL_LAST_PATH" ]; then
+    TOTAL_LAST_PATH=$last_path
+  fi
+
   if [ "$SUMMARY_ONLY" = "" ]; then
 
+    # Warnings in red
+    TIMEOUT_PERC=$((exec_timeout * 100 / execs_done))
+    if [ $TIMEOUT_PERC -ge 10 ]; then
+      echo "  ${RED}timeout_ratio $TIMEOUT_PERC%${NC}"
+    fi
+
+    if [ $EXEC_SEC -lt 100 ]; then
+      echo "  ${RED}slow execution, $EXEC_SEC execs/sec${NC}"
+    fi
+
+    fmt_duration $last_path && FMT_PATH=$DUR_STRING
+    fmt_duration $last_crash && FMT_CRASH=$DUR_STRING
+    fmt_duration $last_hang && FMT_HANG=$DUR_STRING
+    FMT_CWOP="not available"
+    test -n "$cycles_wo_finds" && {
+      test "$cycles_wo_finds" = 0 && FMT_CWOP="$cycles_wo_finds"
+      test "$cycles_wo_finds" -gt 10 && FMT_CWOP="${YELLOW}$cycles_wo_finds${NC}"
+      test "$cycles_wo_finds" -gt 50 && FMT_CWOP="${RED}$cycles_wo_finds${NC}"
+    }
+
+    echo "  last_path       : $FMT_PATH"
+    echo "  last_crash      : $FMT_CRASH"
+    echo "  last_hang       : $FMT_HANG"
+    echo "  cycles_wo_finds : $FMT_CWOP"
+
+    CPU_USAGE=$(ps aux | grep $fuzzer_pid | grep -v grep | awk '{print $3}')
+    MEM_USAGE=$(ps aux | grep $fuzzer_pid | grep -v grep | awk '{print $4}')
+
+    echo "  cpu usage $CPU_USAGE%, memory usage $MEM_USAGE%"
     echo "  cycle $((cycles_done + 1)), lifetime speed $EXEC_SEC execs/sec, path $cur_path/$paths_total (${PATH_PERC}%)"
 
     if [ "$unique_crashes" = "0" ]; then
@@ -132,11 +221,28 @@ for i in `find . -maxdepth 2 -iname fuzzer_stats | sort`; do
 
 done
 
+# Formatting for total time, time since last path, crash, and hang
+fmt_duration $((CUR_TIME - TOTAL_TIME)) && FMT_TIME=$DUR_STRING
+# Formatting for total execution
+FMT_EXECS="0 millions"
+EXECS_MILLION=$((TOTAL_EXECS / 1000 / 1000))
+EXECS_THOUSAND=$((TOTAL_EXECS / 1000 % 1000))
+if [ $EXECS_MILLION -gt 9 ]; then
+  FMT_EXECS="$EXECS_MILLION millions"
+elif [ $EXECS_MILLION -gt 0 ]; then
+  FMT_EXECS="$EXECS_MILLION millions, $EXECS_THOUSAND thousands"
+else
+  FMT_EXECS="$EXECS_THOUSAND thousands"
+fi
+
 rm -f "$TMP"
 
 TOTAL_DAYS=$((TOTAL_TIME / 60 / 60 / 24))
 TOTAL_HRS=$(((TOTAL_TIME / 60 / 60) % 24))
 
+test -z "$TOTAL_WCOP" && TOTAL_WCOP="not available"
+fmt_duration $TOTAL_LAST_PATH && TOTAL_LAST_PATH=$DUR_STRING
+
 test "$TOTAL_TIME" = "0" && TOTAL_TIME=1
 
 echo "Summary stats"
@@ -148,9 +254,12 @@ if [ ! "$DEAD_CNT" = "0" ]; then
   echo "      Dead or remote : $DEAD_CNT (excluded from stats)"
 fi
 
-echo "      Total run time : $TOTAL_DAYS days, $TOTAL_HRS hours"
-echo "         Total execs : $((TOTAL_EXECS / 1000 / 1000)) million"
+echo "      Total run time : $FMT_TIME"
+echo "         Total execs : $FMT_EXECS"
 echo "    Cumulative speed : $TOTAL_EPS execs/sec"
+if [ "$ALIVE_CNT" -gt "0" ]; then
+  echo "       Average speed : $((TOTAL_EPS / ALIVE_CNT)) execs/sec"
+fi
 echo "       Pending paths : $TOTAL_PFAV faves, $TOTAL_PENDING total"
 
 if [ "$ALIVE_CNT" -gt "1" ]; then
@@ -158,6 +267,8 @@ if [ "$ALIVE_CNT" -gt "1" ]; then
 fi
 
 echo "       Crashes found : $TOTAL_CRASHES locally unique"
+echo "Cycles without finds : $TOTAL_WCOP"
+echo "  Time without finds : $TOTAL_LAST_PATH"
 echo
 
 exit 0

afl-wine-trace

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+import pefile
+import shutil
+import subprocess
+
+if len(sys.argv) < 2:
+    print("[afl-wine-trace] usage: ./afl-wine-trace binary [args...]\n")
+    exit(1)
+
+if os.getenv("AFL_PATH"):
+    my_dir = os.getenv("AFL_PATH")
+else:
+    my_dir = os.path.dirname(os.path.abspath(__file__))
+
+os.environ["WINELOADERNOEXEC"] = "1"
+
+pe = pefile.PE(sys.argv[1])
+
+if "AFL_ENTRYPOINT" not in os.environ:
+    os.environ["AFL_ENTRYPOINT"] = "0x%x" % (pe.OPTIONAL_HEADER.ImageBase + pe.OPTIONAL_HEADER.AddressOfEntryPoint)
+if not os.getenv("AFL_INST_LIBS"):
+    if "AFL_CODE_START" not in os.environ:
+        os.environ["AFL_CODE_START"] = "0x%x" % (pe.OPTIONAL_HEADER.ImageBase + pe.OPTIONAL_HEADER.BaseOfCode)
+    if "AFL_CODE_END" not in os.environ:
+        os.environ["AFL_CODE_END"] = "0x%x" % (pe.OPTIONAL_HEADER.ImageBase + pe.OPTIONAL_HEADER.BaseOfCode + pe.OPTIONAL_HEADER.SizeOfCode)
+
+if pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_AMD64"] or pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_IA64"]:
+    os.environ["LD_PRELOAD"] = os.path.join(my_dir, "qemu_mode/unsigaction/unsigaction64.so")
+else:
+    os.environ["LD_PRELOAD"] = os.path.join(my_dir, "qemu_mode/unsigaction/unsigaction32.so")
+
+if os.getenv("WINECOV_QEMU_PATH"):
+    qemu_path = os.getenv("WINECOV_QEMU_PATH")
+elif os.path.exists(os.path.join(my_dir, "afl-qemu-trace")):
+    qemu_path = os.path.join(my_dir, "afl-qemu-trace")
+else:
+    qemu_path = "qemu-"
+    if pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_AMD64"] or pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_IA64"]:
+        qemu_path += "x86_64"
+    elif pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_I386"]:
+        qemu_path += "i386"
+    else:
+        print ("[afl-wine-trace] unsuppoted architecture\n")
+        exit(1)
+    qemu_path = shutil.which(qemu_path)
+
+wine_path = None
+if os.getenv("AFL_WINE_PATH"):
+    wine_path = os.getenv("AFL_WINE_PATH")
+else:
+    if not wine_path and shutil.which("wine"):
+        wine_path = shutil.which("wine")
+    if not wine_path and os.path.exists("/usr/bin/wine"):
+        wine_path = "/usr/bin/wine"
+    if not wine_path and os.path.exists("/usr/lib/wine/wine"):
+        wine_path = "/usr/lib/wine/wine"
+    if pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_AMD64"] or pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_IA64"]:
+        wine_path += "64"
+    elif pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_I386"]:
+        pass
+    else:
+        print ("[afl-wine-trace] unsopported architecture\n")
+        exit(1)
+
+argv = sys.argv[1:]
+for i in range(len(argv)):
+    if ".cur_input" in argv[i]:
+        argv[i] = subprocess.run([os.path.join(os.path.dirname(wine_path), "winepath"), "--windows", argv[i]], universal_newlines=True, stdout=subprocess.PIPE).stdout
+        break
+
+print("[afl-wine-trace] exec:", " ".join([qemu_path, wine_path] + argv))
+os.execve(qemu_path, [qemu_path, wine_path] + argv, os.environ)

alloc-inl.h

@@ -1,582 +0,0 @@
-/*
-   american fuzzy lop - error-checking, memory-zeroing alloc routines
-   ------------------------------------------------------------------
-
-   Written and maintained by Michal Zalewski <lcamtuf@google.com>
-
-   Copyright 2013, 2014, 2015 Google Inc. All rights reserved.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at:
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
-   This allocator is not designed to resist malicious attackers (the canaries
-   are small and predictable), but provides a robust and portable way to detect
-   use-after-free, off-by-one writes, stale pointers, and so on.
-
- */
-
-#ifndef _HAVE_ALLOC_INL_H
-#define _HAVE_ALLOC_INL_H
-
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-
-#include "config.h"
-#include "types.h"
-#include "debug.h"
-
-/* User-facing macro to sprintf() to a dynamically allocated buffer. */
-
-#define alloc_printf(_str...) ({ \
-    u8* _tmp; \
-    s32 _len = snprintf(NULL, 0, _str); \
-    if (_len < 0) FATAL("Whoa, snprintf() fails?!"); \
-    _tmp = ck_alloc(_len + 1); \
-    snprintf((char*)_tmp, _len + 1, _str); \
-    _tmp; \
-  })
-
-/* Macro to enforce allocation limits as a last-resort defense against
-   integer overflows. */
-
-#define ALLOC_CHECK_SIZE(_s) do { \
-    if ((_s) > MAX_ALLOC) \
-      ABORT("Bad alloc request: %u bytes", (_s)); \
-  } while (0)
-
-/* Macro to check malloc() failures and the like. */
-
-#define ALLOC_CHECK_RESULT(_r, _s) do { \
-    if (!(_r)) \
-      ABORT("Out of memory: can't allocate %u bytes", (_s)); \
-  } while (0)
-
-/* Magic tokens used to mark used / freed chunks. */
-
-#define ALLOC_MAGIC_C1  0xFF00FF00 /* Used head (dword)  */
-#define ALLOC_MAGIC_F   0xFE00FE00 /* Freed head (dword) */
-#define ALLOC_MAGIC_C2  0xF0       /* Used tail (byte)   */
-
-/* Positions of guard tokens in relation to the user-visible pointer. */
-
-#define ALLOC_C1(_ptr)  (((u32*)(_ptr))[-2])
-#define ALLOC_S(_ptr)   (((u32*)(_ptr))[-1])
-#define ALLOC_C2(_ptr)  (((u8*)(_ptr))[ALLOC_S(_ptr)])
-
-#define ALLOC_OFF_HEAD  8
-#define ALLOC_OFF_TOTAL (ALLOC_OFF_HEAD + 1)
-
-/* Allocator increments for ck_realloc_block(). */
-
-#define ALLOC_BLK_INC    256
-
-/* Sanity-checking macros for pointers. */
-
-#define CHECK_PTR(_p) do { \
-    if (_p) { \
-      if (ALLOC_C1(_p) ^ ALLOC_MAGIC_C1) {\
-        if (ALLOC_C1(_p) == ALLOC_MAGIC_F) \
-          ABORT("Use after free."); \
-        else ABORT("Corrupted head alloc canary."); \
-      } \
-   } \
-  } while (0)
-
-/*
-#define CHECK_PTR(_p) do { \
-    if (_p) { \
-      if (ALLOC_C1(_p) ^ ALLOC_MAGIC_C1) {\
-        if (ALLOC_C1(_p) == ALLOC_MAGIC_F) \
-          ABORT("Use after free."); \
-        else ABORT("Corrupted head alloc canary."); \
-      } \
-      if (ALLOC_C2(_p) ^ ALLOC_MAGIC_C2) \
-        ABORT("Corrupted tail alloc canary."); \
-    } \
-  } while (0)
-*/
-
-#define CHECK_PTR_EXPR(_p) ({ \
-    typeof (_p) _tmp = (_p); \
-    CHECK_PTR(_tmp); \
-    _tmp; \
-  })
-
-
-/* Allocate a buffer, explicitly not zeroing it. Returns NULL for zero-sized
-   requests. */
-
-static inline void* DFL_ck_alloc_nozero(u32 size) {
-
-  void* ret;
-
-  if (!size) return NULL;
-
-  ALLOC_CHECK_SIZE(size);
-  ret = malloc(size + ALLOC_OFF_TOTAL);
-  ALLOC_CHECK_RESULT(ret, size);
-
-  ret += ALLOC_OFF_HEAD;
-
-  ALLOC_C1(ret) = ALLOC_MAGIC_C1;
-  ALLOC_S(ret)  = size;
-  ALLOC_C2(ret) = ALLOC_MAGIC_C2;
-
-  return ret;
-
-}
-
-
-/* Allocate a buffer, returning zeroed memory. */
-
-static inline void* DFL_ck_alloc(u32 size) {
-
-  void* mem;
-
-  if (!size) return NULL;
-  mem = DFL_ck_alloc_nozero(size);
-
-  return memset(mem, 0, size);
-
-}
-
-
-/* Free memory, checking for double free and corrupted heap. When DEBUG_BUILD
-   is set, the old memory will be also clobbered with 0xFF. */
-
-static inline void DFL_ck_free(void* mem) {
-
-  if (!mem) return;
-
-  CHECK_PTR(mem);
-
-#ifdef DEBUG_BUILD
-
-  /* Catch pointer issues sooner. */
-  memset(mem, 0xFF, ALLOC_S(mem));
-
-#endif /* DEBUG_BUILD */
-
-  ALLOC_C1(mem) = ALLOC_MAGIC_F;
-
-  free(mem - ALLOC_OFF_HEAD);
-
-}
-
-
-/* Re-allocate a buffer, checking for issues and zeroing any newly-added tail.
-   With DEBUG_BUILD, the buffer is always reallocated to a new addresses and the
-   old memory is clobbered with 0xFF. */
-
-static inline void* DFL_ck_realloc(void* orig, u32 size) {
-
-  void* ret;
-  u32   old_size = 0;
-
-  if (!size) {
-
-    DFL_ck_free(orig);
-    return NULL;
-
-  }
-
-  if (orig) {
-
-    CHECK_PTR(orig);
-
-#ifndef DEBUG_BUILD
-    ALLOC_C1(orig) = ALLOC_MAGIC_F;
-#endif /* !DEBUG_BUILD */
-
-    old_size  = ALLOC_S(orig);
-    orig     -= ALLOC_OFF_HEAD;
-
-    ALLOC_CHECK_SIZE(old_size);
-
-  }
-
-  ALLOC_CHECK_SIZE(size);
-
-#ifndef DEBUG_BUILD
-
-  ret = realloc(orig, size + ALLOC_OFF_TOTAL);
-  ALLOC_CHECK_RESULT(ret, size);
-
-#else
-
-  /* Catch pointer issues sooner: force relocation and make sure that the
-     original buffer is wiped. */
-
-  ret = malloc(size + ALLOC_OFF_TOTAL);
-  ALLOC_CHECK_RESULT(ret, size);
-
-  if (orig) {
-
-    memcpy(ret + ALLOC_OFF_HEAD, orig + ALLOC_OFF_HEAD, MIN(size, old_size));
-    memset(orig + ALLOC_OFF_HEAD, 0xFF, old_size);
-
-    ALLOC_C1(orig + ALLOC_OFF_HEAD) = ALLOC_MAGIC_F;
-
-    free(orig);
-
-  }
-
-#endif /* ^!DEBUG_BUILD */
-
-  ret += ALLOC_OFF_HEAD;
-
-  ALLOC_C1(ret) = ALLOC_MAGIC_C1;
-  ALLOC_S(ret)  = size;
-  ALLOC_C2(ret) = ALLOC_MAGIC_C2;
-
-  if (size > old_size)
-    memset(ret + old_size, 0, size - old_size);
-
-  return ret;
-
-}
-
-
-/* Re-allocate a buffer with ALLOC_BLK_INC increments (used to speed up
-   repeated small reallocs without complicating the user code). */
-
-static inline void* DFL_ck_realloc_block(void* orig, u32 size) {
-
-#ifndef DEBUG_BUILD
-
-  if (orig) {
-
-    CHECK_PTR(orig);
-
-    if (ALLOC_S(orig) >= size) return orig;
-
-    size += ALLOC_BLK_INC;
-
-  }
-
-#endif /* !DEBUG_BUILD */
-
-  return DFL_ck_realloc(orig, size);
-
-}
-
-
-/* Create a buffer with a copy of a string. Returns NULL for NULL inputs. */
-
-static inline u8* DFL_ck_strdup(u8* str) {
-
-  void* ret;
-  u32   size;
-
-  if (!str) return NULL;
-
-  size = strlen((char*)str) + 1;
-
-  ALLOC_CHECK_SIZE(size);
-  ret = malloc(size + ALLOC_OFF_TOTAL);
-  ALLOC_CHECK_RESULT(ret, size);
-
-  ret += ALLOC_OFF_HEAD;
-
-  ALLOC_C1(ret) = ALLOC_MAGIC_C1;
-  ALLOC_S(ret)  = size;
-  ALLOC_C2(ret) = ALLOC_MAGIC_C2;
-
-  return memcpy(ret, str, size);
-
-}
-
-
-/* Create a buffer with a copy of a memory block. Returns NULL for zero-sized
-   or NULL inputs. */
-
-static inline void* DFL_ck_memdup(void* mem, u32 size) {
-
-  void* ret;
-
-  if (!mem || !size) return NULL;
-
-  ALLOC_CHECK_SIZE(size);
-  ret = malloc(size + ALLOC_OFF_TOTAL);
-  ALLOC_CHECK_RESULT(ret, size);
-  
-  ret += ALLOC_OFF_HEAD;
-
-  ALLOC_C1(ret) = ALLOC_MAGIC_C1;
-  ALLOC_S(ret)  = size;
-  ALLOC_C2(ret) = ALLOC_MAGIC_C2;
-
-  return memcpy(ret, mem, size);
-
-}
-
-
-/* Create a buffer with a block of text, appending a NUL terminator at the end.
-   Returns NULL for zero-sized or NULL inputs. */
-
-static inline u8* DFL_ck_memdup_str(u8* mem, u32 size) {
-
-  u8* ret;
-
-  if (!mem || !size) return NULL;
-
-  ALLOC_CHECK_SIZE(size);
-  ret = malloc(size + ALLOC_OFF_TOTAL + 1);
-  ALLOC_CHECK_RESULT(ret, size);
-  
-  ret += ALLOC_OFF_HEAD;
-
-  ALLOC_C1(ret) = ALLOC_MAGIC_C1;
-  ALLOC_S(ret)  = size;
-  ALLOC_C2(ret) = ALLOC_MAGIC_C2;
-
-  memcpy(ret, mem, size);
-  ret[size] = 0;
-
-  return ret;
-
-}
-
-
-#ifndef DEBUG_BUILD
-
-/* In non-debug mode, we just do straightforward aliasing of the above functions
-   to user-visible names such as ck_alloc(). */
-
-#define ck_alloc          DFL_ck_alloc
-#define ck_alloc_nozero   DFL_ck_alloc_nozero
-#define ck_realloc        DFL_ck_realloc
-#define ck_realloc_block  DFL_ck_realloc_block
-#define ck_strdup         DFL_ck_strdup
-#define ck_memdup         DFL_ck_memdup
-#define ck_memdup_str     DFL_ck_memdup_str
-#define ck_free           DFL_ck_free
-
-#define alloc_report()
-
-#else
-
-/* In debugging mode, we also track allocations to detect memory leaks, and the
-   flow goes through one more layer of indirection. */
-
-/* Alloc tracking data structures: */
-
-#define ALLOC_BUCKETS     4096
-
-struct TRK_obj {
-  void *ptr;
-  char *file, *func;
-  u32  line;
-};
-
-#ifdef AFL_MAIN
-
-struct TRK_obj* TRK[ALLOC_BUCKETS];
-u32 TRK_cnt[ALLOC_BUCKETS];
-
-#  define alloc_report() TRK_report()
-
-#else
-
-extern struct TRK_obj* TRK[ALLOC_BUCKETS];
-extern u32 TRK_cnt[ALLOC_BUCKETS];
-
-#  define alloc_report()
-
-#endif /* ^AFL_MAIN */
-
-/* Bucket-assigning function for a given pointer: */
-
-#define TRKH(_ptr) (((((u32)(_ptr)) >> 16) ^ ((u32)(_ptr))) % ALLOC_BUCKETS)
-
-
-/* Add a new entry to the list of allocated objects. */
-
-static inline void TRK_alloc_buf(void* ptr, const char* file, const char* func,
-                                 u32 line) {
-
-  u32 i, bucket;
-
-  if (!ptr) return;
-
-  bucket = TRKH(ptr);
-
-  /* Find a free slot in the list of entries for that bucket. */
-
-  for (i = 0; i < TRK_cnt[bucket]; i++)
-
-    if (!TRK[bucket][i].ptr) {
-
-      TRK[bucket][i].ptr  = ptr;
-      TRK[bucket][i].file = (char*)file;
-      TRK[bucket][i].func = (char*)func;
-      TRK[bucket][i].line = line;
-      return;
-
-    }
-
-  /* No space available - allocate more. */
-
-  TRK[bucket] = DFL_ck_realloc_block(TRK[bucket],
-    (TRK_cnt[bucket] + 1) * sizeof(struct TRK_obj));
-
-  TRK[bucket][i].ptr  = ptr;
-  TRK[bucket][i].file = (char*)file;
-  TRK[bucket][i].func = (char*)func;
-  TRK[bucket][i].line = line;
-
-  TRK_cnt[bucket]++;
-
-}
-
-
-/* Remove entry from the list of allocated objects. */
-
-static inline void TRK_free_buf(void* ptr, const char* file, const char* func,
-                                u32 line) {
-
-  u32 i, bucket;
-
-  if (!ptr) return;
-
-  bucket = TRKH(ptr);
-
-  /* Find the element on the list... */
-
-  for (i = 0; i < TRK_cnt[bucket]; i++)
-
-    if (TRK[bucket][i].ptr == ptr) {
-
-      TRK[bucket][i].ptr = 0;
-      return;
-
-    }
-
-  WARNF("ALLOC: Attempt to free non-allocated memory in %s (%s:%u)",
-        func, file, line);
-
-}
-
-
-/* Do a final report on all non-deallocated objects. */
-
-static inline void TRK_report(void) {
-
-  u32 i, bucket;
-
-  fflush(0);
-
-  for (bucket = 0; bucket < ALLOC_BUCKETS; bucket++)
-    for (i = 0; i < TRK_cnt[bucket]; i++)
-      if (TRK[bucket][i].ptr)
-        WARNF("ALLOC: Memory never freed, created in %s (%s:%u)",
-              TRK[bucket][i].func, TRK[bucket][i].file, TRK[bucket][i].line);
-
-}
-
-
-/* Simple wrappers for non-debugging functions: */
-
-static inline void* TRK_ck_alloc(u32 size, const char* file, const char* func,
-                                 u32 line) {
-
-  void* ret = DFL_ck_alloc(size);
-  TRK_alloc_buf(ret, file, func, line);
-  return ret;
-
-}
-
-
-static inline void* TRK_ck_realloc(void* orig, u32 size, const char* file,
-                                   const char* func, u32 line) {
-
-  void* ret = DFL_ck_realloc(orig, size);
-  TRK_free_buf(orig, file, func, line);
-  TRK_alloc_buf(ret, file, func, line);
-  return ret;
-
-}
-
-
-static inline void* TRK_ck_realloc_block(void* orig, u32 size, const char* file,
-                                         const char* func, u32 line) {
-
-  void* ret = DFL_ck_realloc_block(orig, size);
-  TRK_free_buf(orig, file, func, line);
-  TRK_alloc_buf(ret, file, func, line);
-  return ret;
-
-}
-
-
-static inline void* TRK_ck_strdup(u8* str, const char* file, const char* func,
-                                  u32 line) {
-
-  void* ret = DFL_ck_strdup(str);
-  TRK_alloc_buf(ret, file, func, line);
-  return ret;
-
-}
-
-
-static inline void* TRK_ck_memdup(void* mem, u32 size, const char* file,
-                                  const char* func, u32 line) {
-
-  void* ret = DFL_ck_memdup(mem, size);
-  TRK_alloc_buf(ret, file, func, line);
-  return ret;
-
-}
-
-
-static inline void* TRK_ck_memdup_str(void* mem, u32 size, const char* file,
-                                      const char* func, u32 line) {
-
-  void* ret = DFL_ck_memdup_str(mem, size);
-  TRK_alloc_buf(ret, file, func, line);
-  return ret;
-
-}
-
-
-static inline void TRK_ck_free(void* ptr, const char* file,
-                                const char* func, u32 line) {
-
-  TRK_free_buf(ptr, file, func, line);
-  DFL_ck_free(ptr);
-
-}
-
-/* Aliasing user-facing names to tracking functions: */
-
-#define ck_alloc(_p1) \
-  TRK_ck_alloc(_p1, __FILE__, __FUNCTION__, __LINE__)
-
-#define ck_alloc_nozero(_p1) \
-  TRK_ck_alloc(_p1, __FILE__, __FUNCTION__, __LINE__)
-
-#define ck_realloc(_p1, _p2) \
-  TRK_ck_realloc(_p1, _p2, __FILE__, __FUNCTION__, __LINE__)
-
-#define ck_realloc_block(_p1, _p2) \
-  TRK_ck_realloc_block(_p1, _p2, __FILE__, __FUNCTION__, __LINE__)
-
-#define ck_strdup(_p1) \
-  TRK_ck_strdup(_p1, __FILE__, __FUNCTION__, __LINE__)
-
-#define ck_memdup(_p1, _p2) \
-  TRK_ck_memdup(_p1, _p2, __FILE__, __FUNCTION__, __LINE__)
-
-#define ck_memdup_str(_p1, _p2) \
-  TRK_ck_memdup_str(_p1, _p2, __FILE__, __FUNCTION__, __LINE__)
-
-#define ck_free(_p1) \
-  TRK_ck_free(_p1, __FILE__, __FUNCTION__, __LINE__)
-
-#endif /* ^!DEBUG_BUILD */
-
-#endif /* ! _HAVE_ALLOC_INL_H */

config.h

@@ -1,359 +0,0 @@
-/*
-   american fuzzy lop plus plus - vaguely configurable bits
-   ----------------------------------------------
-
-   Written and maintained by Michal Zalewski <lcamtuf@google.com>
-
-   Copyright 2013, 2014, 2015, 2016 Google Inc. All rights reserved.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at:
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
- */
-
-#ifndef _HAVE_CONFIG_H
-#define _HAVE_CONFIG_H
-
-#include "types.h"
-
-/* Version string: */
-
-#define VERSION             "++2.53c"
-
-/******************************************************
- *                                                    *
- *  Settings that may be of interest to power users:  *
- *                                                    *
- ******************************************************/
-
-/* Comment out to disable terminal colors (note that this makes afl-analyze
-   a lot less nice): */
-
-#define USE_COLOR
-
-/* Comment out to disable fancy ANSI boxes and use poor man's 7-bit UI: */
-
-#define FANCY_BOXES
-
-/* Default timeout for fuzzed code (milliseconds). This is the upper bound,
-   also used for detecting hangs; the actual value is auto-scaled: */
-
-#define EXEC_TIMEOUT        1000
-
-/* Timeout rounding factor when auto-scaling (milliseconds): */
-
-#define EXEC_TM_ROUND       20
-
-/* Default memory limit for child process (MB): */
-
-#ifndef __x86_64__ 
-#  define MEM_LIMIT         25
-#else
-#  define MEM_LIMIT         50
-#endif /* ^!__x86_64__ */
-
-/* Default memory limit when running in QEMU mode (MB): */
-
-#define MEM_LIMIT_QEMU      200
-
-/* Default memory limit when running in Unicorn mode (MB): */
-
-#define MEM_LIMIT_UNICORN   200
-
-/* Number of calibration cycles per every new test case (and for test
-   cases that show variable behavior): */
-
-#define CAL_CYCLES          8
-#define CAL_CYCLES_LONG     40
-
-/* Number of subsequent timeouts before abandoning an input file: */
-
-#define TMOUT_LIMIT         250
-
-/* Maximum number of unique hangs or crashes to record: */
-
-#define KEEP_UNIQUE_HANG    500
-#define KEEP_UNIQUE_CRASH   5000
-
-/* Baseline number of random tweaks during a single 'havoc' stage: */
-
-#define HAVOC_CYCLES        256
-#define HAVOC_CYCLES_INIT   1024
-
-/* Maximum multiplier for the above (should be a power of two, beware
-   of 32-bit int overflows): */
-
-#define HAVOC_MAX_MULT      16
-#define HAVOC_MAX_MULT_MOPT 32
-
-/* Absolute minimum number of havoc cycles (after all adjustments): */
-
-#define HAVOC_MIN           16
-
-/* Power Schedule Divisor */
-#define POWER_BETA          1
-#define MAX_FACTOR          (POWER_BETA * 32)
-
-/* Maximum stacking for havoc-stage tweaks. The actual value is calculated
-   like this: 
-
-   n = random between 1 and HAVOC_STACK_POW2
-   stacking = 2^n
-
-   In other words, the default (n = 7) produces 2, 4, 8, 16, 32, 64, or
-   128 stacked tweaks: */
-
-#define HAVOC_STACK_POW2    7
-
-/* Caps on block sizes for cloning and deletion operations. Each of these
-   ranges has a 33% probability of getting picked, except for the first
-   two cycles where smaller blocks are favored: */
-
-#define HAVOC_BLK_SMALL     32
-#define HAVOC_BLK_MEDIUM    128
-#define HAVOC_BLK_LARGE     1500
-
-/* Extra-large blocks, selected very rarely (<5% of the time): */
-
-#define HAVOC_BLK_XL        32768
-
-/* Probabilities of skipping non-favored entries in the queue, expressed as
-   percentages: */
-
-#define SKIP_TO_NEW_PROB    99 /* ...when there are new, pending favorites */
-#define SKIP_NFAV_OLD_PROB  95 /* ...no new favs, cur entry already fuzzed */
-#define SKIP_NFAV_NEW_PROB  75 /* ...no new favs, cur entry not fuzzed yet */
-
-/* Splicing cycle count: */
-
-#define SPLICE_CYCLES       15
-
-/* Nominal per-splice havoc cycle length: */
-
-#define SPLICE_HAVOC        32
-
-/* Maximum offset for integer addition / subtraction stages: */
-
-#define ARITH_MAX           35
-
-/* Limits for the test case trimmer. The absolute minimum chunk size; and
-   the starting and ending divisors for chopping up the input file: */
-
-#define TRIM_MIN_BYTES      4
-#define TRIM_START_STEPS    16
-#define TRIM_END_STEPS      1024
-
-/* Maximum size of input file, in bytes (keep under 100MB): */
-
-#define MAX_FILE            (1 * 1024 * 1024)
-
-/* The same, for the test case minimizer: */
-
-#define TMIN_MAX_FILE       (10 * 1024 * 1024)
-
-/* Block normalization steps for afl-tmin: */
-
-#define TMIN_SET_MIN_SIZE   4
-#define TMIN_SET_STEPS      128
-
-/* Maximum dictionary token size (-x), in bytes: */
-
-#define MAX_DICT_FILE       128
-
-/* Length limits for auto-detected dictionary tokens: */
-
-#define MIN_AUTO_EXTRA      3
-#define MAX_AUTO_EXTRA      32
-
-/* Maximum number of user-specified dictionary tokens to use in deterministic
-   steps; past this point, the "extras/user" step will be still carried out,
-   but with proportionally lower odds: */
-
-#define MAX_DET_EXTRAS      200
-
-/* Maximum number of auto-extracted dictionary tokens to actually use in fuzzing
-   (first value), and to keep in memory as candidates. The latter should be much
-   higher than the former. */
-
-#define USE_AUTO_EXTRAS     50
-#define MAX_AUTO_EXTRAS     (USE_AUTO_EXTRAS * 10)
-
-/* Scaling factor for the effector map used to skip some of the more
-   expensive deterministic steps. The actual divisor is set to
-   2^EFF_MAP_SCALE2 bytes: */
-
-#define EFF_MAP_SCALE2      3
-
-/* Minimum input file length at which the effector logic kicks in: */
-
-#define EFF_MIN_LEN         128
-
-/* Maximum effector density past which everything is just fuzzed
-   unconditionally (%): */
-
-#define EFF_MAX_PERC        90
-
-/* UI refresh frequency (Hz): */
-
-#define UI_TARGET_HZ        5
-
-/* Fuzzer stats file and plot update intervals (sec): */
-
-#define STATS_UPDATE_SEC    60
-#define PLOT_UPDATE_SEC     5
-
-/* Smoothing divisor for CPU load and exec speed stats (1 - no smoothing). */
-
-#define AVG_SMOOTHING       16
-
-/* Sync interval (every n havoc cycles): */
-
-#define SYNC_INTERVAL       5
-
-/* Output directory reuse grace period (minutes): */
-
-#define OUTPUT_GRACE        25
-
-/* Uncomment to use simple file names (id_NNNNNN): */
-
-// #define SIMPLE_FILES
-
-/* List of interesting values to use in fuzzing. */
-
-#define INTERESTING_8 \
-  -128,          /* Overflow signed 8-bit when decremented  */ \
-  -1,            /*                                         */ \
-   0,            /*                                         */ \
-   1,            /*                                         */ \
-   16,           /* One-off with common buffer size         */ \
-   32,           /* One-off with common buffer size         */ \
-   64,           /* One-off with common buffer size         */ \
-   100,          /* One-off with common buffer size         */ \
-   127           /* Overflow signed 8-bit when incremented  */
-
-#define INTERESTING_16 \
-  -32768,        /* Overflow signed 16-bit when decremented */ \
-  -129,          /* Overflow signed 8-bit                   */ \
-   128,          /* Overflow signed 8-bit                   */ \
-   255,          /* Overflow unsig 8-bit when incremented   */ \
-   256,          /* Overflow unsig 8-bit                    */ \
-   512,          /* One-off with common buffer size         */ \
-   1000,         /* One-off with common buffer size         */ \
-   1024,         /* One-off with common buffer size         */ \
-   4096,         /* One-off with common buffer size         */ \
-   32767         /* Overflow signed 16-bit when incremented */
-
-#define INTERESTING_32 \
-  -2147483648LL, /* Overflow signed 32-bit when decremented */ \
-  -100663046,    /* Large negative number (endian-agnostic) */ \
-  -32769,        /* Overflow signed 16-bit                  */ \
-   32768,        /* Overflow signed 16-bit                  */ \
-   65535,        /* Overflow unsig 16-bit when incremented  */ \
-   65536,        /* Overflow unsig 16 bit                   */ \
-   100663045,    /* Large positive number (endian-agnostic) */ \
-   2147483647    /* Overflow signed 32-bit when incremented */
-
-/***********************************************************
- *                                                         *
- *  Really exotic stuff you probably don't want to touch:  *
- *                                                         *
- ***********************************************************/
-
-/* Call count interval between reseeding the libc PRNG from /dev/urandom: */
-
-#define RESEED_RNG          10000
-
-/* Maximum line length passed from GCC to 'as' and used for parsing
-   configuration files: */
-
-#define MAX_LINE            8192
-
-/* Environment variable used to pass SHM ID to the called program. */
-
-#define SHM_ENV_VAR         "__AFL_SHM_ID"
-
-/* Other less interesting, internal-only variables. */
-
-#define CLANG_ENV_VAR       "__AFL_CLANG_MODE"
-#define AS_LOOP_ENV_VAR     "__AFL_AS_LOOPCHECK"
-#define PERSIST_ENV_VAR     "__AFL_PERSISTENT"
-#define DEFER_ENV_VAR       "__AFL_DEFER_FORKSRV"
-
-/* In-code signatures for deferred and persistent mode. */
-
-#define PERSIST_SIG         "##SIG_AFL_PERSISTENT##"
-#define DEFER_SIG           "##SIG_AFL_DEFER_FORKSRV##"
-
-/* Distinctive bitmap signature used to indicate failed execution: */
-
-#define EXEC_FAIL_SIG       0xfee1dead
-
-/* Distinctive exit code used to indicate MSAN trip condition: */
-
-#define MSAN_ERROR          86
-
-/* Designated file descriptors for forkserver commands (the application will
-   use FORKSRV_FD and FORKSRV_FD + 1): */
-
-#define FORKSRV_FD          198
-
-/* Fork server init timeout multiplier: we'll wait the user-selected
-   timeout plus this much for the fork server to spin up. */
-
-#define FORK_WAIT_MULT      10
-
-/* Calibration timeout adjustments, to be a bit more generous when resuming
-   fuzzing sessions or trying to calibrate already-added internal finds.
-   The first value is a percentage, the other is in milliseconds: */
-
-#define CAL_TMOUT_PERC      125
-#define CAL_TMOUT_ADD       50
-
-/* Number of chances to calibrate a case before giving up: */
-
-#define CAL_CHANCES         3
-
-/* Map size for the traced binary (2^MAP_SIZE_POW2). Must be greater than
-   2; you probably want to keep it under 18 or so for performance reasons
-   (adjusting AFL_INST_RATIO when compiling is probably a better way to solve
-   problems with complex programs). You need to recompile the target binary
-   after changing this - otherwise, SEGVs may ensue. */
-
-#define MAP_SIZE_POW2       16
-#define MAP_SIZE            (1 << MAP_SIZE_POW2)
-
-/* Maximum allocator request size (keep well under INT_MAX): */
-
-#define MAX_ALLOC           0x40000000
-
-/* A made-up hashing seed: */
-
-#define HASH_CONST          0xa5b35705
-
-/* Constants for afl-gotcpu to control busy loop timing: */
-
-#define  CTEST_TARGET_MS    5000
-#define  CTEST_CORE_TRG_MS  1000
-#define  CTEST_BUSY_CYCLES  (10 * 1000 * 1000)
-
-/* Uncomment this to use inferior block-coverage-based instrumentation. Note
-   that you need to recompile the target binary for this to have any effect: */
-
-// #define COVERAGE_ONLY
-
-/* Uncomment this to ignore hit counts and output just one bit per tuple.
-   As with the previous setting, you will need to recompile the target
-   binary: */
-
-// #define SKIP_COUNTS
-
-/* Uncomment this to use instrumentation data to record newly discovered paths,
-   but do not use them as seeds for fuzzing. This is useful for conveniently
-   measuring coverage that could be attained by a "dumb" fuzzing algorithm: */
-
-// #define IGNORE_FINDS
-
-#endif /* ! _HAVE_CONFIG_H */

config.h

@@ -0,0 +1 @@
+include/config.h

debug.h

@@ -1,251 +0,0 @@
-/*
-   american fuzzy lop - debug / error handling macros
-   --------------------------------------------------
-
-   Written and maintained by Michal Zalewski <lcamtuf@google.com>
-
-   Copyright 2013, 2014, 2015, 2016 Google Inc. All rights reserved.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at:
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
- */
-
-#ifndef _HAVE_DEBUG_H
-#define _HAVE_DEBUG_H
-
-#include <errno.h>
-
-#include "types.h"
-#include "config.h"
-
-/*******************
- * Terminal colors *
- *******************/
-
-#ifdef USE_COLOR
-
-#  define cBLK "\x1b[0;30m"
-#  define cRED "\x1b[0;31m"
-#  define cGRN "\x1b[0;32m"
-#  define cBRN "\x1b[0;33m"
-#  define cBLU "\x1b[0;34m"
-#  define cMGN "\x1b[0;35m"
-#  define cCYA "\x1b[0;36m"
-#  define cLGR "\x1b[0;37m"
-#  define cGRA "\x1b[1;90m"
-#  define cLRD "\x1b[1;91m"
-#  define cLGN "\x1b[1;92m"
-#  define cYEL "\x1b[1;93m"
-#  define cLBL "\x1b[1;94m"
-#  define cPIN "\x1b[1;95m"
-#  define cLCY "\x1b[1;96m"
-#  define cBRI "\x1b[1;97m"
-#  define cRST "\x1b[0m"
-
-#  define bgBLK "\x1b[40m"
-#  define bgRED "\x1b[41m"
-#  define bgGRN "\x1b[42m"
-#  define bgBRN "\x1b[43m"
-#  define bgBLU "\x1b[44m"
-#  define bgMGN "\x1b[45m"
-#  define bgCYA "\x1b[46m"
-#  define bgLGR "\x1b[47m"
-#  define bgGRA "\x1b[100m"
-#  define bgLRD "\x1b[101m"
-#  define bgLGN "\x1b[102m"
-#  define bgYEL "\x1b[103m"
-#  define bgLBL "\x1b[104m"
-#  define bgPIN "\x1b[105m"
-#  define bgLCY "\x1b[106m"
-#  define bgBRI "\x1b[107m"
-
-#else
-
-#  define cBLK ""
-#  define cRED ""
-#  define cGRN ""
-#  define cBRN ""
-#  define cBLU ""
-#  define cMGN ""
-#  define cCYA ""
-#  define cLGR ""
-#  define cGRA ""
-#  define cLRD ""
-#  define cLGN ""
-#  define cYEL ""
-#  define cLBL ""
-#  define cPIN ""
-#  define cLCY ""
-#  define cBRI ""
-#  define cRST ""
-
-#  define bgBLK ""
-#  define bgRED ""
-#  define bgGRN ""
-#  define bgBRN ""
-#  define bgBLU ""
-#  define bgMGN ""
-#  define bgCYA ""
-#  define bgLGR ""
-#  define bgGRA ""
-#  define bgLRD ""
-#  define bgLGN ""
-#  define bgYEL ""
-#  define bgLBL ""
-#  define bgPIN ""
-#  define bgLCY ""
-#  define bgBRI ""
-
-#endif /* ^USE_COLOR */
-
-/*************************
- * Box drawing sequences *
- *************************/
-
-#ifdef FANCY_BOXES
-
-#  define SET_G1   "\x1b)0"       /* Set G1 for box drawing    */
-#  define RESET_G1 "\x1b)B"       /* Reset G1 to ASCII         */
-#  define bSTART   "\x0e"         /* Enter G1 drawing mode     */
-#  define bSTOP    "\x0f"         /* Leave G1 drawing mode     */
-#  define bH       "q"            /* Horizontal line           */
-#  define bV       "x"            /* Vertical line             */
-#  define bLT      "l"            /* Left top corner           */
-#  define bRT      "k"            /* Right top corner          */
-#  define bLB      "m"            /* Left bottom corner        */
-#  define bRB      "j"            /* Right bottom corner       */
-#  define bX       "n"            /* Cross                     */
-#  define bVR      "t"            /* Vertical, branch right    */
-#  define bVL      "u"            /* Vertical, branch left     */
-#  define bHT      "v"            /* Horizontal, branch top    */
-#  define bHB      "w"            /* Horizontal, branch bottom */
-
-#else
-
-#  define SET_G1   ""
-#  define RESET_G1 ""
-#  define bSTART   ""
-#  define bSTOP    ""
-#  define bH       "-"
-#  define bV       "|"
-#  define bLT      "+"
-#  define bRT      "+"
-#  define bLB      "+"
-#  define bRB      "+"
-#  define bX       "+"
-#  define bVR      "+"
-#  define bVL      "+"
-#  define bHT      "+"
-#  define bHB      "+"
-
-#endif /* ^FANCY_BOXES */
-
-/***********************
- * Misc terminal codes *
- ***********************/
-
-#define TERM_HOME     "\x1b[H"
-#define TERM_CLEAR    TERM_HOME "\x1b[2J"
-#define cEOL          "\x1b[0K"
-#define CURSOR_HIDE   "\x1b[?25l"
-#define CURSOR_SHOW   "\x1b[?25h"
-
-/************************
- * Debug & error macros *
- ************************/
-
-/* Just print stuff to the appropriate stream. */
-
-#ifdef MESSAGES_TO_STDOUT
-#  define SAYF(x...)    printf(x)
-#else 
-#  define SAYF(x...)    fprintf(stderr, x)
-#endif /* ^MESSAGES_TO_STDOUT */
-
-/* Show a prefixed warning. */
-
-#define WARNF(x...) do { \
-    SAYF(cYEL "[!] " cBRI "WARNING: " cRST x); \
-    SAYF(cRST "\n"); \
-  } while (0)
-
-/* Show a prefixed "doing something" message. */
-
-#define ACTF(x...) do { \
-    SAYF(cLBL "[*] " cRST x); \
-    SAYF(cRST "\n"); \
-  } while (0)
-
-/* Show a prefixed "success" message. */
-
-#define OKF(x...) do { \
-    SAYF(cLGN "[+] " cRST x); \
-    SAYF(cRST "\n"); \
-  } while (0)
-
-/* Show a prefixed fatal error message (not used in afl). */
-
-#define BADF(x...) do { \
-    SAYF(cLRD "\n[-] " cRST x); \
-    SAYF(cRST "\n"); \
-  } while (0)
-
-/* Die with a verbose non-OS fatal error message. */
-
-#define FATAL(x...) do { \
-    SAYF(bSTOP RESET_G1 CURSOR_SHOW cRST cLRD "\n[-] PROGRAM ABORT : " \
-         cBRI x); \
-    SAYF(cLRD "\n         Location : " cRST "%s(), %s:%u\n\n", \
-         __FUNCTION__, __FILE__, __LINE__); \
-    exit(1); \
-  } while (0)
-
-/* Die by calling abort() to provide a core dump. */
-
-#define ABORT(x...) do { \
-    SAYF(bSTOP RESET_G1 CURSOR_SHOW cRST cLRD "\n[-] PROGRAM ABORT : " \
-         cBRI x); \
-    SAYF(cLRD "\n    Stop location : " cRST "%s(), %s:%u\n\n", \
-         __FUNCTION__, __FILE__, __LINE__); \
-    abort(); \
-  } while (0)
-
-/* Die while also including the output of perror(). */
-
-#define PFATAL(x...) do { \
-    fflush(stdout); \
-    SAYF(bSTOP RESET_G1 CURSOR_SHOW cRST cLRD "\n[-]  SYSTEM ERROR : " \
-         cBRI x); \
-    SAYF(cLRD "\n    Stop location : " cRST "%s(), %s:%u\n", \
-         __FUNCTION__, __FILE__, __LINE__); \
-    SAYF(cLRD "       OS message : " cRST "%s\n", strerror(errno)); \
-    exit(1); \
-  } while (0)
-
-/* Die with FAULT() or PFAULT() depending on the value of res (used to
-   interpret different failure modes for read(), write(), etc). */
-
-#define RPFATAL(res, x...) do { \
-    if (res < 0) PFATAL(x); else FATAL(x); \
-  } while (0)
-
-/* Error-checking versions of read() and write() that call RPFATAL() as
-   appropriate. */
-
-#define ck_write(fd, buf, len, fn) do { \
-    u32 _len = (len); \
-    s32 _res = write(fd, buf, _len); \
-    if (_res != _len) RPFATAL(_res, "Short write to %s", fn); \
-  } while (0)
-
-#define ck_read(fd, buf, len, fn) do { \
-    u32 _len = (len); \
-    s32 _res = read(fd, buf, _len); \
-    if (_res != _len) RPFATAL(_res, "Short read from %s", fn); \
-  } while (0)
-
-#endif /* ! _HAVE_DEBUG_H */

dictionaries/README.md

@@ -1,19 +1,17 @@
-================
-AFL dictionaries
-================
+# AFL dictionaries
 
-  (See ../docs/README for the general instruction manual.)
+(See [../docs/README.md](../docs/README.md) for the general instruction manual.)
 
 This subdirectory contains a set of dictionaries that can be used in
 conjunction with the -x option to allow the fuzzer to effortlessly explore the
 grammar of some of the more verbose data formats or languages. The basic
-principle behind the operation of fuzzer dictionaries is outlined in section 9
-of the "main" README for the project.
+principle behind the operation of fuzzer dictionaries is outlined in section 10
+of the "main" README.md for the project.
 
 Custom dictionaries can be added at will. They should consist of a
 reasonably-sized set of rudimentary syntax units that the fuzzer will then try
-to clobber together in various ways. Snippets between 2 and 16 bytes are usually
-the sweet spot.
+to clobber together in various ways. Snippets between 2 and 16 bytes are
+usually the sweet spot.
 
 Custom dictionaries can be created in two ways:
 
@@ -32,12 +30,12 @@ parameter is a file or a directory.
 
 In the file mode, every name field can be optionally followed by @<num>, e.g.:
 
-  keyword_foo@1 = "foo"
+  `keyword_foo@1 = "foo"`
 
 Such entries will be loaded only if the requested dictionary level is equal or
 higher than this number. The default level is zero; a higher value can be set
 by appending @<num> to the dictionary file name, like so:
 
-  -x path/to/dictionary.dct@2
+  `-x path/to/dictionary.dct@2`
 
 Good examples of dictionaries can be found in xml.dict and png.dict.

dictionaries/gif.dict

@@ -2,7 +2,7 @@
 # AFL dictionary for GIF images
 # -----------------------------
 #
-# Created by Michal Zalewski <lcamtuf@google.com>
+# Created by Michal Zalewski
 #
 
 header_87a="87a"

dictionaries/html_tags.dict

@@ -5,7 +5,7 @@
 # A basic collection of HTML tags likely to matter to HTML parsers. Does *not*
 # include any attributes or attribute values.
 #
-# Created by Michal Zalewski <lcamtuf@google.com>
+# Created by Michal Zalewski
 #
 
 tag_a="<a>"

dictionaries/jpeg.dict

@@ -2,7 +2,7 @@
 # AFL dictionary for JPEG images
 # ------------------------------
 #
-# Created by Michal Zalewski <lcamtuf@google.com>
+# Created by Michal Zalewski
 #
 
 header_jfif="JFIF\x00"

dictionaries/js.dict

@@ -4,7 +4,7 @@
 #
 # Contains basic reserved keywords and syntax building blocks.
 #
-# Created by Michal Zalewski <lcamtuf@google.com>
+# Created by Michal Zalewski
 #
 
 keyword_arguments="arguments"

dictionaries/png.dict

@@ -5,7 +5,7 @@
 # Just the basic, standard-originating sections; does not include vendor
 # extensions.
 #
-# Created by Michal Zalewski <lcamtuf@google.com>
+# Created by Michal Zalewski
 #
 
 header_png="\x89PNG\x0d\x0a\x1a\x0a"

dictionaries/regexp.dict

@@ -0,0 +1,256 @@
+#
+# AFL dictionary for regex
+# --------------------------
+#
+# Contains various regular expressions.
+#
+# Created by Yang Guo <yangguo@chromium.org>
+#
+# Contributed by Dhiraj Mishra <dhiraj@inputzero.io>
+#
+"?"
+"abc"
+"()"
+"[]"
+"abc|def"
+"abc|def|ghi"
+"^xxx$"
+"ab\\b\\d\\bcd"
+"\\w|\\d"
+"a*?"
+"abc+"
+"abc+?"
+"xyz?"
+"xyz??"
+"xyz{0,1}"
+"xyz{0,1}?"
+"xyz{93}"
+"xyz{1,32}"
+"xyz{1,32}?"
+"xyz{1,}"
+"xyz{1,}?"
+"a\\fb\\nc\\rd\\te\\vf"
+"a\\nb\\bc"
+"(?:foo)"
+"(?: foo )"
+"foo|(bar|baz)|quux"
+"foo(?=bar)baz"
+"foo(?!bar)baz"
+"foo(?<=bar)baz"
+"foo(?<!bar)baz"
+"()"
+"(?=)"
+"[]"
+"[x]"
+"[xyz]"
+"[a-zA-Z0-9]"
+"[-123]"
+"[^123]"
+"]"
+"}"
+"[a-b-c]"
+"[x\\dz]"
+"[\\d-z]"
+"[\\d-\\d]"
+"[z-\\d]"
+"\\cj\\cJ\\ci\\cI\\ck\\cK"
+"\\c!"
+"\\c_"
+"\\c~"
+"[\\c!]"
+"[\\c_]"
+"[\\c~]"
+"[\\ca]"
+"[\\cz]"
+"[\\cA]"
+"[\\cZ]"
+"[\\c1]"
+"\\[\\]\\{\\}\\(\\)\\%\\^\\#\\ "
+"[\\[\\]\\{\\}\\(\\)\\%\\^\\#\\ ]"
+"\\8"
+"\\9"
+"\\11"
+"\\11a"
+"\\011"
+"\\118"
+"\\111"
+"\\1111"
+"(x)(x)(x)\\1"
+"(x)(x)(x)\\2"
+"(x)(x)(x)\\3"
+"(x)(x)(x)\\4"
+"(x)(x)(x)\\1*"
+"(x)(x)(x)\\3*"
+"(x)(x)(x)\\4*"
+"(x)(x)(x)(x)(x)(x)(x)(x)(x)(x)\\10"
+"(x)(x)(x)(x)(x)(x)(x)(x)(x)(x)\\11"
+"(a)\\1"
+"(a\\1)"
+"(\\1a)"
+"(\\2)(\\1)"
+"(?=a){0,10}a"
+"(?=a){1,10}a"
+"(?=a){9,10}a"
+"(?!a)?a"
+"\\1(a)"
+"(?!(a))\\1"
+"(?!\\1(a\\1)\\1)\\1"
+"\\1\\2(a(?:\\1(b\\1\\2))\\2)\\1"
+"[\\0]"
+"[\\11]"
+"[\\11a]"
+"[\\011]"
+"[\\00011]"
+"[\\118]"
+"[\\111]"
+"[\\1111]"
+"\\x60"
+"\\x3z"
+"\\c"
+"\\u0034"
+"\\u003z"
+"foo[z]*"
+"\\u{12345}"
+"\\u{12345}\\u{23456}"
+"\\u{12345}{3}"
+"\\u{12345}*"
+"\\ud808\\udf45*"
+"[\\ud808\\udf45-\\ud809\\udccc]"
+"a"
+"a|b"
+"a\\n"
+"a$"
+"a\\b!"
+"a\\Bb"
+"a*?"
+"a?"
+"a??"
+"a{0,1}?"
+"a{1,2}?"
+"a+?"
+"(a)"
+"(a)\\1"
+"(\\1a)"
+"\\1(a)"
+"a\\s"
+"a\\S"
+"a\\D"
+"a\\w"
+"a\\W"
+"a."
+"a\\q"
+"a[a]"
+"a[^a]"
+"a[a-z]"
+"a(?:b)"
+"a(?=b)"
+"a(?!b)"
+"\\x60"
+"\\u0060"
+"\\cA"
+"\\q"
+"\\1112"
+"(a)\\1"
+"(?!a)?a\\1"
+"(?:(?=a))a\\1"
+"a{}"
+"a{,}"
+"a{"
+"a{z}"
+"a{12z}"
+"a{12,"
+"a{12,3b"
+"{}"
+"{,}"
+"{"
+"{z}"
+"{1z}"
+"{12,"
+"{12,3b"
+"a"
+"abc"
+"a[bc]d"
+"a|bc"
+"ab|c"
+"a||bc"
+"(?:ab)"
+"(?:ab|cde)"
+"(?:ab)|cde"
+"(ab)"
+"(ab|cde)"
+"(ab)\\1"
+"(ab|cde)\\1"
+"(?:ab)?"
+"(?:ab)+"
+"a?"
+"a+"
+"a??"
+"a*?"
+"a+?"
+"(?:a?)?"
+"(?:a+)?"
+"(?:a?)+"
+"(?:a*)+"
+"(?:a+)+"
+"(?:a?)*"
+"(?:a*)*"
+"(?:a+)*"
+"a{0}"
+"(?:a+){0,0}"
+"a*b"
+"a+b"
+"a*b|c"
+"a+b|c"
+"(?:a{5,1000000}){3,1000000}"
+"(?:ab){4,7}"
+"a\\bc"
+"a\\sc"
+"a\\Sc"
+"a(?=b)c"
+"a(?=bbb|bb)c"
+"a(?!bbb|bb)c"
+"\xe2\x81\xa3"
+"[\xe2\x81\xa3]"
+"\xed\xb0\x80"
+"\xed\xa0\x80"
+"(\xed\xb0\x80)\x01"
+"((\xed\xa0\x80))\x02"
+"\xf0\x9f\x92\xa9"
+"\x01"
+"\x0f"
+"[-\xf0\x9f\x92\xa9]+"
+"[\xf0\x9f\x92\xa9-\xf4\x8f\xbf\xbf]"
+"(?<=)"
+"(?<=a)"
+"(?<!)"
+"(?<!a)"
+"(?<a>)"
+"(?<a>.)"
+"(?<a>.)\\k<a>"
+"\\p{Script=Greek}"
+"\\P{sc=Greek}"
+"\\p{Script_Extensions=Greek}"
+"\\P{scx=Greek}"
+"\\p{General_Category=Decimal_Number}"
+"\\P{gc=Decimal_Number}"
+"\\p{gc=Nd}"
+"\\P{Decimal_Number}"
+"\\p{Nd}"
+"\\P{Any}"
+"\\p{Changes_When_NFKC_Casefolded}"
+"(?:a?)??"
+"a?)"xyz{93}"
+"{93}"
+"a{12za?)?"
+"[\x8f]"
+"[\xf0\x9f\x92\xa9-\xf4\x8f\xbf\x92\xa9-\xf4\x8f\xbf\xbf]"
+"[\x92\xa9-\xf4\x8f\xbf\xbf]"
+"\\1\\2(b\\1\\2))\\2)\\1"
+"\\1\\2(a(?:\\1\\2))\\2)\\1"
+"?:\\1"
+"\\1(b\\1\\2))\\2)\\1"
+"\\1\\2(a(?:\\1(b\\1\\2))\\2)\\1"
+"foo(?=bar)bar)baz"
+"fo(?o(?o(?o(?=bar)baz"
+"foo(?=bar)baz"
+"foo(?=bar)bar)az"

dictionaries/sql.dict

@@ -11,7 +11,7 @@
 # standpoint, because they are usually not allowed in non-privileged
 # contexts).
 #
-# Created by Michal Zalewski <lcamtuf@google.com>
+# Created by Michal Zalewski
 #
 
 function_abs=" abs(1)"

dictionaries/tiff.dict

@@ -5,7 +5,7 @@
 # Just the basic, standard-originating sections; does not include vendor
 # extensions.
 #
-# Created by Michal Zalewski <lcamtuf@google.com>
+# Created by Michal Zalewski
 #
 
 header_ii="II*\x00"

dictionaries/webp.dict

@@ -2,7 +2,7 @@
 # AFL dictionary for WebP images
 # ------------------------------
 #
-# Created by Michal Zalewski <lcamtuf@google.com>
+# Created by Michal Zalewski
 #
 
 header_RIFF="RIFF"

dictionaries/xml.dict

@@ -4,7 +4,7 @@
 #
 # Several basic syntax elements and attributes, modeled on libxml2.
 #
-# Created by Michal Zalewski <lcamtuf@google.com>
+# Created by Michal Zalewski
 #
 
 attr_encoding=" encoding=\"1\""

docs/INSTALL.md

@@ -1,28 +1,30 @@
-=========================
-Installation instructions
-=========================
+# Installation instructions
 
   This document provides basic installation instructions and discusses known
-  issues for a variety of platforms. See README for the general instruction
+  issues for a variety of platforms. See README.md for the general instruction
   manual.
 
-1) Linux on x86
+## 1) Linux on x86
 ---------------
 
 This platform is expected to work well. Compile the program with:
 
-$ make
+```bash
+make
+```
 
 You can start using the fuzzer without installation, but it is also possible to
 install it with:
 
-# make install
+```bash
+make install
+```
 
 There are no special dependencies to speak of; you will need GNU make and a
 working compiler (gcc or clang). Some of the optional scripts bundled with the
 program may depend on bash, gdb, and similar basic tools.
 
-If you are using clang, please review llvm_mode/README.llvm; the LLVM
+If you are using clang, please review llvm_mode/README.md; the LLVM
 integration mode can offer substantial performance gains compared to the
 traditional approach.
 
@@ -30,27 +32,30 @@ You may have to change several settings to get optimal results (most notably,
 disable crash reporting utilities and switch to a different CPU governor), but
 afl-fuzz will guide you through that if necessary.
 
-2) OpenBSD, FreeBSD, NetBSD on x86
-----------------------------------
+## OpenBSD, FreeBSD, NetBSD on x86
 
 Similarly to Linux, these platforms are expected to work well and are
 regularly tested. Compile everything with GNU make:
 
-$ gmake
+```bash
+gmake
+```
 
 Note that BSD make will *not* work; if you do not have gmake on your system,
 please install it first. As on Linux, you can use the fuzzer itself without
 installation, or install it with:
 
-# gmake install
+```
+gmake install
+```
 
 Keep in mind that if you are using csh as your shell, the syntax of some of the
-shell commands given in the README and other docs will be different.
+shell commands given in the README.md and other docs will be different.
 
-The llvm_mode requires a dynamically linked, fully-operational installation of
+The `llvm_mode` requires a dynamically linked, fully-operational installation of
 clang. At least on FreeBSD, the clang binaries are static and do not include
 some of the essential tools, so if you want to make it work, you may need to
-follow the instructions in llvm_mode/README.llvm.
+follow the instructions in llvm_mode/README.md.
 
 Beyond that, everything should work as advertised.
 
@@ -58,8 +63,7 @@ The QEMU mode is currently supported only on Linux. I think it's just a QEMU
 problem, I couldn't get a vanilla copy of user-mode emulation support working
 correctly on BSD at all.
 
-3) MacOS X on x86
------------------
+## 3. MacOS X on x86
 
 MacOS X should work, but there are some gotchas due to the idiosyncrasies of
 the platform. On top of this, I have limited release testing capabilities
@@ -69,8 +73,8 @@ To build AFL, install Xcode and follow the general instructions for Linux.
 
 The Xcode 'gcc' tool is just a wrapper for clang, so be sure to use afl-clang
 to compile any instrumented binaries; afl-gcc will fail unless you have GCC
-installed from another source (in which case, please specify AFL_CC and
-AFL_CXX to point to the "real" GCC binaries).
+installed from another source (in which case, please specify `AFL_CC` and
+`AFL_CXX` to point to the "real" GCC binaries).
 
 Only 64-bit compilation will work on the platform; porting the 32-bit
 instrumentation would require a fair amount of work due to the way OS X
@@ -80,47 +84,45 @@ The crash reporting daemon that comes by default with MacOS X will cause
 problems with fuzzing. You need to turn it off by following the instructions
 provided here: http://goo.gl/CCcd5u
 
-The fork() semantics on OS X are a bit unusual compared to other unix systems
+The `fork()` semantics on OS X are a bit unusual compared to other unix systems
 and definitely don't look POSIX-compliant. This means two things:
 
   - Fuzzing will be probably slower than on Linux. In fact, some folks report
     considerable performance gains by running the jobs inside a Linux VM on
     MacOS X.
-
   - Some non-portable, platform-specific code may be incompatible with the
-    AFL forkserver. If you run into any problems, set AFL_NO_FORKSRV=1 in the
+    AFL forkserver. If you run into any problems, set `AFL_NO_FORKSRV=1` in the
     environment before starting afl-fuzz.
 
 User emulation mode of QEMU does not appear to be supported on MacOS X, so
-black-box instrumentation mode (-Q) will not work.
+black-box instrumentation mode (`-Q`) will not work.
 
 The llvm_mode requires a fully-operational installation of clang. The one that
 comes with Xcode is missing some of the essential headers and helper tools.
-See llvm_mode/README.llvm for advice on how to build the compiler from scratch.
+See llvm_mode/README.md for advice on how to build the compiler from scratch.
 
-4) Linux or *BSD on non-x86 systems
------------------------------------
+## 4. Linux or *BSD on non-x86 systems
 
 Standard build will fail on non-x86 systems, but you should be able to
 leverage two other options:
 
-  - The LLVM mode (see llvm_mode/README.llvm), which does not rely on
+  - The LLVM mode (see llvm_mode/README.md), which does not rely on
     x86-specific assembly shims. It's fast and robust, but requires a
     complete installation of clang.
-
-  - The QEMU mode (see qemu_mode/README.qemu), which can be also used for
+  - The QEMU mode (see qemu_mode/README.md), which can be also used for
     fuzzing cross-platform binaries. It's slower and more fragile, but
     can be used even when you don't have the source for the tested app.
 
 If you're not sure what you need, you need the LLVM mode. To get it, try:
 
-$ AFL_NO_X86=1 gmake && gmake -C llvm_mode
+```bash
+AFL_NO_X86=1 gmake && gmake -C llvm_mode
+```
 
 ...and compile your target program with afl-clang-fast or afl-clang-fast++
 instead of the traditional afl-gcc or afl-clang wrappers.
 
-5) Solaris on x86
------------------
+## 5. Solaris on x86
 
 The fuzzer reportedly works on Solaris, but I have not tested this first-hand,
 and the user base is fairly small, so I don't have a lot of feedback.
@@ -128,36 +130,39 @@ and the user base is fairly small, so I don't have a lot of feedback.
 To get the ball rolling, you will need to use GNU make and GCC or clang. I'm
 being told that the stock version of GCC that comes with the platform does not
 work properly due to its reliance on a hardcoded location for 'as' (completely
-ignoring the -B parameter or $PATH).
+ignoring the `-B` parameter or `$PATH`).
 
 To fix this, you may want to build stock GCC from the source, like so:
 
-$ ./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \
+```sh
+./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \
   --with-gmp-include=/usr/include/gmp --with-mpfr-include=/usr/include/mpfr
-$ make
-$ sudo make install
+make
+sudo make install
+```
 
-Do *not* specify --with-as=/usr/gnu/bin/as - this will produce a GCC binary that
-ignores the -B flag and you will be back to square one.
+Do *not* specify `--with-as=/usr/gnu/bin/as` - this will produce a GCC binary that
+ignores the `-B` flag and you will be back to square one.
 
 Note that Solaris reportedly comes with crash reporting enabled, which causes
 problems with crashes being misinterpreted as hangs, similarly to the gotchas
 for Linux and MacOS X. AFL does not auto-detect crash reporting on this
 particular platform, but you may need to run the following command:
 
-$ coreadm -d global -d global-setid -d process -d proc-setid \
+```sh
+coreadm -d global -d global-setid -d process -d proc-setid \
   -d kzone -d log
+```
 
 User emulation mode of QEMU is not available on Solaris, so black-box
-instrumentation mode (-Q) will not work.
+instrumentation mode (`-Q`) will not work.
 
-6) Everything else
-------------------
+## 6. Everything else
 
 You're on your own. On POSIX-compliant systems, you may be able to compile and
 run the fuzzer; and the LLVM mode may offer a way to instrument non-x86 code.
 
-The fuzzer will not run on Windows. It will also not work under Cygwin. It
+The fuzzer will run on Windows in WSL only. It will not work under Cygwin on in the normal Windows world. It
 could be ported to the latter platform fairly easily, but it's a pretty bad
 idea, because Cygwin is extremely slow. It makes much more sense to use
 VirtualBox or so to run a hardware-accelerated Linux VM; it will run around
@@ -171,13 +176,15 @@ It's possible that all you need is this workaround:
   https://github.com/pelya/android-shmem
 
 Joshua J. Drake notes that the Android linker adds a shim that automatically
-intercepts SIGSEGV and related signals. To fix this issue and be able to see
+intercepts `SIGSEGV` and related signals. To fix this issue and be able to see
 crashes, you need to put this at the beginning of the fuzzed program:
 
+```sh
   signal(SIGILL, SIG_DFL);
   signal(SIGABRT, SIG_DFL);
   signal(SIGBUS, SIG_DFL);
   signal(SIGFPE, SIG_DFL);
   signal(SIGSEGV, SIG_DFL);
+```
 
-You may need to #include <signal.h> first.
+You may need to `#include <signal.h>` first.

docs/PATCHES.md

@@ -1,9 +1,11 @@
+# Applied Patches
+
 The following patches from https://github.com/vanhauser-thc/afl-patches
 have been installed or not installed:
 
 
-INSTALLED
-=========
+## INSTALLED
+```
 afl-llvm-fix.diff			by kcwu(at)csie(dot)org
 afl-sort-all_uniq-fix.diff		by legarrec(dot)vincent(at)gmail(dot)com
 laf-intel.diff				by heiko(dot)eissfeldt(at)hexco(dot)de
@@ -16,7 +18,10 @@ afl-qemu-ppc64.diff			by william(dot)barsse(at)airbus(dot)com
 afl-qemu-optimize-entrypoint.diff	by mh(at)mh-sec(dot)de
 afl-qemu-speed.diff			by abiondo on github
 afl-qemu-optimize-map.diff		by mh(at)mh-sec(dot)de
+```
 
++ llvm_mode ngram prev_loc coverage (github.com/adrianherrera/afl-ngram-pass)
++ Custom mutator (native library) (by kyakdan)
 + unicorn_mode (modernized and updated by domenukk)
 + instrim (https://github.com/csienslab/instrim) was integrated
 + MOpt (github.com/puppet-meteor/MOpt-AFL) was imported
@@ -27,10 +32,12 @@ afl-qemu-optimize-map.diff		by mh(at)mh-sec(dot)de
 + forkserver patch for afl-tmin (github.com/nccgroup/TriforceAFL)
 
 
-NOT INSTALLED
-=============
+## NOT INSTALLED
+
+```
 afl-fuzz-context_sensitive.diff	- changes too much of the behaviour
 afl-tmpfs.diff - same as afl-fuzz-tmpdir.diff but more complex
 afl-cmin-reduce-dataset.diff - unsure of the impact
 afl-llvm-fix2.diff - not needed with the other patches
+```
 

docs/QuickStartGuide.md

@@ -1,11 +1,9 @@
-=====================
-AFL quick start guide
-=====================
+# AFL quick start guide
 
-You should read docs/README.md - it's pretty short. If you really can't, here's
+You should read [README.md](README.md) - it's pretty short. If you really can't, here's
 how to hit the ground running:
 
-1) Compile AFL with 'make'. If build fails, see docs/INSTALL for tips.
+1) Compile AFL with 'make'. If build fails, see [INSTALL.md](INSTALL.md) for tips.
 
 2) Find or write a reasonably fast and simple program that takes data from
    a file or stdin, processes it in a test-worthy way, then exits cleanly.
@@ -17,7 +15,7 @@ how to hit the ground running:
 
    The program must crash properly when a fault is encountered. Watch out for
    custom SIGSEGV or SIGABRT handlers and background processes. For tips on
-   detecting non-crashing flaws, see section 11 in docs/README.md .
+   detecting non-crashing flaws, see section 11 in [README.md](README.md) .
 
 3) Compile the program / library to be fuzzed using afl-gcc. A common way to
    do this would be:
@@ -29,7 +27,7 @@ how to hit the ground running:
 
 4) Get a small but valid input file that makes sense to the program. When
    fuzzing verbose syntax (SQL, HTTP, etc), create a dictionary as described in
-   dictionaries/README.dictionaries, too.
+   dictionaries/README.md, too.
 
 5) If the program reads from stdin, run 'afl-fuzz' like so:
 
@@ -40,15 +38,17 @@ how to hit the ground running:
    command line; AFL will put an auto-generated file name in there for you.
 
 6) Investigate anything shown in red in the fuzzer UI by promptly consulting
-   docs/status_screen.txt.
+   [status_screen.md](status_screen.md).
 
 7) compile and use llvm_mode (afl-clang-fast/afl-clang-fast++) as it is way
    faster and has a few cool features
 
+8) There is a basic docker build with 'docker build -t aflplusplus .'
+
 That's it. Sit back, relax, and - time permitting - try to skim through the
 following files:
 
-  - docs/README.md            - A general introduction to AFL,
-  - docs/perf_tips.txt        - Simple tips on how to fuzz more quickly,
-  - docs/status_screen.txt    - An explanation of the tidbits shown in the UI,
-  - docs/parallel_fuzzing.txt - Advice on running AFL on multiple cores.
+  - README.md                 - A general introduction to AFL,
+  - docs/perf_tips.md         - Simple tips on how to fuzz more quickly,
+  - docs/status_screen.md     - An explanation of the tidbits shown in the UI,
+  - docs/parallel_fuzzing.md  - Advice on running AFL on multiple cores.

docs/README.MOpt.md

@@ -36,6 +36,9 @@ enter the pacemaker fuzzing mode.
 Setting 0 will enter the pacemaker fuzzing mode at first, which is
 recommended in a short time-scale evaluation. 
 
+Setting -1 will enable both pacemaker mode and normal aflmutation fuzzing in
+parallel.
+
 Other important parameters can be found in afl-fuzz.c, for instance, 
 
 'swarm_num': the number of the PSO swarms used in the fuzzing process.

docs/README.radamsa.md

@@ -0,0 +1,9 @@
+# libradamsa
+
+Pretranslated radamsa library. This code belongs to the radamsa author.
+
+> Original repository: https://gitlab.com/akihe/radamsa
+
+> Source commit: 7b2cc2d0
+
+> The code here is adapted for AFL++ with minor changes respect the original version

docs/binaryonly_fuzzing.md

@@ -0,0 +1,194 @@
+# Fuzzing binary-only programs with afl++
+
+  afl++, libfuzzer and others are great if you have the source code, and
+  it allows for very fast and coverage guided fuzzing.
+
+  However, if there is only the binary program and no source code available,
+  then standard `afl-fuzz -n` (dumb mode) is not effective.
+
+  The following is a description of how these binaries can be fuzzed with afl++
+
+## TL;DR:
+
+  qemu_mode in persistent mode is the fastest - if the stability is
+  high enough. Otherwise try retrowrite, afl-dyninst and if these
+  fail too then standard qemu_mode with AFL_ENTRYPOINT to where you need it.
+
+
+## QEMU
+
+  Qemu is the "native" solution to the program.
+  It is available in the ./qemu_mode/ directory and once compiled it can
+  be accessed by the afl-fuzz -Q command line option.
+  It is the easiest to use alternative and even works for cross-platform binaries.
+
+  The speed decrease is at about 50%.
+  However various options exist to increase the speed:
+   - using AFL_ENTRYPOINT to move the forkserver to a later basic block in
+     the binary (+5-10% speed)
+   - using persistent mode [qemu_mode/README.persistent.md](../qemu_mode/README.persistent.md)
+     this will result in 150-300% overall speed - so 3-8x the original
+     qemu_mode speed!
+   - using AFL_CODE_START/AFL_CODE_END to only instrument specific parts
+
+  Note that there is also honggfuzz: [https://github.com/google/honggfuzz](https://github.com/google/honggfuzz)
+  which now has a qemu_mode, but its performance is just 1.5% ...
+
+  As it is included in afl++ this needs no URL.
+
+
+## WINE+QEMU
+
+  Wine mode can run Win32 PE binaries with the QEMU instrumentation.
+  It needs Wine, python3 and the pefile python package installed.
+
+  As it is included in afl++ this needs no URL.
+
+
+## UNICORN
+
+  Unicorn is a fork of QEMU. The instrumentation is, therefore, very similar.
+  In contrast to QEMU, Unicorn does not offer a full system or even userland
+  emulation. Runtime environment and/or loaders have to be written from scratch,
+  if needed. On top, block chaining has been removed. This means the speed boost
+  introduced in  the patched QEMU Mode of afl++ cannot simply be ported over to
+  Unicorn. For further information, check out [unicorn_mode/README.md](../unicorn_mode/README.md).
+
+  As it is included in afl++ this needs no URL.
+
+
+## DYNINST
+
+  Dyninst is a binary instrumentation framework similar to Pintool and
+  Dynamorio (see far below). However whereas Pintool and Dynamorio work at
+  runtime, dyninst instruments the target at load time, and then let it run -
+  or save the  binary with the changes.
+  This is great for some things, e.g. fuzzing, and not so effective for others,
+  e.g. malware analysis.
+
+  So what we can do with dyninst is taking every basic block, and put afl's
+  instrumention code in there - and then save the binary.
+  Afterwards we can just fuzz the newly saved target binary with afl-fuzz.
+  Sounds great? It is. The issue though - it is a non-trivial problem to
+  insert instructions, which change addresses in the process space, so that
+  everything is still working afterwards. Hence more often than not binaries
+  crash when they are run.
+
+  The speed decrease is about 15-35%, depending on the optimization options
+  used with afl-dyninst.
+
+  So if Dyninst works, it is the best option available. Otherwise it just
+  doesn't work well.
+
+  [https://github.com/vanhauser-thc/afl-dyninst](https://github.com/vanhauser-thc/afl-dyninst)
+
+
+## RETROWRITE
+
+  If you have an x86/x86_64 binary that still has it's symbols, is compiled
+  with position independant code (PIC/PIE) and does not use most of the C++
+  features then the retrowrite solution might be for you.
+  It decompiles to ASM files which can then be instrumented with afl-gcc.
+
+  It is at about 80-85% performance.
+
+  [https://github.com/HexHive/retrowrite](https://github.com/HexHive/retrowrite)
+
+
+## MCSEMA
+
+  Theoretically you can also decompile to llvm IR with mcsema, and then
+  use llvm_mode to instrument the binary.
+  Good luck with that.
+
+  [https://github.com/lifting-bits/mcsema](https://github.com/lifting-bits/mcsema)
+
+
+## INTEL-PT
+
+  If you have a newer Intel CPU, you can make use of Intels processor trace.
+  The big issue with Intel's PT is the small buffer size and the complex
+  encoding of the debug information collected through PT.
+  This makes the decoding very CPU intensive and hence slow.
+  As a result, the overall speed decrease is about 70-90% (depending on
+  the implementation and other factors).
+
+  There are two afl intel-pt implementations:
+
+  1. [https://github.com/junxzm1990/afl-pt](https://github.com/junxzm1990/afl-pt)
+     => this needs Ubuntu 14.04.05 without any updates and the 4.4 kernel.
+
+  2. [https://github.com/hunter-ht-2018/ptfuzzer](https://github.com/hunter-ht-2018/ptfuzzer)
+     => this needs a 4.14 or 4.15 kernel. the "nopti" kernel boot option must
+        be used. This one is faster than the other.
+
+  Note that there is also honggfuzz: https://github.com/google/honggfuzz
+  But its IPT performance is just 6%!
+
+
+## CORESIGHT
+
+  Coresight is ARM's answer to Intel's PT.
+  There is no implementation so far which handle coresight and getting
+  it working on an ARM Linux is very difficult due to custom kernel building
+  on embedded systems is difficult. And finding one that has coresight in
+  the ARM chip is difficult too.
+  My guess is that it is slower than Qemu, but faster than Intel PT.
+
+  If anyone finds any coresight implementation for afl please ping me: vh@thc.org
+
+
+## FRIDA
+
+  Frida is a dynamic instrumentation engine like Pintool, Dyninst and Dynamorio.
+  What is special is that it is written Python, and scripted with Javascript.
+  It is mostly used to reverse binaries on mobile phones however can be used
+  everywhere.
+
+  There is a WIP fuzzer available at [https://github.com/andreafioraldi/frida-fuzzer](https://github.com/andreafioraldi/frida-fuzzer)
+
+  There is also an early implementation in an AFL++ test branch:
+  [https://github.com/AFLplusplus/AFLplusplus/tree/frida](https://github.com/AFLplusplus/AFLplusplus/tree/frida)
+
+
+## PIN & DYNAMORIO
+
+  Pintool and Dynamorio are dynamic instrumentation engines, and they can be
+  used for getting basic block information at runtime.
+  Pintool is only available for Intel x32/x64 on Linux, Mac OS and Windows
+  whereas Dynamorio is additionally available for ARM and AARCH64.
+  Dynamorio is also 10x faster than Pintool.
+
+  The big issue with Dynamorio (and therefore Pintool too) is speed.
+  Dynamorio has a speed decrease of 98-99%
+  Pintool has a speed decrease of 99.5%
+
+  Hence Dynamorio is the option to go for if everything fails, and Pintool
+  only if Dynamorio fails too.
+
+  Dynamorio solutions:
+  * [https://github.com/vanhauser-thc/afl-dynamorio](https://github.com/vanhauser-thc/afl-dynamorio)
+  * [https://github.com/mxmssh/drAFL](https://github.com/mxmssh/drAFL)
+  * [https://github.com/googleprojectzero/winafl/](https://github.com/googleprojectzero/winafl/) <= very good but windows only
+
+  Pintool solutions:
+  * [https://github.com/vanhauser-thc/afl-pin](https://github.com/vanhauser-thc/afl-pin)
+  * [https://github.com/mothran/aflpin](https://github.com/mothran/aflpin)
+  * [https://github.com/spinpx/afl_pin_mode](https://github.com/spinpx/afl_pin_mode) <= only old Pintool version supported
+
+
+## Non-AFL solutions
+
+  There are many binary-only fuzzing frameworks.
+  Some are great for CTFs but don't work with large binaries, others are very
+  slow but have good path discovery, some are very hard to set-up ...
+
+  * QSYM: [https://github.com/sslab-gatech/qsym](https://github.com/sslab-gatech/qsym)
+  * Manticore: [https://github.com/trailofbits/manticore](https://github.com/trailofbits/manticore)
+  * S2E: [https://github.com/S2E](https://github.com/S2E)
+  *  ... please send me any missing that are good
+
+
+## Closing words
+
+  That's it! News, corrections, updates? Send an email to vh@thc.org

docs/binaryonly_fuzzing.txt

@@ -1,140 +0,0 @@
-
-Fuzzing binary-only programs with afl++
-=======================================
-
-afl++, libfuzzer and others are great if you have the source code, and
-it allows for very fast and coverage guided fuzzing.
-
-However, if there is only the binary program and not source code available,
-then standard afl++ (dumb mode) is not effective.
-
-The following is a description of how these can be fuzzed with afl++
-
-!!!!!
-TL;DR: try DYNINST with afl-dyninst. If it produces too many crashes then
-      use afl -Q qemu_mode, or better: use both in parallel.
-!!!!!
-
-
-QEMU
-----
-Qemu is the "native" solution to the program.
-It is available in the ./qemu_mode/ directory and once compiled it can
-be accessed by the afl-fuzz -Q command line option.
-The speed decrease is at about 50%
-It is the easiest to use alternative and even works for cross-platform binaries.
-
-As it is included in afl++ this needs no URL.
-
-
-UNICORN
--------
-Unicorn is a fork of QEMU. The instrumentation is, therefore, very similar.
-In contrast to QEMU, Unicorn does not offer a full system or even userland emulation.
-Runtime environment and/or loaders have to be written from scratch, if needed.
-On top, block chaining has been removed. This means the speed boost introduced in 
-to the patched QEMU Mode of afl++ cannot simply be ported over to Unicorn.
-For further information, check out ./unicorn_mode.txt.
-
-
-DYNINST
--------
-Dyninst is a binary instrumentation framework similar to Pintool and Dynamorio
-(see far below). However whereas Pintool and Dynamorio work at runtime, dyninst
-instruments the target at load time, and then let it run.
-This is great for some things, e.g. fuzzing, and not so effective for others,
-e.g. malware analysis.
-
-So what we can do with dyninst is taking every basic block, and put afl's
-instrumention code in there - and then save the binary.
-Afterwards we can just fuzz the newly saved target binary with afl-fuzz.
-Sounds great? It is. The issue though - it is a non-trivial problem to
-insert instructions, which change addresses in the process space, so
-everything is still working afterwards. Hence more often than not binaries
-crash when they are run (because of instrumentation).
-
-The speed decrease is about 15-35%, depending on the optimization options
-used with afl-dyninst.
-
-So if dyninst works, it is the best option available. Otherwise it just doesn't
-work well.
-
-https://github.com/vanhauser-thc/afl-dyninst
-
-
-INTEL-PT
---------
-If you have a newer Intel CPU, you can make use of Intels processor trace.
-The big issue with Intel's PT is the small buffer size and the complex
-encoding of the debug information collected through PT.
-This makes the decoding very CPU intensive and hence slow.
-As a result, the overall speed decrease is about 70-90% (depending on
-the implementation and other factors).
-
-There are two afl intel-pt implementations:
-
-1. https://github.com/junxzm1990/afl-pt
- => this needs Ubuntu 14.04.05 without any updates and the 4.4 kernel.
-
-2. https://github.com/hunter-ht-2018/ptfuzzer
- => this needs a 4.14 or 4.15 kernel. the "nopti" kernel boot option must
-    be used. This one is faster than the other.
-
-
-CORESIGHT
----------
-
-Coresight is ARM's answer to Intel's PT.
-There is no implementation so far which handle coresight and getting
-it working on an ARM Linux is very difficult due to custom kernel building
-on embedded systems is difficult. And finding one that has coresight in
-the ARM chip is difficult too.
-My guess is that it is slower than Qemu, but faster than Intel PT.
-If anyone finds any coresight implementation for afl please ping me:
-vh@thc.org
-
-
-PIN & DYNAMORIO
----------------
-
-Pintool and Dynamorio are dynamic instrumentation engines, and they can be
-used for getting basic block information at runtime.
-Pintool is only available for Intel x32/x64 on Linux, Mac OS and Windows
-whereas Dynamorio is additionally available for ARM and AARCH64.
-Dynamorio is also 10x faster than Pintool.
-
-The big issue with Dynamorio (and therefore Pintool too) is speed.
-Dynamorio has a speed decrease of 98-99%
-Pintool has a speed decrease of 99.5%
-
-Hence Dynamorio is the option to go for if everything fails, and Pintool
-only if Dynamorio fails too.
-
-Dynamorio solutions:
-  https://github.com/vanhauser-thc/afl-dynamorio
-  https://github.com/mxmssh/drAFL
-  https://github.com/googleprojectzero/winafl/ <= very good but windows only
-
-Pintool solutions:
-  https://github.com/vanhauser-thc/afl-pin
-  https://github.com/mothran/aflpin
-  https://github.com/spinpx/afl_pin_mode  <= only old Pintool version supported
-
-
-Non-AFL solutions
------------------
-
-There are many binary-only fuzzing frameworks. Some are great for CTFs but don't
-work with large binaries, others are very slow but have good path discovery,
-some are very hard to set-up ...
-
-QSYM: https://github.com/sslab-gatech/qsym
-Manticore: https://github.com/trailofbits/manticore
-S2E: https://github.com/S2E
-<please send me any missing that are good>
-
-
-
-That's it!
-News, corrections, updates?
-Email vh@thc.org

docs/custom_mutators.md

@@ -0,0 +1,255 @@
+# Custom Mutators in AFL++
+
+This file describes how you can implement custom mutations to be used in AFL.
+For now, we support C/C++ library and Python module, collectivelly named as the
+custom mutator.
+
+Implemented by
+- C/C++ library (`*.so`): Khaled Yakdan from Code Intelligence (<yakdan@code-intelligence.de>)
+- Python module: Christian Holler from Mozilla (<choller@mozilla.com>)
+
+## 1) Introduction
+
+Custom mutators can be passed to `afl-fuzz` to perform custom mutations on test
+cases beyond those available in AFL. For example, to enable structure-aware
+fuzzing by using libraries that perform mutations according to a given grammar.
+
+The custom mutator is passed to `afl-fuzz` via the `AFL_CUSTOM_MUTATOR_LIBRARY`
+or `AFL_PYTHON_MODULE` environment variable, and must export a fuzz function.
+Now afl also supports multiple custom mutators which can be specified in the same `AFL_CUSTOM_MUTATOR_LIBRARY` environment variable like this.
+```bash
+export AFL_CUSTOM_MUTATOR_LIBRARY="full/path/to/mutator_first.so;full/path/to/mutator_second.so"
+```
+Please see [APIs](#2-apis) and [Usage](#3-usage) for detail.
+
+The custom mutation stage is set to be the first non-deterministic stage (right before the havoc stage).
+
+Note: If `AFL_CUSTOM_MUTATOR_ONLY` is set, all mutations will solely be
+performed with the custom mutator.
+
+## 2) APIs
+
+C/C++:
+```c
+void *afl_custom_init(afl_t *afl, unsigned int seed);
+size_t afl_custom_fuzz(void *data, uint8_t *buf, size_t buf_size, u8 **out_buf, uint8_t *add_buf, size_t add_buf_size, size_t max_size);
+size_t afl_custom_post_process(void *data, uint8_t *buf, size_t buf_size, uint8_t **out_buf);
+int32_t afl_custom_init_trim(void *data, uint8_t *buf, size_t buf_size);
+size_t afl_custom_trim(void *data, uint8_t **out_buf);
+int32_t afl_custom_post_trim(void *data, int success) {
+size_t afl_custom_havoc_mutation(void *data, u8 *buf, size_t buf_size, u8 **out_buf, size_t max_size);
+uint8_t afl_custom_havoc_mutation_probability(void *data);
+uint8_t afl_custom_queue_get(void *data, const uint8_t *filename);
+void afl_custom_queue_new_entry(void *data, const uint8_t *filename_new_queue, const uint8_t *filename_orig_queue);
+void afl_custom_deinit(void *data);
+```
+
+Python:
+```python
+def init(seed):
+    pass
+
+def fuzz(buf, add_buf, max_size):
+    return mutated_out
+
+def post_process(buf):
+    return out_buf
+
+def init_trim(buf):
+    return cnt
+
+def trim():
+    return out_buf
+
+def post_trim(success):
+    return next_index
+
+def havoc_mutation(buf, max_size):
+    return mutated_out
+
+def havoc_mutation_probability():
+    return probability # int in [0, 100]
+
+def queue_get(filename):
+    return True
+
+def queue_new_entry(filename_new_queue, filename_orig_queue):
+    pass
+```
+
+### Custom Mutation
+
+- `init`:
+
+    This method is called when AFL++ starts up and is used to seed RNG and set up buffers and state.
+
+- `queue_get` (optional):
+
+    This method determines whether the custom fuzzer should fuzz the current
+    queue entry or not
+
+- `fuzz` (optional):
+
+    This method performs custom mutations on a given input. It also accepts an
+    additional test case.
+    Note that this function is optional - but it makes sense to use it.
+    You would only skip this if `post_process` is used to fix checksums etc.
+    so you are using it e.g. as a post processing library.
+
+- `havoc_mutation` and `havoc_mutation_probability` (optional):
+
+    `havoc_mutation` performs a single custom mutation on a given input. This
+    mutation is stacked with the other mutations in havoc. The other method,
+    `havoc_mutation_probability`, returns the probability that `havoc_mutation`
+    is called in havoc. By default, it is 6%.
+
+- `post_process` (optional):
+
+    For some cases, the format of the mutated data returned from the custom
+    mutator is not suitable to directly execute the target with this input.
+    For example, when using libprotobuf-mutator, the data returned is in a
+    protobuf format which corresponds to a given grammar. In order to execute
+    the target, the protobuf data must be converted to the plain-text format
+    expected by the target. In such scenarios, the user can define the
+    `post_process` function. This function is then transforming the data into the
+    format expected by the API before executing the target.
+
+- `queue_new_entry` (optional):
+
+    This methods is called after adding a new test case to the queue.
+
+- `deinit`:
+
+    The last method to be called, deinitializing the state.
+
+Note that there are also three functions for trimming as described in the
+next section.
+
+### Trimming Support
+
+The generic trimming routines implemented in AFL++ can easily destroy the
+structure of complex formats, possibly leading to a point where you have a lot
+of test cases in the queue that your Python module cannot process anymore but
+your target application still accepts. This is especially the case when your
+target can process a part of the input (causing coverage) and then errors out
+on the remaining input.
+
+In such cases, it makes sense to implement a custom trimming routine. The API
+consists of multiple methods because after each trimming step, we have to go
+back into the C code to check if the coverage bitmap is still the same for the
+trimmed input. Here's a quick API description:
+
+- `init_trim` (optional):
+
+    This method is called at the start of each trimming operation and receives
+    the initial buffer. It should return the amount of iteration steps possible
+    on this input (e.g. if your input has n elements and you want to remove them
+    one by one, return n, if you do a binary search, return log(n), and so on).
+
+    If your trimming algorithm doesn't allow you to determine the amount of
+    (remaining) steps easily (esp. while running), then you can alternatively
+    return 1 here and always return 0 in `post_trim` until you are finished and
+    no steps remain. In that case, returning 1 in `post_trim` will end the
+    trimming routine. The whole current index/max iterations stuff is only used
+    to show progress.
+
+- `trim` (optional)
+
+    This method is called for each trimming operation. It doesn't have any
+    arguments because we already have the initial buffer from `init_trim` and we
+    can memorize the current state in the data variables. This can also save
+    reparsing steps for each iteration. It should return the trimmed input
+    buffer, where the returned data must not exceed the initial input data in
+    length. Returning anything that is larger than the original data (passed to
+    `init_trim`) will result in a fatal abort of AFL++.
+
+- `post_trim` (optional)
+
+    This method is called after each trim operation to inform you if your
+    trimming step was successful or not (in terms of coverage). If you receive
+    a failure here, you should reset your input to the last known good state.
+    In any case, this method must return the next trim iteration index (from 0
+    to the maximum amount of steps you returned in `init_trim`).
+
+Omitting any of three trimming methods will cause the trimming to be disabled
+and trigger a fallback to the builtin default trimming routine.
+
+### Environment Variables
+
+Optionally, the following environment variables are supported:
+
+- `AFL_CUSTOM_MUTATOR_ONLY`
+
+    Disable all other mutation stages. This can prevent broken testcases
+    (those that your Python module can't work with anymore) to fill up your
+    queue. Best combined with a custom trimming routine (see below) because
+    trimming can cause the same test breakage like havoc and splice.
+
+
+- `AFL_PYTHON_ONLY`
+
+    Deprecated and removed, use `AFL_CUSTOM_MUTATOR_ONLY` instead
+    trimming can cause the same test breakage like havoc and splice.
+
+- `AFL_DEBUG`
+
+    When combined with `AFL_NO_UI`, this causes the C trimming code to emit additional messages about the performance and actions of your custom trimmer. Use this to see if it works :)
+
+## 3) Usage
+
+### Prerequisite
+
+For Python mutator, the python 3 or 2 development package is required. On
+Debian/Ubuntu/Kali this can be done:
+
+```bash
+sudo apt install python3-dev
+# or
+sudo apt install python-dev
+```
+
+Then, AFL++ can be compiled with Python support. The AFL++ Makefile detects
+Python 2 and 3 through `python-config` if it is in the PATH and compiles
+`afl-fuzz` with the feature if available.
+
+Note: for some distributions, you might also need the package `python[23]-apt`.
+In case your setup is different, set the necessary variables like this:
+`PYTHON_INCLUDE=/path/to/python/include LDFLAGS=-L/path/to/python/lib make`.
+
+### Custom Mutator Preparation
+
+For C/C++ mutator, the source code must be compiled as a shared object:
+```bash
+gcc -shared -Wall -O3 example.c -o example.so
+```
+Note that if you specify multiple custom mutators, the corresponding functions will
+be called in the order in which they are specified. e.g first `post_process` function of
+`example_first.so` will be called and then that of `example_second.so`
+
+### Run
+
+C/C++
+```bash
+export AFL_CUSTOM_MUTATOR_LIBRARY="/full/path/to/example_first.so;/full/path/to/example_second.so"
+afl-fuzz /path/to/program
+```
+
+Python
+```bash
+export PYTHONPATH=`dirname /full/path/to/example.py`
+export AFL_PYTHON_MODULE=example
+afl-fuzz /path/to/program
+```
+
+## 4) Example
+
+Please see [example.c](../examples/custom_mutators/example.c) and
+[example.py](../examples/custom_mutators/example.py)
+
+## 5) Other Resources
+
+- AFL libprotobuf mutator
+    - [bruce30262/libprotobuf-mutator_fuzzing_learning](https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator)
+    - [thebabush/afl-libprotobuf-mutator](https://github.com/thebabush/afl-libprotobuf-mutator)
+- [XML Fuzzing@NullCon 2017](https://www.agarri.fr/docs/XML_Fuzzing-NullCon2017-PUBLIC.pdf)
+    - [A bug detected by AFL + XML-aware mutators](https://bugs.chromium.org/p/chromium/issues/detail?id=930663)

docs/env_variables.md

@@ -1,18 +1,20 @@
-=======================
-Environmental variables
-=======================
+# Environmental variables
 
-  This document discusses the environment variables used by American Fuzzy Lop
+  This document discusses the environment variables used by American Fuzzy Lop++
   to expose various exotic functions that may be (rarely) useful for power
-  users or for some types of custom fuzzing setups. See README for the general
+  users or for some types of custom fuzzing setups. See README.md for the general
   instruction manual.
 
-1) Settings for afl-gcc, afl-clang, and afl-as - and gcc_plugin afl-gcc-fast
-----------------------------------------------------------------------------
+## 1) Settings for afl-gcc, afl-clang, and afl-as - and gcc_plugin afl-gcc-fast
 
 Because they can't directly accept command-line options, the compile-time
 tools make fairly broad use of environmental variables:
 
+  - Most afl tools do not print any ouput if stout/stderr are redirected.
+    If you want to have the output into a file then set the AFL_DEBUG
+    environment variable.
+    This is sadly necessary for various build processes which fail otherwise.
+
   - Setting AFL_HARDEN automatically adds code hardening options when invoking
     the downstream compiler. This currently includes -D_FORTIFY_SOURCE=2 and
     -fstack-protector-all. The setting is useful for catching non-crashing
@@ -25,19 +27,20 @@ tools make fairly broad use of environmental variables:
 
   - Setting AFL_USE_ASAN automatically enables ASAN, provided that your
     compiler supports that. Note that fuzzing with ASAN is mildly challenging
-    - see notes_for_asan.txt.
+    - see [notes_for_asan.md](notes_for_asan.md).
 
     (You can also enable MSAN via AFL_USE_MSAN; ASAN and MSAN come with the
-    same gotchas; the modes are mutually exclusive. UBSAN and other exotic
-    sanitizers are not officially supported yet, but are easy to get to work
-    by hand.)
+    same gotchas; the modes are mutually exclusive. UBSAN can be enabled
+    similarly by setting the environment variable AFL_USE_UBSAN=1. Finally
+    there is the Control Flow Integrity sanitizer that can be activated by
+    AFL_USE_CFISAN=1)
 
   - Setting AFL_CC, AFL_CXX, and AFL_AS lets you use alternate downstream
     compilation tools, rather than the default 'clang', 'gcc', or 'as' binaries
     in your $PATH.
 
   - AFL_PATH can be used to point afl-gcc to an alternate location of afl-as.
-    One possible use of this is experimental/clang_asm_normalize/, which lets
+    One possible use of this is examples/clang_asm_normalize/, which lets
     you instrument hand-written assembly when compiling clang code by plugging
     a normalizer into the chain. (There is no equivalent feature for GCC.)
 
@@ -65,17 +68,24 @@ tools make fairly broad use of environmental variables:
     mkdir assembly_here
     TMPDIR=$PWD/assembly_here AFL_KEEP_ASSEMBLY=1 make clean all
 
+  - If you are a weird person that wants to compile and instrument asm
+    text files then use the AFL_AS_FORCE_INSTRUMENT variable:
+      AFL_AS_FORCE_INSTRUMENT=1 afl-gcc foo.s -o foo
+
   - Setting AFL_QUIET will prevent afl-cc and afl-as banners from being
     displayed during compilation, in case you find them distracting.
 
   - Setting AFL_CAL_FAST will speed up the initial calibration, if the
     application is very slow
 
-2) Settings for afl-clang-fast / afl-clang-fast++
--------------------------------------------------
+## 2) Settings for afl-clang-fast / afl-clang-fast++ / afl-gcc-fast / afl-g++-fast
 
-The native LLVM instrumentation helper accepts a subset of the settings
-discussed in section #1, with the exception of:
+The native instrumentation helpers (llvm_mode and gcc_plugin) accept a subset
+of the settings discussed in section #1, with the exception of:
+
+    - Setting AFL_LLVM_SKIPSINGLEBLOCK=1 will skip instrumenting
+      functions with a single basic block. This is useful for most C and
+      some C++ targets. This works for all instrumentation modes.
 
   - AFL_AS, since this toolchain does not directly invoke GNU as.
 
@@ -87,8 +97,95 @@ discussed in section #1, with the exception of:
 
 Then there are a few specific features that are only available in llvm_mode:
 
-  LAF-INTEL
-  =========
+### Select the instrumentation mode
+
+    - AFL_LLVM_INSTRUMENT - this configures the instrumentation mode. 
+      Available options:
+        CLASSIC - classic AFL (map[cur_loc ^ prev_loc >> 1]++) (default)
+        CFG - InsTrim instrumentation (see below)
+        LTO - LTO instrumentation (see below)
+        CTX - context sensitive instrumentation (see below)
+        NGRAM-x - deeper previous location coverage (from NGRAM-2 up to NGRAM-16)
+      In CLASSIC (default) and CFG/INSTRIM you can also specify CTX and/or
+      NGRAM, seperate the options with a comma "," then, e.g.:
+        AFL_LLVM_INSTRUMENT=CFG,CTX,NGRAM-4
+      Not that this is a good idea to use both CTX and NGRAM :)
+
+### LTO
+
+    This is a different kind way of instrumentation: first it compiles all
+    code in LTO (link time optimization) and then performs an edge inserting
+    instrumentation which is 100% collision free (collisions are a big issue
+    in afl and afl-like instrumentations). This is performed by using
+    afl-clang-lto/afl-clang-lto++ instead of afl-clang-fast, but is only
+    built if LLVM 11 or newer is used.
+
+   - AFL_LLVM_INSTRUMENT=CFG will use Control Flow Graph instrumentation.
+     (recommended)
+
+   - AFL_LLVM_LTO_AUTODICTIONARY will generate a dictionary in the target
+     binary based on string compare and memory compare functions.
+     afl-fuzz will automatically get these transmitted when starting to
+     fuzz.
+
+    None of the following options are necessary to be used and are rather for
+    manual use (which only ever the author of this LTO implementation will use).
+    These are used if several seperated instrumentation are performed which
+    are then later combined.
+
+   - AFL_LLVM_MAP_ADDR sets the fixed map address to a different address than
+     the default 0x10000. A value of 0 or empty sets the map address to be
+     dynamic (the original afl way, which is slower)
+   - AFL_LLVM_MAP_DYNAMIC sets the shared memory address to be dynamic
+   - AFL_LLVM_LTO_STARTID sets the starting location ID for the instrumentation.
+     This defaults to 1
+   - AFL_LLVM_LTO_DONTWRITEID prevents that the highest location ID written
+     into the instrumentation is set in a global variable
+
+    See llvm_mode/README.LTO.md for more information.
+
+### INSTRIM
+
+    This feature increases the speed by ~15% without any disadvantages to the
+    classic instrumentation.
+
+    Note that there is also an LTO version (if you have llvm 11 or higher) -
+    that is the best instrumentation we have. Use `afl-clang-lto` to activate.
+    The InsTrim LTO version additionally has all the options and features of
+    LTO (see above).
+
+    - Setting AFL_LLVM_INSTRIM or AFL_LLVM_INSTRUMENT=CFG to activates this mode
+
+    - Setting AFL_LLVM_INSTRIM_LOOPHEAD=1 expands on INSTRIM to optimize loops.
+      afl-fuzz will only be able to see the path the loop took, but not how
+      many times it was called (unless it is a complex loop).
+
+    See llvm_mode/README.instrim.md
+
+### NGRAM
+
+    - Setting AFL_LLVM_NGRAM_SIZE or AFL_LLVM_INSTRUMENT=NGRAM-{value}
+      activates ngram prev_loc coverage, good values are 2, 4 or 8
+      (any value between 2 and 16 is valid).
+      It is highly recommended to increase the MAP_SIZE_POW2 definition in
+      config.h to at least 18 and maybe up to 20 for this as otherwise too
+      many map collisions occur.
+
+    See llvm_mode/README.ctx.md
+
+### CTX
+
+    - Setting AFL_LLVM_CTX or AFL_LLVM_INSTRUMENT=CTX
+      activates context sensitive branch coverage - meaning that each edge
+      is additionally combined with its caller.
+      It is highly recommended to increase the MAP_SIZE_POW2 definition in
+      config.h to at least 18 and maybe up to 20 for this as otherwise too
+      many map collisions occur.
+
+    See llvm_mode/README.ngram.md
+
+### LAF-INTEL
+
     This great feature will split compares to series of single byte comparisons
     to allow afl-fuzz to find otherwise rather impossible paths. It is not
     restricted to Intel CPUs ;-)
@@ -97,34 +194,21 @@ Then there are a few specific features that are only available in llvm_mode:
 
     - Setting AFL_LLVM_LAF_TRANSFORM_COMPARES will split string compare functions
 
-    - Setting AFL_LLVM_LAF_SPLIT_COMPARES will split > 8 bit CMP instructions
+    - Setting AFL_LLVM_LAF_SPLIT_COMPARES will split all floating point and
+      64, 32 and 16 bit integer CMP instructions
 
-    See llvm_mode/README.laf-intel for more information. 
+    See llvm_mode/README.laf-intel.md for more information.
+
+### WHITELIST
 
-  WHITELIST
-  =========
     This feature allows selectively instrumentation of the source
 
     - Setting AFL_LLVM_WHITELIST with a filename will only instrument those
       files that match the names listed in this file.
 
-    See llvm_mode/README.whitelist for more information.
+    See llvm_mode/README.whitelist.md for more information.
 
-  INSTRIM
-  =======
-    This feature increases the speed by whopping 20% but at the cost of a
-    lower path discovery and therefore coverage.
-
-    - Setting AFL_LLVM_INSTRIM activates this mode
-
-    - Setting AFL_LLVM_INSTRIM_LOOPHEAD=1 expands on INSTRIM to optimize loops.
-      afl-fuzz will only be able to see the path the loop took, but not how
-      many times it was called (unless it is a complex loop).
-
-    See llvm_mode/README.instrim
-
-  NOT_ZERO
-  ========
+### NOT_ZERO
 
     - Setting AFL_LLVM_NOT_ZERO=1 during compilation will use counters
       that skip zero on overflow. This is the default for llvm >= 9,
@@ -132,10 +216,31 @@ Then there are a few specific features that are only available in llvm_mode:
       slowdown due a performance issue that is only fixed in llvm 9+.
       This feature increases path discovery by a little bit.
 
-    See llvm_mode/README.neverzero
+    - Setting AFL_LLVM_SKIP_NEVERZERO=1 will not implement the skip zero
+      test. If the target performs only few loops then this will give a
+      small performance boost.
 
-3) Settings for afl-fuzz
-------------------------
+    See llvm_mode/README.neverzero.md
+
+### CMPLOG
+
+    - Setting AFL_LLVM_CMPLOG=1 during compilation will tell afl-clang-fast to
+      produce a CmpLog binary. See llvm_mode/README.cmplog.md
+
+    See llvm_mode/README.neverzero.md
+
+Then there are a few specific features that are only available in the gcc_plugin:
+
+### WHITELIST
+
+    This feature allows selective instrumentation of the source
+
+    - Setting AFL_GCC_WHITELIST with a filename will only instrument those
+      files that match the names listed in this file (one filename per line).
+
+    See gcc_plugin/README.whitelist.md for more information.
+
+## 3) Settings for afl-fuzz
 
 The main fuzzer binary accepts several options that disable a couple of sanity
 checks or alter some of the more exotic semantics of the tool:
@@ -158,6 +263,11 @@ checks or alter some of the more exotic semantics of the tool:
     normally indicated by the cycle counter in the UI turning green. May be
     convenient for some types of automated jobs.
 
+  - AFL_MAP_SIZE sets the size of the shared map that afl-fuzz, afl-showmap,
+    afl-tmin and afl-analyze create to gather instrumentation data from
+    the target. This must be equal or larger than the size the target was
+    compiled with.
+
   - Setting AFL_NO_AFFINITY disables attempts to bind to a specific CPU core
     on Linux systems. This slows things down, but lets you run more instances
     of afl-fuzz than would be prudent (if you really want to).
@@ -171,12 +281,15 @@ checks or alter some of the more exotic semantics of the tool:
     deciding if a particular test case is a "hang". The default is 1 second
     or the value of the -t parameter, whichever is larger. Dialing the value
     down can be useful if you are very concerned about slow inputs, or if you
-    don't want AFL to spend too much time classifying that stuff and just 
+    don't want AFL to spend too much time classifying that stuff and just
     rapidly put all timeouts in that bin.
 
   - AFL_NO_ARITH causes AFL to skip most of the deterministic arithmetics.
     This can be useful to speed up the fuzzing of text-based file formats.
 
+  - AFL_NO_SNAPSHOT will advice afl-fuzz not to use the snapshot feature
+    if the snapshot lkm is loaded
+
   - AFL_SHUFFLE_QUEUE randomly reorders the input queue on startup. Requested
     by some users for unorthodox parallelized fuzzing setups, but not
     advisable otherwise.
@@ -197,14 +310,19 @@ checks or alter some of the more exotic semantics of the tool:
     else. This makes the "own finds" counter in the UI more accurate.
     Beyond counter aesthetics, not much else should change.
 
-  - Setting AFL_POST_LIBRARY allows you to configure a postprocessor for
-    mutated files - say, to fix up checksums. See experimental/post_library/
-    for more.
+  - Note that AFL_POST_LIBRARY is deprecated, use AFL_CUSTOM_MUTATOR_LIBRARY
+    instead (see below).
 
-  - For AFL_PYTHON_MODULE and AFL_PYTHON_ONLY - they require to be compiled
-    with -DUSE_PYTHON. Please see docs/python_mutators.txt
-    This feature allows to configure custom mutators which can be very helpful
-    in e.g. fuzzing XML or other highly flexible structured input.
+  - Setting AFL_CUSTOM_MUTATOR_LIBRARY to a shared library with
+    afl_custom_fuzz() creates additional mutations through this library.
+    If afl-fuzz is compiled with Python (which is autodetected during builing
+    afl-fuzz), setting AFL_PYTHON_MODULE to a Python module can also provide
+    additional mutations.
+    If AFL_CUSTOM_MUTATOR_ONLY is also set, all mutations will solely be
+    performed with the custom mutator.
+    This feature allows to configure custom mutators which can be very helpful,
+    e.g. fuzzing XML or other highly flexible structured input.
+    Please see [custom_mutators.md](custom_mutators.md).
 
   - AFL_FAST_CAL keeps the calibration stage about 2.5x faster (albeit less
     precise), which can help when starting a session against a slow target.
@@ -223,6 +341,9 @@ checks or alter some of the more exotic semantics of the tool:
     some basic stats. This behavior is also automatically triggered when the
     output from afl-fuzz is redirected to a file or to a pipe.
 
+  - Setting AFL_FORCE_UI will force painting the UI on the screen even if
+    no valid terminal was detected (for virtual consoles)
+
   - If you are Jakub, you may need AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES.
     Others need not apply.
 
@@ -233,8 +354,17 @@ checks or alter some of the more exotic semantics of the tool:
   - Setting AFL_DEBUG_CHILD_OUTPUT will not suppress the child output.
     Not pretty but good for debugging purposes.
 
-4) Settings for afl-qemu-trace
-------------------------------
+  - Setting AFL_NO_CPU_RED will not display very high cpu usages in red color.
+
+  - Setting AFL_AUTORESUME will resume a fuzz run (same as providing `-i -`)
+    for an existing out folder, even if a different `-i` was provided.
+    Without this setting, afl-fuzz will refuse execution for a long-fuzzed out dir.
+
+  - Outdated environment variables that are that not supported anymore:
+    AFL_DEFER_FORKSRV
+    AFL_PERSISTENT
+
+## 4) Settings for afl-qemu-trace
 
 The QEMU wrapper used to instrument binary-only code supports several settings:
 
@@ -244,10 +374,20 @@ The QEMU wrapper used to instrument binary-only code supports several settings:
 
   - Setting AFL_INST_LIBS causes the translator to also instrument the code
     inside any dynamically linked libraries (notably including glibc).
-  
+
+  - Setting AFL_COMPCOV_LEVEL enables the CompareCoverage tracing of all cmp
+    and sub in x86 and x86_64 and memory comparions functions (e.g. strcmp,
+    memcmp, ...) when libcompcov is preloaded using AFL_PRELOAD.
+    More info at qemu_mode/libcompcov/README.md.
+    There are two levels at the moment, AFL_COMPCOV_LEVEL=1 that instruments
+    only comparisons with immediate values / read-only memory and
+    AFL_COMPCOV_LEVEL=2 that instruments all the comparions. Level 2 is more
+    accurate but may need a larger shared memory.
+
   - Setting AFL_QEMU_COMPCOV enables the CompareCoverage tracing of all
-    cmp and sub in x86 and x86_64. Support for other architectures and
-    comparison functions (mem/strcmp et al.) is planned.
+    cmp and sub in x86 and x86_64.
+    This is an alias of AFL_COMPCOV_LEVEL=1 when AFL_COMPCOV_LEVEL is
+    not specified.
 
   - The underlying QEMU binary will recognize any standard "user space
     emulation" variables (e.g., QEMU_STACK_SIZE), but there should be no
@@ -255,14 +395,30 @@ The QEMU wrapper used to instrument binary-only code supports several settings:
 
   - AFL_DEBUG will print the found entrypoint for the binary to stderr.
     Use this if you are unsure if the entrypoint might be wrong - but
-    use it directly, e.g. afl-qemu-trace ./program 
+    use it directly, e.g. afl-qemu-trace ./program
 
-  - If you want to specify a specific entrypoint into the binary (this can
-    be very good for the performance!), use AFL_ENTRYPOINT for this.
+  - AFL_ENTRYPOINT allows you to specify a specific entrypoint into the
+    binary (this can be very good for the performance!).
     The entrypoint is specified as hex address, e.g. 0x4004110
+    Note that the address must be the address of a basic block.
 
-5) Settings for afl-cmin
-------------------------
+  - When the target is i386/x86_64 you can specify the address of the function
+    that has to be the body of the persistent loop using
+    AFL_QEMU_PERSISTENT_ADDR=`start addr`.
+
+  - Another modality to execute the persistent loop is to specify also the
+    AFL_QEMU_PERSISTENT_RET=`end addr` env variable.
+    With this variable assigned, instead of patching the return address, the
+    specified instruction is transformed to a jump towards `start addr`.
+
+  - AFL_QEMU_PERSISTENT_GPR=1 QEMU will save the original value of general
+    purpose registers and restore them in each persistent cycle.
+
+  - With AFL_QEMU_PERSISTENT_RETADDR_OFFSET you can specify the offset from the
+    stack pointer in which QEMU can find the return address when `start addr` is
+    hitted.
+
+## 5) Settings for afl-cmin
 
 The corpus minimization script offers very little customization:
 
@@ -277,8 +433,7 @@ The corpus minimization script offers very little customization:
     a modest security risk on multi-user systems with rogue users, but should
     be safe on dedicated fuzzing boxes.
 
-6) Settings for afl-tmin
-------------------------
+# #6) Settings for afl-tmin
 
 Virtually nothing to play with. Well, in QEMU mode (-Q), AFL_PATH will be
 searched for afl-qemu-trace. In addition to this, TMPDIR may be used if a
@@ -289,16 +444,14 @@ to match when minimizing crashes. This will make minimization less useful, but
 may prevent the tool from "jumping" from one crashing condition to another in
 very buggy software. You probably want to combine it with the -e flag.
 
-7) Settings for afl-analyze
----------------------------
+## 7) Settings for afl-analyze
 
 You can set AFL_ANALYZE_HEX to get file offsets printed as hexadecimal instead
 of decimal.
 
-8) Settings for libdislocator.so
---------------------------------
+## 8) Settings for libdislocator
 
-The library honors three environmental variables:
+The library honors these environmental variables:
 
   - AFL_LD_LIMIT_MB caps the size of the maximum heap usage permitted by the
     library, in megabytes. The default value is 1 GB. Once this is exceeded,
@@ -315,14 +468,15 @@ The library honors three environmental variables:
     of the common allocators check for that internally and return NULL, so
     it's a security risk only in more exotic setups.
 
-9) Settings for libtokencap.so
-------------------------------
+  - AFL_ALIGNED_ALLOC=1 will force the alignment of the allocation size to
+    max_align_t to be compliant with the C standard.
+
+## 9) Settings for libtokencap
 
 This library accepts AFL_TOKEN_FILE to indicate the location to which the
 discovered tokens should be written.
 
-10) Third-party variables set by afl-fuzz & other tools
--------------------------------------------------------
+## 10) Third-party variables set by afl-fuzz & other tools
 
 Several variables are not directly interpreted by afl-fuzz, but are set to
 optimal values if not already present in the environment:
@@ -336,6 +490,7 @@ optimal values if not already present in the environment:
 
     abort_on_error=1
     detect_leaks=0
+    malloc_context_size=0
     symbolize=0
     allocator_may_return_null=1
 
@@ -346,7 +501,7 @@ optimal values if not already present in the environment:
 
   - In the same vein, by default, MSAN_OPTIONS are set to:
 
-    exit_code=86 (required for legacy reasons)    
+    exit_code=86 (required for legacy reasons)
     abort_on_error=1
     symbolize=0
     msan_track_origins=0
@@ -355,3 +510,4 @@ optimal values if not already present in the environment:
     Be sure to include the first one when customizing anything, since some
     MSAN versions don't call abort() on error, and we need a way to detect
     faults.
+

docs/historical_notes.md

@@ -1,17 +1,14 @@
-================
-Historical notes
-================
+# Historical notes
 
   This doc talks about the rationale of some of the high-level design decisions
   for American Fuzzy Lop. It's adopted from a discussion with Rob Graham.
-  See README for the general instruction manual, and technical_details.txt for
+  See README.md for the general instruction manual, and technical_details.md for
   additional implementation-level insights.
 
-1) Influences
--------------
+## 1) Influences
 
-In short, afl-fuzz is inspired chiefly by the work done by Tavis Ormandy back
-in 2007. Tavis did some very persuasive experiments using gcov block coverage
+In short, `afl-fuzz` is inspired chiefly by the work done by Tavis Ormandy back
+in 2007. Tavis did some very persuasive experiments using `gcov` block coverage
 to select optimal test cases out of a large corpus of data, and then using
 them as a starting point for traditional fuzzing workflows.
 
@@ -22,7 +19,7 @@ In parallel to this, both Tavis and I were interested in evolutionary fuzzing.
 Tavis had his experiments, and I was working on a tool called bunny-the-fuzzer,
 released somewhere in 2007.
 
-Bunny used a generational algorithm not much different from afl-fuzz, but
+Bunny used a generational algorithm not much different from `afl-fuzz`, but
 also tried to reason about the relationship between various input bits and
 the internal state of the program, with hopes of deriving some additional value
 from that. The reasoning / correlation part was probably in part inspired by
@@ -43,7 +40,7 @@ coverage-driven fuzzer that relied on coverage as a fitness function.
 Jared's approach was by no means identical to what afl-fuzz does, but it was in
 the same ballpark. His fuzzer tried to explicitly solve for the maximum coverage
 with a single input file; in comparison, afl simply selects for cases that do
-something new (which yields better results - see technical_details.txt).
+something new (which yields better results - see [technical_details.md](technical_details.md)).
 
 A few years later, Gabriel Campana released fuzzgrind, a tool that relied purely
 on Valgrind and a constraint solver to maximize coverage without any brute-force
@@ -75,8 +72,7 @@ But I digress; ultimately, attribution is hard, and glorying the fundamental
 concepts behind AFL is probably a waste of time. The devil is very much in the
 often-overlooked details, which brings us to...
 
-2) Design goals for afl-fuzz
-----------------------------
+## 2. Design goals for afl-fuzz
 
 In short, I believe that the current implementation of afl-fuzz takes care of
 several itches that seemed impossible to scratch with other tools:
@@ -86,7 +82,7 @@ several itches that seemed impossible to scratch with other tools:
    likely to find a bug, but runs 100x slower, your users are getting a bad
    deal.
 
-   To avoid starting with a handicap, afl-fuzz is meant to let you fuzz most of
+   To avoid starting with a handicap, `afl-fuzz` is meant to let you fuzz most of
    the intended targets at roughly their native speed - so even if it doesn't
    add value, you do not lose much.
 
@@ -107,7 +103,7 @@ several itches that seemed impossible to scratch with other tools:
    them strictly worse than "dumb" tools, and such degradation can be difficult
    for less experienced users to notice and correct.
 
-   In contrast, afl-fuzz is designed to be rock solid, chiefly by keeping it
+   In contrast, `afl-fuzz` is designed to be rock solid, chiefly by keeping it
    simple. In fact, at its core, it's designed to be just a very good
    traditional fuzzer with a wide range of interesting, well-researched
    strategies to go by. The fancy parts just help it focus the effort in
@@ -137,11 +133,11 @@ several itches that seemed impossible to scratch with other tools:
    corpora of interesting test cases that can be fed into a manual testing
    process or a UI harness later on.
 
-As mentioned in technical_details.txt, AFL does all this not by systematically
+As mentioned in [technical_details.md](technical_details.md), AFL does all this not by systematically
 applying a single overarching CS concept, but by experimenting with a variety
 of small, complementary methods that were shown to reliably yields results
 better than chance. The use of instrumentation is a part of that toolkit, but is
 far from being the most important one.
 
-Ultimately, what matters is that afl-fuzz is designed to find cool bugs - and
+Ultimately, what matters is that `afl-fuzz` is designed to find cool bugs - and
 has a pretty robust track record of doing just that.

docs/ideas.md

@@ -0,0 +1,120 @@
+# Ideas for afl++
+
+In the following, we describe a variety of ideas that could be implemented
+for future AFL++ versions.
+
+For GSOC2020 interested students please see
+[https://github.com/AFLplusplus/AFLplusplus/issues/208](https://github.com/AFLplusplus/AFLplusplus/issues/208)
+
+## Flexible Grammar Mutator
+
+Currently, AFL++'s mutation does not have deeper knowledge about the fuzzed
+binary, apart from feedback, even though the developer may have insights
+about the target.
+
+A developer may choose to provide dictionaries and implement own mutations
+in python or C, but an easy mutator that behaves according to a given grammar,
+does not exist.
+
+State-of-the-art research on grammar fuzzing has some problems in their
+implementations like code quality, scalability, or ease of use and other
+common issues of the academic code.
+
+We aim to develop a pluggable grammar mutator for afl++ that combines
+various results.
+
+Mentor: andreafioraldi 
+
+## Expand on the MOpt mutator
+
+Work on the MOpt mutator that is already in AFL++.
+
+This is an excellent mutations scheduler based on Particle Swarm
+Optimization but the current implementation schedule only the mutations
+that were present on AFL.
+
+AFL++ added a lot of optional mutators like the Input-2-State one based
+on Redqueen, the Radamsa mutator, the Custom mutator (the user can define
+its own mutator) and the work is to generalize MOpt for all the current
+and future mutators.
+
+Mentor: vanhauser-thc or andreafioraldi
+
+## perf-fuzz Linux Kernel Module
+
+Either Port the patch to the upcoming Ubuntu LTS 20.04 default kernel
+and provide a qemu-kvm image or find a different userspace snapshot
+solution that has a good performance and is reliable, e.g. with docker.
+[perf-fuzz](https://gts3.org/assets/papers/2017/xu:os-fuzz.pdf)
+The perf-fuzz kernel can be found at [https://github.com/sslab-gatech/perf-fuzz](https://github.com/sslab-gatech/perf-fuzz)
+There also is/was a FreeBSD project at [https://github.com/veracode-research/freebsd-perf-fuzz](https://github.com/veracode-research/freebsd-perf-fuzz)
+
+This enables snapshot fuzzing on Linux with an incredible performance!
+
+Mentor: any
+Idea/Issue tracker: [https://github.com/AFLplusplus/AFLplusplus/issues/248](https://github.com/AFLplusplus/AFLplusplus/issues/248)
+
+## QEMU 4-based Instrumentation
+
+First tests to use QEMU 4 for binary-only AFL++ showed that caching behavior
+changed, which vastly decreases fuzzing speeds.
+
+This is the cause why, right now, we cannot switch to QEMU 4.2.
+
+Understanding the current instrumentation and fixing the current caching
+issues will be needed.
+
+Mentor: andreafioraldi
+
+## WASM Instrumentation
+
+Currently, AFL++ can be used for source code fuzzing and traditional binaries.
+With the rise of WASM as compile target, however, a novel way of
+instrumentation needs to be implemented for binaries compiled to Webassembly.
+This can either be done by inserting instrumentation directly into the
+WASM AST, or by patching feedback into a WASM VMs of choice, similar to
+the current Unicorn instrumentation.
+
+Mentor: any
+
+## Machine Learning
+
+Something with machine learning, better than [NEUZZ](https://github.com/dongdongshe/neuzz) :-)
+Either improve a single mutator thorugh learning of many different bugs
+(a bug class) or gather deep insights about a single target beforehand
+(CFG, DFG, VFG, ...?) and improve performance for a single target.
+
+Mentor: domenukk
+
+## Reengineer `afl-fuzz` as Thread Safe, Embeddable Library
+
+Right now, afl-fuzz is single threaded, cannot safely be embedded in tools,
+and not multi-threaded. It makes use of a large number of globals, must always
+be the parent process and exec child processes. 
+Instead, afl-fuzz could be refactored to contain no global state and globals.
+This allows for different use cases that could be implemented during this
+project.
+Note that in the mean time a lot has happened here already, but e.g. making
+it all work and implement multithreading in afl-fuzz ... there is still quite
+some work to do.
+
+Mentor: hexcoder- or vanhauser-thc
+
+## Collision-free Binary-Only Maps
+
+AFL++ supports collison-free maps using an LTO (link-time-optimization) pass.
+This should be possible to implement for QEMU and Unicorn instrumentations.
+As the forkserver parent caches just in time translated translation blocks,
+adding a simple counter between jumps should be doable.
+
+Note: this is already in development for qemu by Andrea, so for people who
+want to contribute it might make more sense to port his solution to unicorn.
+
+Mentor: andreafioraldi or domenukk
+Issue/idea tracker: [https://github.com/AFLplusplus/AFLplusplus/issues/237](https://github.com/AFLplusplus/AFLplusplus/issues/237)
+
+## Your idea!
+
+Finally, we are open to proposals!
+Create an issue at https://github.com/AFLplusplus/AFLplusplus/issues and let's discuss :-)
+

docs/life_pro_tips.md

@@ -0,0 +1,90 @@
+# AFL "Life Pro Tips"
+
+Bite-sized advice for those who understand the basics, but can't be bothered
+to read or memorize every other piece of documentation for AFL.
+
+## Get more bang for your buck by using fuzzing dictionaries.
+
+See [dictionaries/README.md](../dictionaries/README.md) to learn how.
+
+## You can get the most out of your hardware by parallelizing AFL jobs.
+
+See [parallel_fuzzing.md](parallel_fuzzing.md) for step-by-step tips.
+
+## Improve the odds of spotting memory corruption bugs with libdislocator.so!
+
+It's easy. Consult [libdislocator/README.md](../libdislocator/README.md) for usage tips.
+
+## Want to understand how your target parses a particular input file?
+
+Try the bundled `afl-analyze` tool; it's got colors and all!
+
+## You can visually monitor the progress of your fuzzing jobs.
+
+Run the bundled `afl-plot` utility to generate browser-friendly graphs.
+
+## Need to monitor AFL jobs programmatically? 
+Check out the `fuzzer_stats` file in the AFL output dir or try `afl-whatsup`.
+
+## Puzzled by something showing up in red or purple in the AFL UI?
+It could be important - consult docs/status_screen.md right away!
+
+## Know your target? Convert it to persistent mode for a huge performance gain!
+Consult section #5 in llvm_mode/README.md for tips.
+
+## Using clang? 
+Check out llvm_mode/ for a faster alternative to afl-gcc!
+
+## Did you know that AFL can fuzz closed-source or cross-platform binaries?
+Check out qemu_mode/README.md and unicorn_mode/README.md for more.
+
+## Did you know that afl-fuzz can minimize any test case for you?
+Try the bundled `afl-tmin` tool - and get small repro files fast!
+
+## Not sure if a crash is exploitable? AFL can help you figure it out. Specify
+`-C` to enable the peruvian were-rabbit mode.
+
+## Trouble dealing with a machine uprising? Relax, we've all been there.
+
+Find essential survival tips at http://lcamtuf.coredump.cx/prep/.
+
+## Want to automatically spot non-crashing memory handling bugs?
+
+Try running an AFL-generated corpus through ASAN, MSAN, or Valgrind.
+
+## Good selection of input files is critical to a successful fuzzing job.
+
+See docs/perf_tips.md for pro tips.
+
+## You can improve the odds of automatically spotting stack corruption issues.
+
+Specify `AFL_HARDEN=1` in the environment to enable hardening flags.
+
+## Bumping into problems with non-reproducible crashes? 
+It happens, but usually
+isn't hard to diagnose. See section #7 in README.md for tips.
+
+## Fuzzing is not just about memory corruption issues in the codebase. 
+Add some
+sanity-checking `assert()` / `abort()` statements to effortlessly catch logic bugs.
+
+## Hey kid... pssst... want to figure out how AFL really works?
+
+Check out docs/technical_details.md for all the gory details in one place!
+
+## There's a ton of third-party helper tools designed to work with AFL!
+
+Be sure to check out docs/sister_projects.md before writing your own.
+
+## Need to fuzz the command-line arguments of a particular program?
+
+You can find a simple solution in examples/argv_fuzzing.
+
+## Attacking a format that uses checksums? 
+
+Remove the checksum-checking code or
+use a postprocessor! See examples/post_library/ for more.
+
+## Dealing with a very slow target or hoping for instant results? 
+
+Specify `-d` when calling afl-fuzz!

docs/life_pro_tips.txt

@@ -1,128 +0,0 @@
-# ===================
-# AFL "Life Pro Tips"
-# ===================
-#
-# Bite-sized advice for those who understand the basics, but can't be bothered
-# to read or memorize every other piece of documentation for AFL.
-#
-
-%
-
-Get more bang for your buck by using fuzzing dictionaries.
-See dictionaries/README.dictionaries to learn how.
-
-%
-
-You can get the most out of your hardware by parallelizing AFL jobs.
-See docs/parallel_fuzzing.txt for step-by-step tips.
-
-%
-
-Improve the odds of spotting memory corruption bugs with libdislocator.so!
-It's easy. Consult libdislocator/README.dislocator for usage tips.
-
-%
-
-Want to understand how your target parses a particular input file?
-Try the bundled afl-analyze tool; it's got colors and all!
-
-%
-
-You can visually monitor the progress of your fuzzing jobs.
-Run the bundled afl-plot utility to generate browser-friendly graphs.
-
-%
-
-Need to monitor AFL jobs programmatically? Check out the fuzzer_stats file
-in the AFL output dir or try afl-whatsup.
-
-%
-
-Puzzled by something showing up in red or purple in the AFL UI?
-It could be important - consult docs/status_screen.txt right away!
-
-%
-
-Know your target? Convert it to persistent mode for a huge performance gain!
-Consult section #5 in llvm_mode/README.llvm for tips.
-
-%
-
-Using clang? Check out llvm_mode/ for a faster alternative to afl-gcc!
-
-%
-
-Did you know that AFL can fuzz closed-source or cross-platform binaries?
-Check out qemu_mode/README.qemu for more.
-
-%
-
-Did you know that afl-fuzz can minimize any test case for you?
-Try the bundled afl-tmin tool - and get small repro files fast!
-
-%
-
-Not sure if a crash is exploitable? AFL can help you figure it out. Specify
--C to enable the peruvian were-rabbit mode. See section #10 in README for more.
-
-%
-
-Trouble dealing with a machine uprising? Relax, we've all been there.
-Find essential survival tips at http://lcamtuf.coredump.cx/prep/.
-
-%
-
-AFL-generated corpora can be used to power other testing processes.
-See section #2 in README for inspiration - it tends to pay off!
-
-%
-
-Want to automatically spot non-crashing memory handling bugs?
-Try running an AFL-generated corpus through ASAN, MSAN, or Valgrind.
-
-%
-
-Good selection of input files is critical to a successful fuzzing job.
-See section #5 in README (or docs/perf_tips.txt) for pro tips.
-
-%
-
-You can improve the odds of automatically spotting stack corruption issues.
-Specify AFL_HARDEN=1 in the environment to enable hardening flags.
-
-%
-
-Bumping into problems with non-reproducible crashes? It happens, but usually
-isn't hard to diagnose. See section #7 in README for tips.
-
-%
-
-Fuzzing is not just about memory corruption issues in the codebase. Add some
-sanity-checking assert() / abort() statements to effortlessly catch logic bugs.
-
-%
-
-Hey kid... pssst... want to figure out how AFL really works?
-Check out docs/technical_details.txt for all the gory details in one place!
-
-%
-
-There's a ton of third-party helper tools designed to work with AFL!
-Be sure to check out docs/sister_projects.txt before writing your own.
-
-%
-
-Need to fuzz the command-line arguments of a particular program?
-You can find a simple solution in experimental/argv_fuzzing.
-
-%
-
-Attacking a format that uses checksums? Remove the checksum-checking code or
-use a postprocessor! See experimental/post_library/ for more.
-
-%
-
-Dealing with a very slow target or hoping for instant results? Specify -d
-when calling afl-fuzz!
-
-%

docs/notes_for_asan.md

@@ -1,12 +1,9 @@
-==================================
-Notes for using ASAN with afl-fuzz
-==================================
+# Notes for using ASAN with afl-fuzz
 
   This file discusses some of the caveats for fuzzing under ASAN, and suggests
-  a handful of alternatives. See README for the general instruction manual.
+  a handful of alternatives. See README.md for the general instruction manual.
 
-1) Short version
-----------------
+## 1) Short version
 
 ASAN on 64-bit systems requests a lot of memory in a way that can't be easily
 distinguished from a misbehaving program bent on crashing your system.
@@ -23,7 +20,7 @@ Because of this, fuzzing with ASAN is recommended only in four scenarios:
     - Precisely gauge memory needs using http://jwilk.net/software/recidivm .
 
     - Limit the memory available to process using cgroups on Linux (see
-      experimental/asan_cgroups).
+      examples/asan_cgroups).
 
 To compile with ASAN, set AFL_USE_ASAN=1 before calling 'make clean all'. The
 afl-gcc / afl-clang wrappers will pick that up and add the appropriate flags.
@@ -31,14 +28,17 @@ Note that ASAN is incompatible with -static, so be mindful of that.
 
 (You can also use AFL_USE_MSAN=1 to enable MSAN instead.)
 
+NOTE: if you run several slaves only one should run the target compiled with
+ASAN (and UBSAN, CFISAN), the others should run the target with no sanitizers
+compiled in.
+
 There is also the option of generating a corpus using a non-ASAN binary, and
 then feeding it to an ASAN-instrumented one to check for bugs. This is faster,
 and can give you somewhat comparable results. You can also try using
-libdislocator (see libdislocator/README.dislocator in the parent directory) as a
+libdislocator (see libdislocator/README.dislocator.md in the parent directory) as a
 lightweight and hassle-free (but less thorough) alternative.
 
-2) Long version
----------------
+## 2) Long version
 
 ASAN allocates a huge region of virtual address space for bookkeeping purposes.
 Most of this is never actually accessed, so the OS never has to allocate any
@@ -74,7 +74,7 @@ There are also cgroups, but they are Linux-specific, not universally available
 even on Linux systems, and they require root permissions to set up; I'm a bit
 hesitant to make afl-fuzz require root permissions just for that. That said,
 if you are on Linux and want to use cgroups, check out the contributed script
-that ships in experimental/asan_cgroups/.
+that ships in examples/asan_cgroups/.
 
 In settings where cgroups aren't available, we have no nice, portable way to
 avoid counting the ASAN allocation toward the limit. On 32-bit systems, or for
@@ -105,16 +105,19 @@ examine them with ASAN, Valgrind, or other heavy-duty tools in a more
 controlled setting; or compile the target program with -m32 (32-bit mode)
 if your system supports that.
 
-3) Interactions with the QEMU mode
-----------------------------------
+## 3) Interactions with the QEMU mode
 
 ASAN, MSAN, and other sanitizers appear to be incompatible with QEMU user
 emulation, so please do not try to use them with the -Q option; QEMU doesn't
 seem to appreciate the shadow VM trick used by these tools, and will likely
 just allocate all your physical memory, then crash.
 
-4) ASAN and OOM crashes
------------------------
+You can, however, use QASan to run binaries that are not instrumented with ASan
+under QEMU with the AFL++ instrumentation.
+
+https://github.com/andreafioraldi/qasan
+
+## 4) ASAN and OOM crashes
 
 By default, ASAN treats memory allocation failures as fatal errors, immediately
 causing the program to crash. Since this is a departure from normal POSIX
@@ -129,15 +132,19 @@ want to cc: yourself on this bug:
 
   https://bugs.llvm.org/show_bug.cgi?id=22026
 
-5) What about UBSAN?
---------------------
+## 5) What about UBSAN?
 
-Some folks expressed interest in fuzzing with UBSAN. This isn't officially
-supported, because many installations of UBSAN don't offer a consistent way
-to abort() on fault conditions or to terminate with a distinctive exit code.
+New versions of UndefinedBehaviorSanitizer offers the
+-fsanitize=undefined-trap-on-error compiler flag that tells UBSan to insert an
+istruction that will cause SIGILL (ud2 on x86) when an undefined behaviour
+is detected. This is the option that you want to use when combining AFL++
+and UBSan.
 
-That said, some versions of the library can be binary-patched to address this
-issue, while newer releases support explicit compile-time flags - see this
-mailing list thread for tips:
+AFL_USE_UBSAN=1 env var will add this compiler flag to afl-clang-fast,
+afl-gcc-fast and afl-gcc for you.
 
-  https://groups.google.com/forum/#!topic/afl-users/GyeSBJt4M38
+Old versions of UBSAN don't offer a consistent way
+to abort() on fault conditions or to terminate with a distinctive exit code
+but there are some versions of the library can be binary-patched to address this
+issue. You can also preload a shared library that substitute all the UBSan
+routines used to report errors with abort().

docs/parallel_fuzzing.md

@@ -1,12 +1,9 @@
-=========================
-Tips for parallel fuzzing
-=========================
+# Tips for parallel fuzzing
 
   This document talks about synchronizing afl-fuzz jobs on a single machine
-  or across a fleet of systems. See README for the general instruction manual.
+  or across a fleet of systems. See README.md for the general instruction manual.
 
-1) Introduction
----------------
+## 1) Introduction
 
 Every copy of afl-fuzz will take up one CPU core. This means that on an
 n-core system, you can almost always run around n concurrent fuzzing jobs with
@@ -28,13 +25,12 @@ cases on the fly.
 
 Note that afl++ has AFLfast's power schedules implemented.
 It is therefore a good idea to use different power schedules if you run
-several instances in parallel. See docs/power_schedules.txt
+several instances in parallel. See [power_schedules.md](power_schedules.md)
 
 Alternatively running other AFL spinoffs in parallel can be of value,
 e.g. Angora (https://github.com/AngoraFuzzer/Angora/)
 
-2) Single-system parallelization
---------------------------------
+## 2) Single-system parallelization
 
 If you wish to parallelize a single job across multiple cores on a local
 system, simply create a new, empty output directory ("sync dir") that will be
@@ -43,12 +39,16 @@ for every instance - say, "fuzzer01", "fuzzer02", etc.
 
 Run the first one ("master", -M) like this:
 
+```
 $ ./afl-fuzz -i testcase_dir -o sync_dir -M fuzzer01 [...other stuff...]
+```
 
 ...and then, start up secondary (-S) instances like this:
 
+```
 $ ./afl-fuzz -i testcase_dir -o sync_dir -S fuzzer02 [...other stuff...]
 $ ./afl-fuzz -i testcase_dir -o sync_dir -S fuzzer03 [...other stuff...]
+```
 
 Each fuzzer will keep its state in a separate subdirectory, like so:
 
@@ -68,9 +68,11 @@ Note that running multiple -M instances is wasteful, although there is an
 experimental support for parallelizing the deterministic checks. To leverage
 that, you need to create -M instances like so:
 
+```
 $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterA:1/3 [...]
 $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterB:2/3 [...]
 $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterC:3/3 [...]
+```
 
 ...where the first value after ':' is the sequential ID of a particular master
 instance (starting at 1), and the second value is the total number of fuzzers to
@@ -86,15 +88,16 @@ WARNING: Exercise caution when explicitly specifying the -f option. Each fuzzer
 must use a separate temporary file; otherwise, things will go south. One safe
 example may be:
 
+```
 $ ./afl-fuzz [...] -S fuzzer10 -f file10.txt ./fuzzed/binary @@
 $ ./afl-fuzz [...] -S fuzzer11 -f file11.txt ./fuzzed/binary @@
 $ ./afl-fuzz [...] -S fuzzer12 -f file12.txt ./fuzzed/binary @@
+```
 
 This is not a concern if you use @@ without -f and let afl-fuzz come up with the
 file name.
 
-3) Multi-system parallelization
--------------------------------
+## 3) Multi-system parallelization
 
 The basic operating principle for multi-system parallelization is similar to
 the mechanism explained in section 2. The key difference is that you need to
@@ -106,20 +109,24 @@ write a simple script that performs two actions:
     that includes host name in the fuzzer ID, so that you can do something
     like:
 
+    ```sh
     for s in {1..10}; do
       ssh user@host${s} "tar -czf - sync/host${s}_fuzzid*/[qf]*" >host${s}.tgz
     done
+    ```
 
   - Distributes and unpacks these files on all the remaining machines, e.g.:
 
+    ```sh
     for s in {1..10}; do
       for d in {1..10}; do
         test "$s" = "$d" && continue
         ssh user@host${d} 'tar -kxzf -' <host${s}.tgz
       done
     done
+    ```
 
-There is an example of such a script in experimental/distributed_fuzzing/;
+There is an example of such a script in examples/distributed_fuzzing/;
 you can also find a more featured, experimental tool developed by
 Martijn Bogaard at:
 
@@ -167,8 +174,7 @@ It is *not* advisable to skip the synchronization script and run the fuzzers
 directly on a network filesystem; unexpected latency and unkillable processes
 in I/O wait state can mess things up.
 
-4) Remote monitoring and data collection
-----------------------------------------
+## 4) Remote monitoring and data collection
 
 You can use screen, nohup, tmux, or something equivalent to run remote
 instances of afl-fuzz. If you redirect the program's output to a file, it will
@@ -192,8 +198,7 @@ Keep in mind that crashing inputs are *not* automatically propagated to the
 master instance, so you may still want to monitor for crashes fleet-wide
 from within your synchronization or health checking scripts (see afl-whatsup).
 
-5) Asymmetric setups
---------------------
+## 5) Asymmetric setups
 
 It is perhaps worth noting that all of the following is permitted:
 

docs/perf_tips.md

@@ -1,12 +1,9 @@
-=================================
-Tips for performance optimization
-=================================
+## Tips for performance optimization
 
   This file provides tips for troubleshooting slow or wasteful fuzzing jobs.
-  See README for the general instruction manual.
+  See README.md for the general instruction manual.
 
-1) Keep your test cases small
------------------------------
+## 1. Keep your test cases small
 
 This is probably the single most important step to take! Large test cases do
 not merely take more time and memory to be parsed by the tested binary, but
@@ -29,33 +26,33 @@ as high as 500x or so.
 
 In practice, this means that you shouldn't fuzz image parsers with your
 vacation photos. Generate a tiny 16x16 picture instead, and run it through
-jpegtran or pngcrunch for good measure. The same goes for most other types
+`jpegtran` or `pngcrunch` for good measure. The same goes for most other types
 of documents.
 
-There's plenty of small starting test cases in ../testcases/* - try them out
+There's plenty of small starting test cases in ../testcases/ - try them out
 or submit new ones!
 
-If you want to start with a larger, third-party corpus, run afl-cmin with an
+If you want to start with a larger, third-party corpus, run `afl-cmin` with an
 aggressive timeout on that data set first.
 
-2) Use a simpler target
------------------------
+## 2. Use a simpler target
 
 Consider using a simpler target binary in your fuzzing work. For example, for
-image formats, bundled utilities such as djpeg, readpng, or gifhisto are
-considerably (10-20x) faster than the convert tool from ImageMagick - all while
-exercising roughly the same library-level image parsing code.
+image formats, bundled utilities such as `djpeg`, `readpng`, or `gifhisto` are
+considerably (10-20x) faster than the convert tool from ImageMagick - all while exercising roughly the same library-level image parsing code.
 
 Even if you don't have a lightweight harness for a particular target, remember
 that you can always use another, related library to generate a corpus that will
 be then manually fed to a more resource-hungry program later on.
 
-3) Use LLVM instrumentation
----------------------------
+Also note that reading the fuzzing input via stdin is faster than reading from
+a file.
 
-When fuzzing slow targets, you can gain 2x performance improvement by using
-the LLVM-based instrumentation mode described in llvm_mode/README.llvm. Note
-that this mode requires the use of clang and will not work with GCC.
+## 3. Use LLVM instrumentation
+
+When fuzzing slow targets, you can gain 20-100% performance improvement by
+using the LLVM-based instrumentation mode described in [the llvm_mode README](../llvm_mode/README.md).
+Note that this mode requires the use of clang and will not work with GCC.
 
 The LLVM mode also offers a "persistent", in-process fuzzing mode that can
 work well for certain types of self-contained libraries, and for fast targets,
@@ -64,22 +61,26 @@ that can offer huge benefits for programs with high startup overhead. Both
 modes require you to edit the source code of the fuzzed program, but the
 changes often amount to just strategically placing a single line or two.
 
-If there are important data comparisons performed (e.g. strcmp(ptr, MAGIC_HDR)
-then using laf-intel (see llvm_mode/README.laf-intel) will help afl-fuzz a lot
+If there are important data comparisons performed (e.g. `strcmp(ptr, MAGIC_HDR)`)
+then using laf-intel (see llvm_mode/README.laf-intel.md) will help `afl-fuzz` a lot
 to get to the important parts in the code.
 
-If you are only intested in specific parts of the code being fuzzed, you can
+If you are only interested in specific parts of the code being fuzzed, you can
 whitelist the files that are actually relevant. This improves the speed and
-accuracy of afl. See llvm_mode/README.whitelist
+accuracy of afl. See llvm_mode/README.whitelist.md
 
-4) Profile and optimize the binary
-----------------------------------
+Also use the InsTrim mode on larger binaries, this improves performance and
+coverage a lot.
+
+## 4. Profile and optimize the binary
 
 Check for any parameters or settings that obviously improve performance. For
 example, the djpeg utility that comes with IJG jpeg and libjpeg-turbo can be
 called with:
 
+```bash
   -dct fast -nosmooth -onepass -dither none -scale 1/4
+```
 
 ...and that will speed things up. There is a corresponding drop in the quality
 of decoded images, but it's probably not something you care about.
@@ -92,129 +93,132 @@ With some laid-back parsers, enabling "strict" mode (i.e., bailing out after
 first error) may result in smaller files and improved run time without
 sacrificing coverage; for example, for sqlite, you may want to specify -bail.
 
-If the program is still too slow, you can use strace -tt or an equivalent
+If the program is still too slow, you can use `strace -tt` or an equivalent
 profiling tool to see if the targeted binary is doing anything silly.
-Sometimes, you can speed things up simply by specifying /dev/null as the
+Sometimes, you can speed things up simply by specifying `/dev/null` as the
 config file, or disabling some compile-time features that aren't really needed
-for the job (try ./configure --help). One of the notoriously resource-consuming
-things would be calling other utilities via exec*(), popen(), system(), or
+for the job (try `./configure --help`). One of the notoriously resource-consuming
+things would be calling other utilities via `exec*()`, `popen()`, `system()`, or
 equivalent calls; for example, tar can invoke external decompression tools
 when it decides that the input file is a compressed archive.
 
-Some programs may also intentionally call sleep(), usleep(), or nanosleep();
-vim is a good example of that. Other programs may attempt fsync() and so on.
+Some programs may also intentionally call `sleep()`, `usleep()`, or `nanosleep()`;
+vim is a good example of that. Other programs may attempt `fsync()` and so on.
 There are third-party libraries that make it easy to get rid of such code,
 e.g.:
 
   https://launchpad.net/libeatmydata
 
 In programs that are slow due to unavoidable initialization overhead, you may
-want to try the LLVM deferred forkserver mode (see llvm_mode/README.llvm),
+want to try the LLVM deferred forkserver mode (see llvm_mode/README.md),
 which can give you speed gains up to 10x, as mentioned above.
 
 Last but not least, if you are using ASAN and the performance is unacceptable,
 consider turning it off for now, and manually examining the generated corpus
 with an ASAN-enabled binary later on.
 
-5) Instrument just what you need
---------------------------------
+## 5. Instrument just what you need
 
 Instrument just the libraries you actually want to stress-test right now, one
 at a time. Let the program use system-wide, non-instrumented libraries for
 any functionality you don't actually want to fuzz. For example, in most
-cases, it doesn't make to instrument libgmp just because you're testing a
+cases, it doesn't make to instrument `libgmp` just because you're testing a
 crypto app that relies on it for bignum math.
 
 Beware of programs that come with oddball third-party libraries bundled with
-their source code (Spidermonkey is a good example of this). Check ./configure
+their source code (Spidermonkey is a good example of this). Check `./configure`
 options to use non-instrumented system-wide copies instead.
 
-6) Parallelize your fuzzers
----------------------------
+## 6. Parallelize your fuzzers
 
 The fuzzer is designed to need ~1 core per job. This means that on a, say,
 4-core system, you can easily run four parallel fuzzing jobs with relatively
-little performance hit. For tips on how to do that, see parallel_fuzzing.txt.
+little performance hit. For tips on how to do that, see parallel_fuzzing.md.
 
-The afl-gotcpu utility can help you understand if you still have idle CPU
+The `afl-gotcpu` utility can help you understand if you still have idle CPU
 capacity on your system. (It won't tell you about memory bandwidth, cache
 misses, or similar factors, but they are less likely to be a concern.)
 
-7) Keep memory use and timeouts in check
-----------------------------------------
+## 7. Keep memory use and timeouts in check
 
-If you have increased the -m or -t limits more than truly necessary, consider
+If you have increased the `-m` or `-t` limits more than truly necessary, consider
 dialing them back down.
 
 For programs that are nominally very fast, but get sluggish for some inputs,
-you can also try setting -t values that are more punishing than what afl-fuzz
-dares to use on its own. On fast and idle machines, going down to -t 5 may be
+you can also try setting `-t` values that are more punishing than what `afl-fuzz`
+dares to use on its own. On fast and idle machines, going down to `-t 5` may be
 a viable plan.
 
-The -m parameter is worth looking at, too. Some programs can end up spending
+The `-m` parameter is worth looking at, too. Some programs can end up spending
 a fair amount of time allocating and initializing megabytes of memory when
-presented with pathological inputs. Low -m values can make them give up sooner
+presented with pathological inputs. Low `-m` values can make them give up sooner
 and not waste CPU time.
 
-8) Check OS configuration
--------------------------
+## 8. Check OS configuration
 
 There are several OS-level factors that may affect fuzzing speed:
 
+  - If you have no risk of power loss then run your fuzzing on a tmpfs
+    partition. This increases the performance noticably.
+    Alternatively you can use `AFL_TMPDIR` to point to a tmpfs location to
+    just write the input file to a tmpfs.
   - High system load. Use idle machines where possible. Kill any non-essential
     CPU hogs (idle browser windows, media players, complex screensavers, etc).
-
   - Network filesystems, either used for fuzzer input / output, or accessed by
     the fuzzed binary to read configuration files (pay special attention to the
     home directory - many programs search it for dot-files).
-
-  - On-demand CPU scaling. The Linux 'ondemand' governor performs its analysis
+  - On-demand CPU scaling. The Linux `ondemand` governor performs its analysis
     on a particular schedule and is known to underestimate the needs of
-    short-lived processes spawned by afl-fuzz (or any other fuzzer). On Linux,
+    short-lived processes spawned by `afl-fuzz` (or any other fuzzer). On Linux,
     this can be fixed with:
 
+``` bash
     cd /sys/devices/system/cpu
     echo performance | tee cpu*/cpufreq/scaling_governor
+```
 
     On other systems, the impact of CPU scaling will be different; when fuzzing,
     use OS-specific tools to find out if all cores are running at full speed.
-
-  - Transparent huge pages. Some allocators, such as jemalloc, can incur a
+  - Transparent huge pages. Some allocators, such as `jemalloc`, can incur a
     heavy fuzzing penalty when transparent huge pages (THP) are enabled in the
     kernel. You can disable this via:
 
+```bash
     echo never > /sys/kernel/mm/transparent_hugepage/enabled
+```
 
   - Suboptimal scheduling strategies. The significance of this will vary from
     one target to another, but on Linux, you may want to make sure that the
     following options are set:
 
+```bash
     echo 1 >/proc/sys/kernel/sched_child_runs_first
     echo 1 >/proc/sys/kernel/sched_autogroup_enabled
+```
 
     Setting a different scheduling policy for the fuzzer process - say
-    SCHED_RR - can usually speed things up, too, but needs to be done with
+    `SCHED_RR` - can usually speed things up, too, but needs to be done with
     care.
-
-  - Use the afl-system-config script to set all proc/sys settings above
-
+  - Use the `afl-system-config` script to set all proc/sys settings above in one go.
   - Disable all the spectre, meltdown etc. security countermeasures in the
     kernel if your machine is properly separated:
-    "ibpb=off ibrs=off kpti=off l1tf=off mds=off mitigations=off
-     no_stf_barrier noibpb noibrs nopcid nopti nospec_store_bypass_disable
-     nospectre_v1 nospectre_v2 pcid=off pti=off spec_store_bypass_disable=off
-     spectre_v2=off stf_barrier=off"
-    In most Linux distributions you can put this into a /etc/default/grub
+
+```
+ibpb=off ibrs=off kpti=off l1tf=off mds=off mitigations=off
+no_stf_barrier noibpb noibrs nopcid nopti nospec_store_bypass_disable
+nospectre_v1 nospectre_v2 pcid=off pti=off spec_store_bypass_disable=off
+spectre_v2=off stf_barrier=off
+```
+    In most Linux distributions you can put this into a `/etc/default/grub`
     variable.
 
-9) If all other options fail, use -d
-------------------------------------
+## 9. If all other options fail, use `-d`
 
 For programs that are genuinely slow, in cases where you really can't escape
 using huge input files, or when you simply want to get quick and dirty results
-early on, you can always resort to the -d mode.
+early on, you can always resort to the `-d` mode.
 
-The mode causes afl-fuzz to skip all the deterministic fuzzing steps, which
+The mode causes `afl-fuzz` to skip all the deterministic fuzzing steps, which
 makes output a lot less neat and can ultimately make the testing a bit less
 in-depth, but it will give you an experience more familiar from other fuzzing
 tools.

docs/power_schedules.md

@@ -1,8 +1,9 @@
-afl++'s power schedules based on AFLfast
+# afl++'s power schedules based on AFLfast
 
-<a href="https://comp.nus.edu.sg/~mboehme/paper/CCS16.pdf"><img src="https://comp.nus.edu.sg/~mboehme/paper/CCS16.png" align="right" width="250"></a>
+<a href="https://mboehme.github.io/paper/CCS16.pdf"><img src="https://mboehme.github.io/paper/CCS16.png" align="right" width="250"></a>
 Power schedules implemented by Marcel Böhme \<marcel.boehme@acm.org\>. 
-AFLFast is an extension of AFL which was written by Michal Zalewski \<lcamtuf@google.com\>.
+AFLFast is an extension of AFL which is written and maintained by 
+Michal Zalewski \<lcamtuf@google.com\>.
 
 AFLfast has helped in the success of Team Codejitsu at the finals of the DARPA Cyber Grand Challenge where their bot Galactica took **2nd place** in terms of #POVs proven (see red bar at https://www.cybergrandchallenge.com/event#results). AFLFast exposed several previously unreported CVEs that could not be exposed by AFL in 24 hours and otherwise exposed vulnerabilities significantly faster than AFL while generating orders of magnitude more unique crashes. 
 
@@ -18,6 +19,8 @@ We find that AFL's exploitation-based constant schedule assigns **too much energ
 | `-p quad` | ![QUAD](http://latex.codecogs.com/gif.latex?p%28i%29%20%3D%20%5Cmin%5Cleft%28%5Cfrac%7B%5Calpha%28i%29%7D%7B%5Cbeta%7D%5Ccdot%5Cfrac%7Bs%28i%29%5E2%7D%7Bf%28i%29%7D%2CM%5Cright%29) |
 | `-p lin` | ![LIN](http://latex.codecogs.com/gif.latex?p%28i%29%20%3D%20%5Cmin%5Cleft%28%5Cfrac%7B%5Calpha%28i%29%7D%7B%5Cbeta%7D%5Ccdot%5Cfrac%7Bs%28i%29%7D%7Bf%28i%29%7D%2CM%5Cright%29) |
 | `-p exploit` (AFL) | ![LIN](http://latex.codecogs.com/gif.latex?p%28i%29%20%3D%20%5Calpha%28i%29) |
+| `-p mmopt` | Experimental: `explore` with no weighting to runtime and increased weighting on the last 5 queue entries |
+| `-p rare` | Experimental: `rare` puts focus on queue entries that hit rare edges |
 where *α(i)* is the performance score that AFL uses to compute for the seed input *i*, *β(i)>1* is a constant, *s(i)* is the number of times that seed *i* has been chosen from the queue, *f(i)* is the number of generated inputs that exercise the same path as seed *i*, and *μ* is the average number of generated inputs exercising a path.
   
 More details can be found in the paper that was accepted at the [23rd ACM Conference on Computer and Communications Security (CCS'16)](https://www.sigsac.org/ccs/CCS2016/accepted-papers/).

docs/python_mutators.txt

@@ -1,152 +0,0 @@
-==================================================
-Adding custom mutators to AFL using Python modules
-==================================================
-
-  This file describes how you can utilize the external Python API to write
-  your own custom mutation routines.
-
-  Note: This feature is highly experimental. Use at your own risk.
-
-  Implemented by Christian Holler (:decoder) <choller@mozilla.com>.
-
-  NOTE: This is for Python 2.7 !
-  Anyone who wants to add Python 3.7 support is happily welcome :)
-
-  For an example and a template see ../python_mutators/
-
-
-1) Description and purpose
---------------------------
-
-While AFLFuzz comes with a good selection of generic deterministic and
-non-deterministic mutation operations, it sometimes might make sense to extend
-these to implement strategies more specific to the target you are fuzzing.
-
-For simplicity and in order to allow people without C knowledge to extend
-AFLFuzz, I implemented a "Python" stage that can make use of an external
-module (written in Python) that implements a custom mutation stage.
-
-The main motivation behind this is to lower the barrier for people
-experimenting with this tool. Hopefully, someone will be able to do useful
-things with this extension.
-
-If you find it useful, have questions or need additional features added to the
-interface, feel free to send a mail to <choller@mozilla.com>.
-
-See the following information to get a better pictures:
-  https://www.agarri.fr/docs/XML_Fuzzing-NullCon2017-PUBLIC.pdf
-  https://bugs.chromium.org/p/chromium/issues/detail?id=930663
-
-
-2) How the Python module looks like
------------------------------------
-
-You can find a simple example in pymodules/example.py including documentation
-explaining each function. In the same directory, you can find another simple
-module that performs simple mutations.
-
-Right now, "init" is called at program startup and can be used to perform any
-kinds of one-time initializations while "fuzz" is called each time a mutation
-is requested.
-
-There is also optional support for a trimming API, see the section below for
-further information about this feature.
-
-
-3) How to compile AFLFuzz with Python support
----------------------------------------------
-
-You must install the python 2.7 development package of your Linux distribution
-before this will work. On Debian/Ubuntu/Kali this can be done with:
-  apt install python2.7-dev
-
-A prerequisite for using this mode is to compile AFLFuzz with Python support.
-
-The afl Makefile performs some magic and detects Python 2.7 if it is in the
-default path and compiles afl-fuzz with the feature if available (which is
-/usr/include/python2.7 for the Python.h include and /usr/lib/x86_64-linux-gnu
-for the libpython2.7.a library)
-
-In case your setup is different set the necessary variables like this:
-PYTHON_INCLUDE=/path/to/python2.7/include LDFLAGS=-L/path/to/python2.7/lib make
-
-
-4) How to run AFLFuzz with your custom module
----------------------------------------------
-
-You must pass the module name inside the env variable AFL_PYTHON_MODULE.
-
-In addition, if you are trying to load the module from the local directory,
-you must adjust your PYTHONPATH to reflect this circumstance. The following
-command should work if you are inside the aflfuzz directory:
-
-$ AFL_PYTHON_MODULE="pymodules.test" PYTHONPATH=. ./afl-fuzz
-
-Optionally, the following environment variables are supported:
-
-AFL_PYTHON_ONLY - Disable all other mutation stages. This can prevent broken
-                  testcases (those that your Python module can't work with
-                  anymore) to fill up your queue. Best combined with a custom
-                  trimming routine (see below) because trimming can cause the
-                  same test breakage like havoc and splice.
-
-AFL_DEBUG       - When combined with AFL_NO_UI, this causes the C trimming code
-                  to emit additional messages about the performance and actions
-                  of your custom Python trimmer. Use this to see if it works :)
-
-
-5) Order and statistics
------------------------
-
-The Python stage is set to be the first non-deterministic stage (right before
-the havoc stage). In the statistics however, it shows up as the third number
-under "havoc". That's because I'm lazy and I didn't want to mess with the UI
-too much ;)
-
-
-6) Trimming support
--------------------
-
-The generic trimming routines implemented in AFLFuzz can easily destroy the
-structure of complex formats, possibly leading to a point where you have a lot
-of testcases in the queue that your Python module cannot process anymore but
-your target application still accepts. This is especially the case when your
-target can process a part of the input (causing coverage) and then errors out
-on the remaining input.
-
-In such cases, it makes sense to implement a custom trimming routine in Python.
-The API consists of multiple methods because after each trimming step, we have
-to go back into the C code to check if the coverage bitmap is still the same
-for the trimmed input. Here's a quick API description:
-
-init_trim: This method is called at the start of each trimming operation
-           and receives the initial buffer. It should return the amount
-           of iteration steps possible on this input (e.g. if your input
-           has n elements and you want to remove them one by one, return n,
-           if you do a binary search, return log(n), and so on...).
-
-           If your trimming algorithm doesn't allow you to determine the
-           amount of (remaining) steps easily (esp. while running), then you
-           can alternatively return 1 here and always return 0 in post_trim
-           until you are finished and no steps remain. In that case,
-           returning 1 in post_trim will end the trimming routine. The whole
-           current index/max iterations stuff is only used to show progress.
-
-trim:      This method is called for each trimming operation. It doesn't
-           have any arguments because we already have the initial buffer
-           from init_trim and we can memorize the current state in global
-           variables. This can also save reparsing steps for each iteration.
-           It should return the trimmed input buffer, where the returned data
-           must not exceed the initial input data in length. Returning anything
-           that is larger than the original data (passed to init_trim) will
-           result in a fatal abort of AFLFuzz.
-
-post_trim: This method is called after each trim operation to inform you
-           if your trimming step was successful or not (in terms of coverage).
-           If you receive a failure here, you should reset your input to the
-           last known good state.
-           In any case, this method must return the next trim iteration index
-           (from 0 to the maximum amount of steps you returned in init_trim).
-
-Omitting any of the methods will cause Python trimming to be disabled and
-trigger a fallback to the builtin default trimming routine.

docs/sister_projects.md

@@ -0,0 +1,311 @@
+# Sister projects
+
+This doc lists some of the projects that are inspired by, derived from,
+designed for, or meant to integrate with AFL. See README.md for the general
+instruction manual.
+
+!!!
+!!! This list is outdated and needs an update, missing: e.g. Angora, FairFuzz
+!!!
+
+## Support for other languages / environments:
+
+### Python AFL (Jakub Wilk)
+
+Allows fuzz-testing of Python programs. Uses custom instrumentation and its
+own forkserver.
+
+http://jwilk.net/software/python-afl
+
+### Go-fuzz (Dmitry Vyukov)
+
+AFL-inspired guided fuzzing approach for Go targets:
+
+https://github.com/dvyukov/go-fuzz
+
+### afl.rs (Keegan McAllister)
+
+Allows Rust features to be easily fuzzed with AFL (using the LLVM mode).
+
+https://github.com/kmcallister/afl.rs
+
+### OCaml support (KC Sivaramakrishnan)
+
+Adds AFL-compatible instrumentation to OCaml programs.
+
+https://github.com/ocamllabs/opam-repo-dev/pull/23
+http://canopy.mirage.io/Posts/Fuzzing
+
+### AFL for GCJ Java and other GCC frontends (-)
+
+GCC Java programs are actually supported out of the box - simply rename
+afl-gcc to afl-gcj. Unfortunately, by default, unhandled exceptions in GCJ do
+not result in abort() being called, so you will need to manually add a
+top-level exception handler that exits with SIGABRT or something equivalent.
+
+Other GCC-supported languages should be fairly easy to get working, but may
+face similar problems. See https://gcc.gnu.org/frontends.html for a list of
+options.
+
+## AFL-style in-process fuzzer for LLVM (Kostya Serebryany)
+
+Provides an evolutionary instrumentation-guided fuzzing harness that allows
+some programs to be fuzzed without the fork / execve overhead. (Similar
+functionality is now available as the "persistent" feature described in
+[the llvm_mode readme](../llvm_mode/README.md))
+
+http://llvm.org/docs/LibFuzzer.html
+
+## TriforceAFL (Tim Newsham and Jesse Hertz)
+
+Leverages QEMU full system emulation mode to allow AFL to target operating
+systems and other alien worlds:
+
+https://www.nccgroup.trust/us/about-us/newsroom-and-events/blog/2016/june/project-triforce-run-afl-on-everything/
+
+## WinAFL (Ivan Fratric)
+
+As the name implies, allows you to fuzz Windows binaries (using DynamoRio).
+
+https://github.com/ivanfratric/winafl
+
+Another Windows alternative may be:
+
+https://github.com/carlosgprado/BrundleFuzz/
+
+## Network fuzzing
+
+### Preeny (Yan Shoshitaishvili)
+
+Provides a fairly simple way to convince dynamically linked network-centric
+programs to read from a file or not fork. Not AFL-specific, but described as
+useful by many users. Some assembly required.
+
+https://github.com/zardus/preeny
+
+## Distributed fuzzing and related automation
+
+### roving (Richo Healey)
+
+A client-server architecture for effortlessly orchestrating AFL runs across
+a fleet of machines. You don't want to use this on systems that face the
+Internet or live in other untrusted environments.
+
+https://github.com/richo/roving
+
+### Distfuzz-AFL (Martijn Bogaard)
+
+Simplifies the management of afl-fuzz instances on remote machines. The
+author notes that the current implementation isn't secure and should not
+be exposed on the Internet.
+
+https://github.com/MartijnB/disfuzz-afl
+
+### AFLDFF (quantumvm)
+
+A nice GUI for managing AFL jobs.
+
+https://github.com/quantumvm/AFLDFF
+
+### afl-launch (Ben Nagy)
+
+Batch AFL launcher utility with a simple CLI.
+
+https://github.com/bnagy/afl-launch
+
+### AFL Utils (rc0r)
+
+Simplifies the triage of discovered crashes, start parallel instances, etc.
+
+https://github.com/rc0r/afl-utils
+
+Another crash triage tool:
+
+https://github.com/floyd-fuh/afl-crash-analyzer
+
+### afl-fuzzing-scripts (Tobias Ospelt)
+
+Simplifies starting up multiple parallel AFL jobs.
+
+https://github.com/floyd-fuh/afl-fuzzing-scripts/
+
+### afl-sid (Jacek Wielemborek)
+
+Allows users to more conveniently build and deploy AFL via Docker.
+
+https://github.com/d33tah/afl-sid
+
+Another Docker-related project:
+
+https://github.com/ozzyjohnson/docker-afl
+
+### afl-monitor (Paul S. Ziegler)
+
+Provides more detailed and versatile statistics about your running AFL jobs.
+
+https://github.com/reflare/afl-monitor
+
+### FEXM (Security in Telecommunications)
+
+Fully automated fuzzing framework, based on AFL
+
+https://github.com/fgsect/fexm
+
+## Crash triage, coverage analysis, and other companion tools:
+
+### afl-crash-analyzer (Tobias Ospelt)
+
+Makes it easier to navigate and annotate crashing test cases.
+
+https://github.com/floyd-fuh/afl-crash-analyzer/
+
+### Crashwalk (Ben Nagy)
+
+AFL-aware tool to annotate and sort through crashing test cases.
+
+https://github.com/bnagy/crashwalk
+
+### afl-cov (Michael Rash)
+
+Produces human-readable coverage data based on the output queue of afl-fuzz.
+
+https://github.com/mrash/afl-cov
+
+### afl-sancov (Bhargava Shastry)
+
+Similar to afl-cov, but uses clang sanitizer instrumentation.
+
+https://github.com/bshastry/afl-sancov
+
+### RecidiVM (Jakub Wilk)
+
+Makes it easy to estimate memory usage limits when fuzzing with ASAN or MSAN.
+
+http://jwilk.net/software/recidivm
+
+### aflize (Jacek Wielemborek)
+
+Automatically build AFL-enabled versions of Debian packages.
+
+https://github.com/d33tah/aflize
+
+### afl-ddmin-mod (Markus Teufelberger)
+
+A variant of afl-tmin that uses a more sophisticated (but slower)
+minimization algorithm.
+
+https://github.com/MarkusTeufelberger/afl-ddmin-mod
+
+### afl-kit (Kuang-che Wu)
+
+Replacements for afl-cmin and afl-tmin with additional features, such
+as the ability to filter crashes based on stderr patterns.
+
+https://github.com/kcwu/afl-kit
+
+## Narrow-purpose or experimental:
+
+### Cygwin support (Ali Rizvi-Santiago)
+
+Pretty self-explanatory. As per the author, this "mostly" ports AFL to
+Windows. Field reports welcome!
+
+https://github.com/arizvisa/afl-cygwin
+
+### Pause and resume scripts (Ben Nagy)
+
+Simple automation to suspend and resume groups of fuzzing jobs.
+
+https://github.com/bnagy/afl-trivia
+
+### Static binary-only instrumentation (Aleksandar Nikolich)
+
+Allows black-box binaries to be instrumented statically (i.e., by modifying
+the binary ahead of the time, rather than translating it on the run). Author
+reports better performance compared to QEMU, but occasional translation
+errors with stripped binaries.
+
+https://github.com/vanhauser-thc/afl-dyninst
+
+### AFL PIN (Parker Thompson)
+
+Early-stage Intel PIN instrumentation support (from before we settled on
+faster-running QEMU).
+
+https://github.com/mothran/aflpin
+
+### AFL-style instrumentation in llvm (Kostya Serebryany)
+
+Allows AFL-equivalent instrumentation to be injected at compiler level.
+This is currently not supported by AFL as-is, but may be useful in other
+projects.
+
+https://code.google.com/p/address-sanitizer/wiki/AsanCoverage#Coverage_counters
+
+### AFL JS (Han Choongwoo)
+
+One-off optimizations to speed up the fuzzing of JavaScriptCore (now likely
+superseded by LLVM deferred forkserver init - see llvm_mode/README.md).
+
+https://github.com/tunz/afl-fuzz-js
+
+### AFL harness for fwknop (Michael Rash)
+
+An example of a fairly involved integration with AFL.
+
+https://github.com/mrash/fwknop/tree/master/test/afl
+
+### Building harnesses for DNS servers (Jonathan Foote, Ron Bowes)
+
+Two articles outlining the general principles and showing some example code.
+
+https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop
+https://goo.gl/j9EgFf
+
+### Fuzzer shell for SQLite (Richard Hipp)
+
+A simple SQL shell designed specifically for fuzzing the underlying library.
+
+http://www.sqlite.org/src/artifact/9e7e273da2030371
+
+### Support for Python mutation modules (Christian Holler)
+
+now integrated in AFL++, originally from here
+https://github.com/choller/afl/blob/master/docs/mozilla/python_modules.txt
+
+### Support for selective instrumentation (Christian Holler)
+
+now integrated in AFL++, originally from here
+https://github.com/choller/afl/blob/master/docs/mozilla/partial_instrumentation.txt
+
+### Syzkaller (Dmitry Vyukov)
+
+A similar guided approach as applied to fuzzing syscalls:
+
+https://github.com/google/syzkaller/wiki/Found-Bugs
+https://github.com/dvyukov/linux/commit/33787098ffaaa83b8a7ccf519913ac5fd6125931
+http://events.linuxfoundation.org/sites/events/files/slides/AFL%20filesystem%20fuzzing%2C%20Vault%202016_0.pdf
+
+
+### Kernel Snapshot Fuzzing using Unicornafl (Security in Telecommunications)
+
+https://github.com/fgsect/unicorefuzz
+
+### Android support (ele7enxxh)
+
+Based on a somewhat dated version of AFL:
+
+https://github.com/ele7enxxh/android-afl
+
+### CGI wrapper (floyd)
+
+Facilitates the testing of CGI scripts.
+
+https://github.com/floyd-fuh/afl-cgi-wrapper
+
+### Fuzzing difficulty estimation (Marcel Boehme)
+
+A fork of AFL that tries to quantify the likelihood of finding additional
+paths or crashes at any point in a fuzzing job.
+
+https://github.com/mboehme/pythia

docs/sister_projects.txt

@@ -1,358 +0,0 @@
-===============
-Sister projects
-===============
-
-  This doc lists some of the projects that are inspired by, derived from,
-  designed for, or meant to integrate with AFL. See README for the general
-  instruction manual.
-
-!!!
-!!! This list is outdated and needs an update, missing: e.g. Angora, FairFuzz
-!!!
-
--------------------------------------------
-Support for other languages / environments:
--------------------------------------------
-
-Python AFL (Jakub Wilk)
------------------------
-
-  Allows fuzz-testing of Python programs. Uses custom instrumentation and its
-  own forkserver.
-
-  http://jwilk.net/software/python-afl
-
-Go-fuzz (Dmitry Vyukov)
------------------------
-
-  AFL-inspired guided fuzzing approach for Go targets:
-
-  https://github.com/dvyukov/go-fuzz
-
-afl.rs (Keegan McAllister)
---------------------------
-
-  Allows Rust features to be easily fuzzed with AFL (using the LLVM mode).
-
-  https://github.com/kmcallister/afl.rs
-
-OCaml support (KC Sivaramakrishnan)
------------------------------------
-
-  Adds AFL-compatible instrumentation to OCaml programs.
-
-  https://github.com/ocamllabs/opam-repo-dev/pull/23
-  http://canopy.mirage.io/Posts/Fuzzing
-
-AFL for GCJ Java and other GCC frontends (-)
---------------------------------------------
-
-  GCC Java programs are actually supported out of the box - simply rename
-  afl-gcc to afl-gcj. Unfortunately, by default, unhandled exceptions in GCJ do
-  not result in abort() being called, so you will need to manually add a
-  top-level exception handler that exits with SIGABRT or something equivalent.
-
-  Other GCC-supported languages should be fairly easy to get working, but may
-  face similar problems. See https://gcc.gnu.org/frontends.html for a list of
-  options.
-
-AFL-style in-process fuzzer for LLVM (Kostya Serebryany)
---------------------------------------------------------
-
-  Provides an evolutionary instrumentation-guided fuzzing harness that allows
-  some programs to be fuzzed without the fork / execve overhead. (Similar
-  functionality is now available as the "persistent" feature described in
-  ../llvm_mode/README.llvm.)
-
-  http://llvm.org/docs/LibFuzzer.html
-
-AFL fixup shim (Ben Nagy)
--------------------------
-
-  Allows AFL_POST_LIBRARY postprocessors to be written in arbitrary languages
-  that don't have C / .so bindings. Includes examples in Go.
-
-  https://github.com/bnagy/aflfix
-
-TriforceAFL (Tim Newsham and Jesse Hertz)
------------------------------------------
-
-  Leverages QEMU full system emulation mode to allow AFL to target operating
-  systems and other alien worlds:
-
-  https://www.nccgroup.trust/us/about-us/newsroom-and-events/blog/2016/june/project-triforce-run-afl-on-everything/
-
-WinAFL (Ivan Fratric)
----------------------
-
-  As the name implies, allows you to fuzz Windows binaries (using DynamoRio).
-
-  https://github.com/ivanfratric/winafl
-
-  Another Windows alternative may be:
-
-  https://github.com/carlosgprado/BrundleFuzz/
-
-----------------
-Network fuzzing:
-----------------
-
-Preeny (Yan Shoshitaishvili)
-----------------------------
-
-  Provides a fairly simple way to convince dynamically linked network-centric
-  programs to read from a file or not fork. Not AFL-specific, but described as
-  useful by many users. Some assembly required.
-
-  https://github.com/zardus/preeny
-
--------------------------------------------
-Distributed fuzzing and related automation:
--------------------------------------------
-
-roving (Richo Healey)
----------------------
-
-  A client-server architecture for effortlessly orchestrating AFL runs across
-  a fleet of machines. You don't want to use this on systems that face the
-  Internet or live in other untrusted environments.
-
-  https://github.com/richo/roving
-
-Distfuzz-AFL (Martijn Bogaard)
-------------------------------
-
-  Simplifies the management of afl-fuzz instances on remote machines. The
-  author notes that the current implementation isn't secure and should not
-  be exposed on the Internet.
-
-  https://github.com/MartijnB/disfuzz-afl
-
-AFLDFF (quantumvm)
-------------------
-
-  A nice GUI for managing AFL jobs.
-
-  https://github.com/quantumvm/AFLDFF
-
-afl-launch (Ben Nagy)
----------------------
-
-  Batch AFL launcher utility with a simple CLI.
-
-  https://github.com/bnagy/afl-launch
-
-AFL Utils (rc0r)
-----------------
-
-  Simplifies the triage of discovered crashes, start parallel instances, etc.
-
-  https://github.com/rc0r/afl-utils
-
-  Another crash triage tool:
-
-  https://github.com/floyd-fuh/afl-crash-analyzer
-
-afl-fuzzing-scripts (Tobias Ospelt)
------------------------------------
-
-  Simplifies starting up multiple parallel AFL jobs.
-
-  https://github.com/floyd-fuh/afl-fuzzing-scripts/
-
-afl-sid (Jacek Wielemborek)
----------------------------
-
-  Allows users to more conveniently build and deploy AFL via Docker.
-
-  https://github.com/d33tah/afl-sid
-
-  Another Docker-related project:
-
-  https://github.com/ozzyjohnson/docker-afl
-
-afl-monitor (Paul S. Ziegler)
------------------------------
-
-  Provides more detailed and versatile statistics about your running AFL jobs.
-
-  https://github.com/reflare/afl-monitor
-
------------------------------------------------------------
-Crash triage, coverage analysis, and other companion tools:
------------------------------------------------------------
-
-afl-crash-analyzer (Tobias Ospelt)
-----------------------------------
-
-  Makes it easier to navigate and annotate crashing test cases.
-
-  https://github.com/floyd-fuh/afl-crash-analyzer/
-
-Crashwalk (Ben Nagy)
---------------------
-
-  AFL-aware tool to annotate and sort through crashing test cases.
-
-  https://github.com/bnagy/crashwalk
-
-afl-cov (Michael Rash)
-----------------------
-
-  Produces human-readable coverage data based on the output queue of afl-fuzz.
-
-  https://github.com/mrash/afl-cov
-
-afl-sancov (Bhargava Shastry)
------------------------------
-
-  Similar to afl-cov, but uses clang sanitizer instrumentation.
-
-  https://github.com/bshastry/afl-sancov
-
-RecidiVM (Jakub Wilk)
----------------------
-
-  Makes it easy to estimate memory usage limits when fuzzing with ASAN or MSAN.
-
-  http://jwilk.net/software/recidivm
-
-aflize (Jacek Wielemborek)
---------------------------
-
-  Automatically build AFL-enabled versions of Debian packages.
-
-  https://github.com/d33tah/aflize
-
-afl-ddmin-mod (Markus Teufelberger)
------------------------------------
-
-  A variant of afl-tmin that uses a more sophisticated (but slower)
-  minimization algorithm.
-
-  https://github.com/MarkusTeufelberger/afl-ddmin-mod
-
-afl-kit (Kuang-che Wu)
-----------------------
-
-  Replacements for afl-cmin and afl-tmin with additional features, such
-  as the ability to filter crashes based on stderr patterns.
-
-  https://github.com/kcwu/afl-kit
-
--------------------------------
-Narrow-purpose or experimental:
--------------------------------
-
-Cygwin support (Ali Rizvi-Santiago)
------------------------------------
-
-  Pretty self-explanatory. As per the author, this "mostly" ports AFL to
-  Windows. Field reports welcome!
-
-  https://github.com/arizvisa/afl-cygwin
-
-Pause and resume scripts (Ben Nagy)
------------------------------------
-
-  Simple automation to suspend and resume groups of fuzzing jobs.
-
-  https://github.com/bnagy/afl-trivia
-
-Static binary-only instrumentation (Aleksandar Nikolich)
---------------------------------------------------------
-
-  Allows black-box binaries to be instrumented statically (i.e., by modifying
-  the binary ahead of the time, rather than translating it on the run). Author
-  reports better performance compared to QEMU, but occasional translation
-  errors with stripped binaries.
-
-  https://github.com/vanhauser-thc/afl-dyninst
-
-AFL PIN (Parker Thompson)
--------------------------
-
-  Early-stage Intel PIN instrumentation support (from before we settled on
-  faster-running QEMU).
-
-  https://github.com/mothran/aflpin
-
-AFL-style instrumentation in llvm (Kostya Serebryany)
------------------------------------------------------
-
-  Allows AFL-equivalent instrumentation to be injected at compiler level.
-  This is currently not supported by AFL as-is, but may be useful in other
-  projects.
-
-  https://code.google.com/p/address-sanitizer/wiki/AsanCoverage#Coverage_counters
-
-AFL JS (Han Choongwoo)
-----------------------
-
-  One-off optimizations to speed up the fuzzing of JavaScriptCore (now likely
-  superseded by LLVM deferred forkserver init - see llvm_mode/README.llvm).
-
-  https://github.com/tunz/afl-fuzz-js
-
-AFL harness for fwknop (Michael Rash)
--------------------------------------
-
-  An example of a fairly involved integration with AFL.
-
-  https://github.com/mrash/fwknop/tree/master/test/afl
-
-Building harnesses for DNS servers (Jonathan Foote, Ron Bowes)
---------------------------------------------------------------
-
-  Two articles outlining the general principles and showing some example code.
-
-  https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop
-  https://goo.gl/j9EgFf
-
-Fuzzer shell for SQLite (Richard Hipp)
---------------------------------------
-
-  A simple SQL shell designed specifically for fuzzing the underlying library.
-
-  http://www.sqlite.org/src/artifact/9e7e273da2030371
-
-Support for Python mutation modules (Christian Holler)
-------------------------------------------------------
-
-  https://github.com/choller/afl/blob/master/docs/mozilla/python_modules.txt
-
-Support for selective instrumentation (Christian Holler)
---------------------------------------------------------
-
-  https://github.com/choller/afl/blob/master/docs/mozilla/partial_instrumentation.txt
-
-Kernel fuzzing (Dmitry Vyukov)
-------------------------------
-
-  A similar guided approach as applied to fuzzing syscalls:
-
-  https://github.com/google/syzkaller/wiki/Found-Bugs
-  https://github.com/dvyukov/linux/commit/33787098ffaaa83b8a7ccf519913ac5fd6125931
-  http://events.linuxfoundation.org/sites/events/files/slides/AFL%20filesystem%20fuzzing%2C%20Vault%202016_0.pdf
-
-Android support (ele7enxxh)
----------------------------
-
-  Based on a somewhat dated version of AFL:
-
-  https://github.com/ele7enxxh/android-afl
-
-CGI wrapper (floyd)
--------------------
-
-  Facilitates the testing of CGI scripts.
-
-  https://github.com/floyd-fuh/afl-cgi-wrapper
-
-Fuzzing difficulty estimation (Marcel Boehme)
----------------------------------------------
-
-  A fork of AFL that tries to quantify the likelihood of finding additional
-  paths or crashes at any point in a fuzzing job.
-
-  https://github.com/mboehme/pythia

docs/status_screen.md

@@ -1,13 +1,10 @@
-===============================
-Understanding the status screen
-===============================
+# Understanding the status screen
 
-  This document provides an overview of the status screen - plus tips for
-  troubleshooting any warnings and red text shown in the UI. See README for
-  the general instruction manual.
+This document provides an overview of the status screen - plus tips for
+troubleshooting any warnings and red text shown in the UI. See README.md for
+the general instruction manual.
 
-0) A note about colors
-----------------------
+## A note about colors
 
 The status screen and error messages use colors to keep things readable and
 attract your attention to the most important details. For example, red almost
@@ -19,21 +16,18 @@ to that.
 
 If you are using inverse video, you may want to change your settings, say:
 
-  - For GNOME Terminal, go to Edit > Profile preferences, select the "colors"
-    tab, and from the list of built-in schemes, choose "white on black".
-
-  - For the MacOS X Terminal app, open a new window using the "Pro" scheme via
-    the Shell > New Window menu (or make "Pro" your default).
+- For GNOME Terminal, go to `Edit > Profile` preferences, select the "colors" tab, and from the list of built-in schemes, choose "white on black". 
+- For the MacOS X Terminal app, open a new window using the "Pro" scheme via the `Shell > New Window` menu (or make "Pro" your default).
 
 Alternatively, if you really like your current colors, you can edit config.h
-to comment out USE_COLORS, then do 'make clean all'.
+to comment out USE_COLORS, then do `make clean all`.
 
 I'm not aware of any other simple way to make this work without causing
 other side effects - sorry about that.
 
 With that out of the way, let's talk about what's actually on the screen...
 
-0) The status bar
+### The status bar
 
 The top line shows you which mode afl-fuzz is running in
 (normal: "american fuzy lop", crash exploration mode: "peruvian rabbit mode")
@@ -43,15 +37,16 @@ either show the binary name being fuzzed, or the -M/-S master/slave name for
 parallel fuzzing.
 Finally, the last item is the power schedule mode being run (default: explore).
 
-1) Process timing
------------------
+### Process timing
 
+```
   +----------------------------------------------------+
   |        run time : 0 days, 8 hrs, 32 min, 43 sec    |
   |   last new path : 0 days, 0 hrs, 6 min, 40 sec     |
   | last uniq crash : none seen yet                    |
   |  last uniq hang : 0 days, 1 hrs, 24 min, 32 sec    |
   +----------------------------------------------------+
+```
 
 This section is fairly self-explanatory: it tells you how long the fuzzer has
 been running and how much time has elapsed since its most recent finds. This is
@@ -67,36 +62,36 @@ There's one important thing to watch out for: if the tool is not finding new
 paths within several minutes of starting, you're probably not invoking the
 target binary correctly and it never gets to parse the input files we're
 throwing at it; another possible explanations are that the default memory limit
-(-m) is too restrictive, and the program exits after failing to allocate a
+(`-m`) is too restrictive, and the program exits after failing to allocate a
 buffer very early on; or that the input files are patently invalid and always
 fail a basic header check.
 
 If there are no new paths showing up for a while, you will eventually see a big
 red warning in this section, too :-)
 
-2) Overall results
-------------------
+### Overall results
 
+```
   +-----------------------+
   |  cycles done : 0      |
   |  total paths : 2095   |
   | uniq crashes : 0      |
   |   uniq hangs : 19     |
   +-----------------------+
+```
 
-The first field in this section gives you the count of queue passes done so far
-- that is, the number of times the fuzzer went over all the interesting test
+The first field in this section gives you the count of queue passes done so far - that is, the number of times the fuzzer went over all the interesting test
 cases discovered so far, fuzzed them, and looped back to the very beginning.
 Every fuzzing session should be allowed to complete at least one cycle; and
 ideally, should run much longer than that.
 
 As noted earlier, the first pass can take a day or longer, so sit back and
 relax. If you want to get broader but more shallow coverage right away, try
-the -d option - it gives you a more familiar experience by skipping the
+the `-d` option - it gives you a more familiar experience by skipping the
 deterministic fuzzing steps. It is, however, inferior to the standard mode in
 a couple of subtle ways.
 
-To help make the call on when to hit Ctrl-C, the cycle counter is color-coded.
+To help make the call on when to hit `Ctrl-C`, the cycle counter is color-coded.
 It is shown in magenta during the first pass, progresses to yellow if new finds
 are still being made in subsequent rounds, then blue when that ends - and
 finally, turns green after the fuzzer hasn't been seeing any action for a
@@ -105,33 +100,35 @@ longer while.
 The remaining fields in this part of the screen should be pretty obvious:
 there's the number of test cases ("paths") discovered so far, and the number of
 unique faults. The test cases, crashes, and hangs can be explored in real-time
-by browsing the output directory, as discussed in the README.
+by browsing the output directory, as discussed in README.md.
 
-3) Cycle progress
------------------
+### Cycle progress
 
+```
   +-------------------------------------+
   |  now processing : 1296 (61.86%)     |
   | paths timed out : 0 (0.00%)         |
   +-------------------------------------+
+```
 
 This box tells you how far along the fuzzer is with the current queue cycle: it
 shows the ID of the test case it is currently working on, plus the number of
 inputs it decided to ditch because they were persistently timing out.
 
 The "*" suffix sometimes shown in the first line means that the currently
-processed path is not "favored" (a property discussed later on, in section 6).
+processed path is not "favored" (a property discussed later on).
 
 If you feel that the fuzzer is progressing too slowly, see the note about the
--d option in section 2 of this doc.
+`-d` option in this doc.
 
-4) Map coverage
----------------
+### Map coverage
 
+```
   +--------------------------------------+
   |    map density : 10.15% / 29.07%     |
   | count coverage : 4.03 bits/tuple     |
   +--------------------------------------+
+```
 
 The section provides some trivia about the coverage observed by the
 instrumentation embedded in the target binary.
@@ -148,37 +145,35 @@ Be wary of extremes:
     due to being linked against a non-instrumented copy of the target
     library); or that it is bailing out prematurely on your input test cases.
     The fuzzer will try to mark this in pink, just to make you aware.
-
   - Percentages over 70% may very rarely happen with very complex programs
     that make heavy use of template-generated code.
-
     Because high bitmap density makes it harder for the fuzzer to reliably
     discern new program states, I recommend recompiling the binary with
-    AFL_INST_RATIO=10 or so and trying again (see env_variables.txt).
-
+    `AFL_INST_RATIO=10` or so and trying again (see env_variables.md).
     The fuzzer will flag high percentages in red. Chances are, you will never
     see that unless you're fuzzing extremely hairy software (say, v8, perl,
     ffmpeg).
 
 The other line deals with the variability in tuple hit counts seen in the
 binary. In essence, if every taken branch is always taken a fixed number of
-times for all the inputs we have tried, this will read "1.00". As we manage
+times for all the inputs we have tried, this will read `1.00`. As we manage
 to trigger other hit counts for every branch, the needle will start to move
-toward "8.00" (every bit in the 8-bit map hit), but will probably never
+toward `8.00` (every bit in the 8-bit map hit), but will probably never
 reach that extreme.
 
 Together, the values can be useful for comparing the coverage of several
 different fuzzing jobs that rely on the same instrumented binary.
 
-5) Stage progress
------------------
+### Stage progress
 
+```
   +-------------------------------------+
   |  now trying : interest 32/8         |
   | stage execs : 3996/34.4k (11.62%)   |
   | total execs : 27.4M                 |
   |  exec speed : 891.7/sec             |
   +-------------------------------------+
+```
 
 This part gives you an in-depth peek at what the fuzzer is actually doing right
 now. It tells you about the current stage, which can be any of:
@@ -186,39 +181,31 @@ now. It tells you about the current stage, which can be any of:
   - calibration - a pre-fuzzing stage where the execution path is examined
     to detect anomalies, establish baseline execution speed, and so on. Executed
     very briefly whenever a new find is being made.
-
   - trim L/S - another pre-fuzzing stage where the test case is trimmed to the
     shortest form that still produces the same execution path. The length (L)
     and stepover (S) are chosen in general relationship to file size.
-
   - bitflip L/S - deterministic bit flips. There are L bits toggled at any given
     time, walking the input file with S-bit increments. The current L/S variants
-    are: 1/1, 2/1, 4/1, 8/8, 16/8, 32/8.
-
+    are: `1/1`, `2/1`, `4/1`, `8/8`, `16/8`, `32/8`.
   - arith L/8 - deterministic arithmetics. The fuzzer tries to subtract or add
     small integers to 8-, 16-, and 32-bit values. The stepover is always 8 bits.
-
   - interest L/8 - deterministic value overwrite. The fuzzer has a list of known
     "interesting" 8-, 16-, and 32-bit values to try. The stepover is 8 bits.
-
   - extras - deterministic injection of dictionary terms. This can be shown as
     "user" or "auto", depending on whether the fuzzer is using a user-supplied
-    dictionary (-x) or an auto-created one. You will also see "over" or "insert",
+    dictionary (`-x`) or an auto-created one. You will also see "over" or "insert",
     depending on whether the dictionary words overwrite existing data or are
     inserted by offsetting the remaining data to accommodate their length.
-
   - havoc - a sort-of-fixed-length cycle with stacked random tweaks. The
     operations attempted during this stage include bit flips, overwrites with
     random and "interesting" integers, block deletion, block duplication, plus
     assorted dictionary-related operations (if a dictionary is supplied in the
     first place).
-
   - splice - a last-resort strategy that kicks in after the first full queue
     cycle with no new paths. It is equivalent to 'havoc', except that it first
     splices together two random inputs from the queue at some arbitrarily
     selected midpoint.
-
-  - sync - a stage used only when -M or -S is set (see parallel_fuzzing.txt).
+  - sync - a stage used only when `-M` or `-S` is set (see parallel_fuzzing.md).
     No real fuzzing is involved, but the tool scans the output from other
     fuzzers and imports test cases as necessary. The first time this is done,
     it may take several minutes or so.
@@ -231,18 +218,19 @@ most of the time - and if it stays below 100, the job will probably take very
 long.
 
 The fuzzer will explicitly warn you about slow targets, too. If this happens,
-see the perf_tips.txt file included with the fuzzer for ideas on how to speed
+see the [perf_tips.md](perf_tips.md) file included with the fuzzer for ideas on how to speed
 things up.
 
-6) Findings in depth
---------------------
+### Findings in depth
 
+```
   +--------------------------------------+
   | favored paths : 879 (41.96%)         |
   |  new edges on : 423 (20.19%)         |
   | total crashes : 0 (0 unique)         |
   |  total tmouts : 24 (19 unique)       |
   +--------------------------------------+
+```
 
 This gives you several metrics that are of interest mostly to complete nerds.
 The section includes the number of paths that the fuzzer likes the most based
@@ -255,9 +243,9 @@ Note that the timeout counter is somewhat different from the hang counter; this
 one includes all test cases that exceeded the timeout, even if they did not
 exceed it by a margin sufficient to be classified as hangs.
 
-7) Fuzzing strategy yields
---------------------------
+### Fuzzing strategy yields
 
+```
   +-----------------------------------------------------+
   |   bit flips : 57/289k, 18/289k, 18/288k             |
   |  byte flips : 0/36.2k, 4/35.7k, 7/34.6k             |
@@ -267,6 +255,7 @@ exceed it by a margin sufficient to be classified as hangs.
   |       havoc : 1903/20.0M, 0/0                       |
   |        trim : 20.31%/9201, 17.05%                   |
   +-----------------------------------------------------+
+```
 
 This is just another nerd-targeted section keeping track of how many paths we
 have netted, in proportion to the number of execs attempted, for each of the
@@ -280,9 +269,9 @@ goal. Finally, the third number shows the proportion of bytes that, although
 not possible to remove, were deemed to have no effect and were excluded from
 some of the more expensive deterministic fuzzing steps.
 
-8) Path geometry
-----------------
+### Path geometry
 
+```
   +---------------------+
   |    levels : 5       |
   |   pending : 1570    |
@@ -291,6 +280,7 @@ some of the more expensive deterministic fuzzing steps.
   |  imported : 0       |
   | stability : 100.00% |
   +---------------------+
+```
 
 The first field in this section tracks the path depth reached through the
 guided fuzzing process. In essence: the initial test cases supplied by the
@@ -323,46 +313,40 @@ there are several things to look at:
   - The use of uninitialized memory in conjunction with some intrinsic sources
     of entropy in the tested binary. Harmless to AFL, but could be indicative
     of a security bug.
-
   - Attempts to manipulate persistent resources, such as left over temporary
     files or shared memory objects. This is usually harmless, but you may want
     to double-check to make sure the program isn't bailing out prematurely.
     Running out of disk space, SHM handles, or other global resources can
     trigger this, too.
-
   - Hitting some functionality that is actually designed to behave randomly.
     Generally harmless. For example, when fuzzing sqlite, an input like
-    'select random();' will trigger a variable execution path.
-
+    `select random();` will trigger a variable execution path.
   - Multiple threads executing at once in semi-random order. This is harmless
     when the 'stability' metric stays over 90% or so, but can become an issue
     if not. Here's what to try:
-
-    - Use afl-clang-fast from llvm_mode/ - it uses a thread-local tracking
+    * Use afl-clang-fast from [llvm_mode](../llvm_mode/) - it uses a thread-local tracking
       model that is less prone to concurrency issues,
-
-    - See if the target can be compiled or run without threads. Common
-      ./configure options include --without-threads, --disable-pthreads, or
-      --disable-openmp.
-
-    - Replace pthreads with GNU Pth (https://www.gnu.org/software/pth/), which
+    * See if the target can be compiled or run without threads. Common
+      `./configure` options include `--without-threads`, `--disable-pthreads`, or
+      `--disable-openmp`.
+    * Replace pthreads with GNU Pth (https://www.gnu.org/software/pth/), which
       allows you to use a deterministic scheduler.
-
   - In persistent mode, minor drops in the "stability" metric can be normal,
     because not all the code behaves identically when re-entered; but major
-    dips may signify that the code within __AFL_LOOP() is not behaving
+    dips may signify that the code within `__AFL_LOOP()` is not behaving
     correctly on subsequent iterations (e.g., due to incomplete clean-up or
     reinitialization of the state) and that most of the fuzzing effort goes
     to waste.
 
 The paths where variable behavior is detected are marked with a matching entry
-in the <out_dir>/queue/.state/variable_behavior/ directory, so you can look
+in the `<out_dir>/queue/.state/variable_behavior/` directory, so you can look
 them up easily.
 
-9) CPU load
------------
+### CPU load
 
+```
   [cpu: 25%]
+```
 
 This tiny widget shows the apparent CPU utilization on the local system. It is
 calculated by taking the number of processes in the "runnable" state, and then
@@ -370,7 +354,7 @@ comparing it to the number of logical cores on the system.
 
 If the value is shown in green, you are using fewer CPU cores than available on
 your system and can probably parallelize to improve performance; for tips on
-how to do that, see parallel_fuzzing.txt.
+how to do that, see parallel_fuzzing.md.
 
 If the value is shown in red, your CPU is *possibly* oversubscribed, and
 running additional fuzzers may not give you any benefits.
@@ -380,36 +364,51 @@ are ready to run, but not how resource-hungry they may be. It also doesn't
 distinguish between physical cores, logical cores, and virtualized CPUs; the
 performance characteristics of each of these will differ quite a bit.
 
-If you want a more accurate measurement, you can run the afl-gotcpu utility
-from the command line.
+If you want a more accurate measurement, you can run the `afl-gotcpu` utility from the command line.
 
-10) Addendum: status and plot files
------------------------------------
+### Addendum: status and plot files
 
 For unattended operation, some of the key status screen information can be also
 found in a machine-readable format in the fuzzer_stats file in the output
 directory. This includes:
 
-  - start_time     - unix time indicating the start time of afl-fuzz
-  - last_update    - unix time corresponding to the last update of this file
-  - fuzzer_pid     - PID of the fuzzer process
-  - cycles_done    - queue cycles completed so far
-  - execs_done     - number of execve() calls attempted
-  - execs_per_sec  - current number of execs per second
-  - paths_total    - total number of entries in the queue
-  - paths_found    - number of entries discovered through local fuzzing
-  - paths_imported - number of entries imported from other instances
-  - max_depth      - number of levels in the generated data set
-  - cur_path       - currently processed entry number
-  - pending_favs   - number of favored entries still waiting to be fuzzed
-  - pending_total  - number of all entries waiting to be fuzzed
-  - stability      - percentage of bitmap bytes that behave consistently
-  - variable_paths - number of test cases showing variable behavior
-  - unique_crashes - number of unique crashes recorded
-  - unique_hangs   - number of unique hangs encountered
+  - `start_time`        - unix time indicating the start time of afl-fuzz
+  - `last_update`       - unix time corresponding to the last update of this file
+  - `run_time`          - run time in seconds to the last update of this file
+  - `fuzzer_pid`        - PID of the fuzzer process
+  - `cycles_done`       - queue cycles completed so far
+  - `cycles_wo_finds`   - number of cycles without any new paths found
+  - `execs_done`        - number of execve() calls attempted
+  - `execs_per_sec`     - overall number of execs per second
+  - `paths_total`       - total number of entries in the queue
+  - `paths_favored`     - number of queue entries that are favored
+  - `paths_found`       - number of entries discovered through local fuzzing
+  - `paths_imported`    - number of entries imported from other instances
+  - `max_depth`         - number of levels in the generated data set
+  - `cur_path`          - currently processed entry number
+  - `pending_favs`      - number of favored entries still waiting to be fuzzed
+  - `pending_total`     - number of all entries waiting to be fuzzed
+  - `variable_paths`    - number of test cases showing variable behavior
+  - `stability`         - percentage of bitmap bytes that behave consistently
+  - `bitmap_cvg`        - percentage of edge coverage found in the map so far
+  - `unique_crashes`    - number of unique crashes recorded
+  - `unique_hangs`      - number of unique hangs encountered
+  - `last_path`         - seconds since the last path was found
+  - `last_crash`        - seconds since the last crash was found
+  - `last_hang`         - seconds since the last hang was found
+  - `execs_since_crash` - execs since the last crash was found
+  - `exec_timeout`      - the -t command line value
+  - `slowest_exec_ms`   - real time of the slowest execution in ms
+  - `peak_rss_mb`       - max rss usage reached during fuzzing in MB
+  - `edges_found`       - how many edges have been found
+  - `var_byte_count`    - how many edges are non-deterministic
+  - `afl_banner`        - banner text (e.g. the target name)
+  - `afl_version`       - the version of afl used
+  - `target_mode`       - default, persistent, qemu, unicorn, dumb
+  - `command_line`      - full command line used for the fuzzing session
 
 Most of these map directly to the UI elements discussed earlier on.
 
-On top of that, you can also find an entry called 'plot_data', containing a
+On top of that, you can also find an entry called `plot_data`, containing a
 plottable history for most of these fields. If you have gnuplot installed, you
-can turn this into a nice progress report with the included 'afl-plot' tool.
+can turn this into a nice progress report with the included `afl-plot` tool.

docs/technical_details.md

@@ -1,13 +1,10 @@
-===================================
-Technical "whitepaper" for afl-fuzz
-===================================
+# Technical "whitepaper" for afl-fuzz
 
-  This document provides a quick overview of the guts of American Fuzzy Lop.
-  See README for the general instruction manual; and for a discussion of
-  motivations and design goals behind AFL, see historical_notes.txt.
+This document provides a quick overview of the guts of American Fuzzy Lop.
+See README.md for the general instruction manual; and for a discussion of
+motivations and design goals behind AFL, see historical_notes.md.
 
-0) Design statement
--------------------
+## 0. Design statement
 
 American Fuzzy Lop does its best not to focus on any singular principle of
 operation and not be a proof-of-concept for any specific theory. The tool can
@@ -20,28 +17,30 @@ lightweight instrumentation that served as a foundation for the tool, but this
 mechanism should be thought of merely as a means to an end. The only true
 governing principles are speed, reliability, and ease of use.
 
-1) Coverage measurements
-------------------------
+## 1. Coverage measurements
 
 The instrumentation injected into compiled programs captures branch (edge)
 coverage, along with coarse branch-taken hit counts. The code injected at
 branch points is essentially equivalent to:
 
+```c
   cur_location = <COMPILE_TIME_RANDOM>;
   shared_mem[cur_location ^ prev_location]++; 
   prev_location = cur_location >> 1;
+```
 
-The cur_location value is generated randomly to simplify the process of
+The `cur_location` value is generated randomly to simplify the process of
 linking complex projects and keep the XOR output distributed uniformly.
 
-The shared_mem[] array is a 64 kB SHM region passed to the instrumented binary
+The `shared_mem[]` array is a 64 kB SHM region passed to the instrumented binary
 by the caller. Every byte set in the output map can be thought of as a hit for
-a particular (branch_src, branch_dst) tuple in the instrumented code.
+a particular (`branch_src`, `branch_dst`) tuple in the instrumented code.
 
 The size of the map is chosen so that collisions are sporadic with almost all
 of the intended targets, which usually sport between 2k and 10k discoverable
 branch points:
 
+```
    Branch cnt | Colliding tuples | Example targets
   ------------+------------------+-----------------
         1,000 | 0.75%            | giflib, lzo
@@ -50,6 +49,7 @@ branch points:
        10,000 | 7%               | libxml
        20,000 | 14%              | sqlite
        50,000 | 30%              | -
+```
 
 At the same time, its size is small enough to allow the map to be analyzed
 in a matter of microseconds on the receiving end, and to effortlessly fit
@@ -59,8 +59,10 @@ This form of coverage provides considerably more insight into the execution
 path of the program than simple block coverage. In particular, it trivially
 distinguishes between the following execution traces:
 
+```
   A -> B -> C -> D -> E (tuples: AB, BC, CD, DE)
   A -> B -> D -> C -> E (tuples: AB, BD, DC, CE)
+```
 
 This aids the discovery of subtle fault conditions in the underlying code,
 because security vulnerabilities are more often associated with unexpected
@@ -75,8 +77,7 @@ The absence of simple saturating arithmetic opcodes on Intel CPUs means that
 the hit counters can sometimes wrap around to zero. Since this is a fairly
 unlikely and localized event, it's seen as an acceptable performance trade-off.
 
-2) Detecting new behaviors
---------------------------
+### 2. Detecting new behaviors
 
 The fuzzer maintains a global map of tuples seen in previous executions; this
 data can be rapidly compared with individual traces and updated in just a couple
@@ -97,18 +98,24 @@ To illustrate the properties of the algorithm, consider that the second trace
 shown below would be considered substantially new because of the presence of
 new tuples (CA, AE):
 
+```
   #1: A -> B -> C -> D -> E
   #2: A -> B -> C -> A -> E
+```
 
 At the same time, with #2 processed, the following pattern will not be seen
 as unique, despite having a markedly different overall execution path:
 
+```
   #3: A -> B -> C -> A -> B -> C -> A -> B -> C -> D -> E
+```
 
 In addition to detecting new tuples, the fuzzer also considers coarse tuple
 hit counts. These are divided into several buckets:
 
+```
   1, 2, 3, 4-7, 8-15, 16-31, 32-127, 128+
+```
 
 To some extent, the number of buckets is an implementation artifact: it allows
 an in-place mapping of an 8-bit counter generated by the instrumentation to
@@ -135,8 +142,7 @@ reject them and hope that the fuzzer will find a less expensive way to reach
 the same code. Empirical testing strongly suggests that more generous time
 limits are not worth the cost.
 
-3) Evolving the input queue
----------------------------
+## 3. Evolving the input queue
 
 Mutated test cases that produced new state transitions within the program are
 added to the input queue and used as a starting point for future rounds of
@@ -146,7 +152,7 @@ In contrast to more greedy genetic algorithms, this approach allows the tool
 to progressively explore various disjoint and possibly mutually incompatible
 features of the underlying data format, as shown in this image:
 
-  http://lcamtuf.coredump.cx/afl/afl_gzip.png
+  ![gzip_coverage](./visualization/afl_gzip.png)
 
 Several practical examples of the results of this algorithm are discussed
 here:
@@ -165,10 +171,11 @@ of new tuples, and the remainder is associated with changes in hit counts.
 
 The following table compares the relative ability to discover file syntax and
 explore program states when using several different approaches to guided
-fuzzing. The instrumented target was GNU patch 2.7.3 compiled with -O3 and
+fuzzing. The instrumented target was GNU patch 2.7k.3 compiled with `-O3` and
 seeded with a dummy text file; the session consisted of a single pass over the
 input queue with afl-fuzz:
 
+```
     Fuzzer guidance | Blocks  | Edges   | Edge hit | Highest-coverage
       strategy used | reached | reached | cnt var  | test case generated
   ------------------+---------+---------+----------+---------------------------
@@ -179,6 +186,7 @@ input queue with afl-fuzz:
      Block coverage | 855     | 1,130   | 1.57     | Almost-valid RCS diff
       Edge coverage | 1,452   | 2,070   | 2.18     | One-chunk -c mode diff
           AFL model | 1,765   | 2,597   | 4.99     | Four-chunk -c mode diff
+```
 
 The first entry for blind fuzzing ("S") corresponds to executing just a single
 round of testing; the second set of figures ("L") shows the fuzzer running in a
@@ -191,6 +199,7 @@ a series of rudimentary, sequential operations such as walking bit flips.
 Because this mode would be incapable of altering the size of the input file,
 the sessions were seeded with a valid unified diff:
 
+```
     Queue extension | Blocks  | Edges   | Edge hit | Number of unique
       strategy used | reached | reached | cnt var  | crashes found
   ------------------+---------+---------+----------+------------------
@@ -200,14 +209,14 @@ the sessions were seeded with a valid unified diff:
      Block coverage | 1,255   | 1,649   | 1.48     | 0
       Edge coverage | 1,259   | 1,734   | 1.72     | 0
           AFL model | 1,452   | 2,040   | 3.16     | 1
+```
 
 At noted earlier on, some of the prior work on genetic fuzzing relied on
 maintaining a single test case and evolving it to maximize coverage. At least
 in the tests described above, this "greedy" approach appears to confer no
 substantial benefits over blind fuzzing strategies.
 
-4) Culling the corpus
----------------------
+### 4. Culling the corpus
 
 The progressive state exploration approach outlined above means that some of
 the test cases synthesized later on in the game may have edge coverage that
@@ -225,11 +234,8 @@ for each tuple.
 The tuples are then processed sequentially using a simple workflow:
 
   1) Find next tuple not yet in the temporary working set,
-
   2) Locate the winning queue entry for this tuple,
-
   3) Register *all* tuples present in that entry's trace in the working set,
-
   4) Go to #1 if there are any missing tuples in the set.
 
 The generated corpus of "favored" entries is usually 5-10x smaller than the
@@ -238,30 +244,26 @@ with varying probabilities when encountered in the queue:
 
   - If there are new, yet-to-be-fuzzed favorites present in the queue, 99%
     of non-favored entries will be skipped to get to the favored ones.
-
   - If there are no new favorites:
-
-    - If the current non-favored entry was fuzzed before, it will be skipped
+    * If the current non-favored entry was fuzzed before, it will be skipped
       95% of the time.
-
-    - If it hasn't gone through any fuzzing rounds yet, the odds of skipping
+    * If it hasn't gone through any fuzzing rounds yet, the odds of skipping
       drop down to 75%.
 
 Based on empirical testing, this provides a reasonable balance between queue
 cycling speed and test case diversity.
 
 Slightly more sophisticated but much slower culling can be performed on input
-or output corpora with afl-cmin. This tool permanently discards the redundant
-entries and produces a smaller corpus suitable for use with afl-fuzz or
+or output corpora with `afl-cmin`. This tool permanently discards the redundant
+entries and produces a smaller corpus suitable for use with `afl-fuzz` or
 external tools.
 
-5) Trimming input files
------------------------
+## 5. Trimming input files
 
 File size has a dramatic impact on fuzzing performance, both because large
 files make the target binary slower, and because they reduce the likelihood
 that a mutation would touch important format control structures, rather than
-redundant data blocks. This is discussed in more detail in perf_tips.txt.
+redundant data blocks. This is discussed in more detail in perf_tips.md.
 
 The possibility that the user will provide a low-quality starting corpus aside,
 some types of mutations can have the effect of iteratively increasing the size
@@ -275,17 +277,18 @@ The built-in trimmer in afl-fuzz attempts to sequentially remove blocks of data
 with variable length and stepover; any deletion that doesn't affect the checksum
 of the trace map is committed to disk. The trimmer is not designed to be
 particularly thorough; instead, it tries to strike a balance between precision
-and the number of execve() calls spent on the process, selecting the block size
+and the number of `execve()` calls spent on the process, selecting the block size
 and stepover to match. The average per-file gains are around 5-20%.
 
-The standalone afl-tmin tool uses a more exhaustive, iterative algorithm, and
+The standalone `afl-tmin` tool uses a more exhaustive, iterative algorithm, and
 also attempts to perform alphabet normalization on the trimmed files. The
-operation of afl-tmin is as follows.
+operation of `afl-tmin` is as follows.
 
 First, the tool automatically selects the operating mode. If the initial input
 crashes the target binary, afl-tmin will run in non-instrumented mode, simply
-keeping any tweaks that produce a simpler file but still crash the target. If
-the target is non-crashing, the tool uses an instrumented mode and keeps only
+keeping any tweaks that produce a simpler file but still crash the target.
+The same mode is used for hangs, if `-H` (hang mode) is specified.
+If the target is non-crashing, the tool uses an instrumented mode and keeps only
 the tweaks that produce exactly the same execution path.
 
 The actual minimization algorithm is:
@@ -293,16 +296,13 @@ The actual minimization algorithm is:
   1) Attempt to zero large blocks of data with large stepovers. Empirically,
      this is shown to reduce the number of execs by preempting finer-grained
      efforts later on.
-
   2) Perform a block deletion pass with decreasing block sizes and stepovers,
      binary-search-style. 
-
   3) Perform alphabet normalization by counting unique characters and trying
      to bulk-replace each with a zero value.
-
   4) As a last result, perform byte-by-byte normalization on non-zero bytes.
 
-Instead of zeroing with a 0x00 byte, afl-tmin uses the ASCII digit '0'. This
+Instead of zeroing with a 0x00 byte, `afl-tmin` uses the ASCII digit '0'. This
 is done because such a modification is much less likely to interfere with
 text parsing, so it is more likely to result in successful minimization of
 text files.
@@ -312,8 +312,7 @@ minimization approaches proposed in academic work, but requires far fewer
 executions and tends to produce comparable results in most real-world
 applications.
 
-6) Fuzzing strategies
----------------------
+## 6. Fuzzing strategies
 
 The feedback provided by the instrumentation makes it easy to understand the
 value of various fuzzing strategies and optimize their parameters so that they
@@ -323,15 +322,13 @@ afl-fuzz are generally format-agnostic and are discussed in more detail here:
   http://lcamtuf.blogspot.com/2014/08/binary-fuzzing-strategies-what-works.html
 
 It is somewhat notable that especially early on, most of the work done by
-afl-fuzz is actually highly deterministic, and progresses to random stacked
+`afl-fuzz` is actually highly deterministic, and progresses to random stacked
 modifications and test case splicing only at a later stage. The deterministic
 strategies include:
 
   - Sequential bit flips with varying lengths and stepovers,
-
   - Sequential addition and subtraction of small integers,
-
-  - Sequential insertion of known interesting integers (0, 1, INT_MAX, etc),
+  - Sequential insertion of known interesting integers (`0`, `1`, `INT_MAX`, etc),
 
 The purpose of opening with deterministic steps is related to their tendency to
 produce compact test cases and small diffs between the non-crashing and crashing
@@ -341,10 +338,10 @@ With deterministic fuzzing out of the way, the non-deterministic steps include
 stacked bit flips, insertions, deletions, arithmetics, and splicing of different
 test cases.
 
-The relative yields and execve() costs of all these strategies have been
+The relative yields and `execve()` costs of all these strategies have been
 investigated and are discussed in the aforementioned blog post.
 
-For the reasons discussed in historical_notes.txt (chiefly, performance,
+For the reasons discussed in historical_notes.md (chiefly, performance,
 simplicity, and reliability), AFL generally does not try to reason about the
 relationship between specific mutations and program states; the fuzzing steps
 are nominally blind, and are guided only by the evolutionary design of the
@@ -365,8 +362,7 @@ in force only during deterministic stages that do not alter the size or the
 general layout of the underlying file, this mechanism appears to work very
 reliably and proved to be simple to implement.
 
-7) Dictionaries
----------------
+## 7. Dictionaries
 
 The feedback provided by the instrumentation makes it easy to automatically
 identify syntax tokens in some types of input files, and to detect that certain
@@ -398,31 +394,28 @@ to a predefined value baked into the code. The fuzzer relies on this signal
 to build compact "auto dictionaries" that are then used in conjunction with
 other fuzzing strategies.
 
-8) De-duping crashes
---------------------
+## 8. De-duping crashes
 
 De-duplication of crashes is one of the more important problems for any
 competent fuzzing tool. Many of the naive approaches run into problems; in
 particular, looking just at the faulting address may lead to completely
 unrelated issues being clustered together if the fault happens in a common
-library function (say, strcmp, strcpy); while checksumming call stack
+library function (say, `strcmp`, `strcpy`); while checksumming call stack
 backtraces can lead to extreme crash count inflation if the fault can be
 reached through a number of different, possibly recursive code paths.
 
-The solution implemented in afl-fuzz considers a crash unique if any of two
+The solution implemented in `afl-fuzz` considers a crash unique if any of two
 conditions are met:
 
   - The crash trace includes a tuple not seen in any of the previous crashes,
-
   - The crash trace is missing a tuple that was always present in earlier
     faults.
 
 The approach is vulnerable to some path count inflation early on, but exhibits
 a very strong self-limiting effect, similar to the execution path analysis
-logic that is the cornerstone of afl-fuzz.
+logic that is the cornerstone of `afl-fuzz`.
 
-9) Investigating crashes
-------------------------
+## 9. Investigating crashes
 
 The exploitability of many types of crashes can be ambiguous; afl-fuzz tries
 to address this by providing a crash exploration mode where a known-faulting
@@ -441,13 +434,12 @@ newly-found inputs for human review.
 On the subject of crashes, it is worth noting that in contrast to normal
 queue entries, crashing inputs are *not* trimmed; they are kept exactly as
 discovered to make it easier to compare them to the parent, non-crashing entry
-in the queue. That said, afl-tmin can be used to shrink them at will.
+in the queue. That said, `afl-tmin` can be used to shrink them at will.
 
-10) The fork server
--------------------
+## 10 The fork server
 
-To improve performance, afl-fuzz uses a "fork server", where the fuzzed process
-goes through execve(), linking, and libc initialization only once, and is then
+To improve performance, `afl-fuzz` uses a "fork server", where the fuzzed process
+goes through `execve()`, linking, and libc initialization only once, and is then
 cloned from a stopped process image by leveraging copy-on-write. The
 implementation is described in more detail here:
 
@@ -455,7 +447,7 @@ implementation is described in more detail here:
 
 The fork server is an integral aspect of the injected instrumentation and
 simply stops at the first instrumented function to await commands from
-afl-fuzz.
+`afl-fuzz`.
 
 With fast targets, the fork server can offer considerable performance gains,
 usually between 1.5x and 2x. It is also possible to:
@@ -464,17 +456,14 @@ usually between 1.5x and 2x. It is also possible to:
     user-selected chunks of initialization code. It requires very modest
     code changes to the targeted program, and With some targets, can
     produce 10x+ performance gains.
-
   - Enable "persistent" mode, where a single process is used to try out
-    multiple inputs, greatly limiting the overhead of repetitive fork()
+    multiple inputs, greatly limiting the overhead of repetitive `fork()`
     calls. This generally requires some code changes to the targeted program,
-    but can improve the performance of fast targets by a factor of 5 or more
-    - approximating the benefits of in-process fuzzing jobs while still
+    but can improve the performance of fast targets by a factor of 5 or more - approximating the benefits of in-process fuzzing jobs while still
     maintaining very robust isolation between the fuzzer process and the
     targeted binary.
 
-11) Parallelization
--------------------
+## 11. Parallelization
 
 The parallelization mechanism relies on periodically examining the queues
 produced by independently-running instances on other CPU cores or on remote
@@ -485,10 +474,9 @@ This allows for extreme flexibility in fuzzer setup, including running synced
 instances against different parsers of a common data format, often with
 synergistic effects.
 
-For more information about this design, see parallel_fuzzing.txt.
+For more information about this design, see parallel_fuzzing.md.
 
-12) Binary-only instrumentation
--------------------------------
+## 12. Binary-only instrumentation
 
 Instrumentation of black-box, binary-only targets is accomplished with the
 help of a separately-built version of QEMU in "user emulation" mode. This also
@@ -497,6 +485,7 @@ allows the execution of cross-architecture code - say, ARM binaries on x86.
 QEMU uses basic blocks as translation units; the instrumentation is implemented
 on top of this and uses a model roughly analogous to the compile-time hooks:
 
+```c
   if (block_address > elf_text_start && block_address < elf_text_end) {
 
     cur_location = (block_address >> 4) ^ (block_address << 8);
@@ -504,6 +493,7 @@ on top of this and uses a model roughly analogous to the compile-time hooks:
     prev_location = cur_location >> 1;
 
   }
+```
 
 The shift-and-XOR-based scrambling in the second line is used to mask the
 effects of instruction alignment.
@@ -511,7 +501,7 @@ effects of instruction alignment.
 The start-up of binary translators such as QEMU, DynamoRIO, and PIN is fairly
 slow; to counter this, the QEMU mode leverages a fork server similar to that
 used for compiler-instrumented code, effectively spawning copies of an
-already-initialized process paused at _start.
+already-initialized process paused at `_start`.
 
 First-time translation of a new basic block also incurs substantial latency. To
 eliminate this problem, the AFL fork server is extended by providing a channel
@@ -523,8 +513,7 @@ processes.
 As a result of these two optimizations, the overhead of the QEMU mode is
 roughly 2-5x, compared to 100x+ for PIN.
 
-13) The afl-analyze tool
-------------------------
+## 13. The `afl-analyze` tool
 
 The file format analyzer is a simple extension of the minimization algorithm
 discussed earlier on; instead of attempting to remove no-op blocks, the tool
@@ -536,28 +525,22 @@ It uses the following classification scheme:
   - "No-op blocks" - segments where bit flips cause no apparent changes to
     control flow. Common examples may be comment sections, pixel data within
     a bitmap file, etc.
-
   - "Superficial content" - segments where some, but not all, bitflips
     produce some control flow changes. Examples may include strings in rich
     documents (e.g., XML, RTF).
-
   - "Critical stream" - a sequence of bytes where all bit flips alter control
     flow in different but correlated ways. This may be compressed data, 
     non-atomically compared keywords or magic values, etc.
-
   - "Suspected length field" - small, atomic integer that, when touched in
     any way, causes a consistent change to program control flow, suggestive
     of a failed length check.
-
   - "Suspected cksum or magic int" - an integer that behaves similarly to a
     length field, but has a numerical value that makes the length explanation
     unlikely. This is suggestive of a checksum or other "magic" integer.
-
   - "Suspected checksummed block" - a long block of data where any change 
     always triggers the same new execution path. Likely caused by failing
     a checksum or a similar integrity check before any subsequent parsing
     takes place.
-
   - "Magic value section" - a generic token where changes cause the type
     of binary behavior outlined earlier, but that doesn't meet any of the
     other criteria. May be an atomically compared keyword or so.

docs/unicorn_mode.txt

@@ -1,107 +0,0 @@
-=========================================================
-Unicorn-based binary-only instrumentation for afl-fuzz
-=========================================================
-
-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?
-
-The idea and much of the implementation comes from Nathan Voss <njvoss299@gmail.com>.
-
-2) How to use
--------------
-
-*** 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 downloads a recent Unicorn Engine commit that has been tested 
-and is stable-ish from the Unicorn github page. If you are offline, you'll need 
-to hack up this script a little bit and supply your own copy of Unicorn's latest 
-stable release. It's not very hard, just check out the beginning of the 
-build_unicorn_support.sh script and adjust as necessary.
-
-Building Unicorn will take a little bit (~5-10 minutes). Once it completes 
-it automatically compiles a sample application and verify 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
-	* Unicorn-based test harness which:
-		- Adds memory map regions
-		- Loads binary code into memory		
-		- Emulates at least one instruction*
-			- Yeah, this is lame. See 'Gotchas' section below for more info		
-		- 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
-
-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
-
-3) Gotchas, feedback, bugs
---------------------------
-
-To make sure that AFL's fork server starts up correctly the Unicorn test 
-harness script must emulate at least one instruction before loading the
-data that will be fuzzed from the input file. It doesn't matter what the
-instruction is, nor if it is valid. This is an artifact of how the fork-server
-is started and could likely be fixed with some clever re-arranging of the
-patches applied to Unicorn.
-
-Running the build script builds Unicorn and its python bindings and installs 
-them on your system. This installation will supersede any existing Unicorn
-installation with the patched afl-unicorn version.
-
-Refer to the unicorn_mode/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!

examples/README.md

@@ -1,5 +1,9 @@
+# AFL++ Examples
+
 Here's a quick overview of the stuff you can find in this directory:
 
+  - custom_mutators      - example custom mutators in python an c
+
   - argv_fuzzing         - a simple wrapper to allow cmdline to be fuzzed
                            (e.g., to test setuid programs).
 
@@ -9,8 +13,8 @@ Here's a quick overview of the stuff you can find in this directory:
   - bash_shellshock      - a simple hack used to find a bunch of
                            post-Shellshock bugs in bash.
 
-  - canvas_harness       - a test harness used to find browser bugs with a 
-                           corpus generated using simple image parsing 
+  - canvas_harness       - a test harness used to find browser bugs with a
+                           corpus generated using simple image parsing
                            binaries & afl-fuzz.
 
   - clang_asm_normalize  - a script that makes it easy to instrument
@@ -20,7 +24,7 @@ Here's a quick overview of the stuff you can find in this directory:
                            with additional gdb metadata.
 
   - distributed_fuzzing  - a sample script for synchronizing fuzzer instances
-                           across multiple machines (see parallel_fuzzing.txt).
+                           across multiple machines (see parallel_fuzzing.md).
 
   - libpng_no_checksum   - a sample patch for removing CRC checks in libpng.
 
@@ -29,7 +33,10 @@ Here's a quick overview of the stuff you can find in this directory:
 
   - post_library         - an example of how to build postprocessors for AFL.
 
-Note that the minimize_corpus.sh tool has graduated from the experimental/
+  - socket_fuzzing       - a LD_PRELOAD library 'redirects' a socket to stdin
+                           for fuzzing access with afl++
+
+Note that the minimize_corpus.sh tool has graduated from the examples/
 directory and is now available as ../afl-cmin. The LLVM mode has likewise
 graduated to ../llvm_mode/*.
 

examples/afl_network_proxy/GNUmakefile

@@ -0,0 +1,43 @@
+PREFIX   ?= /usr/local
+BIN_PATH  = $(PREFIX)/bin
+DOC_PATH  = $(PREFIX)/share/doc/afl
+
+PROGRAMS = afl-network-client afl-network-server
+
+HASH=\#
+
+CFLAGS += -Wno-pointer-sign
+
+ifdef STATIC
+  CFLAGS += -static
+endif
+
+ifeq "$(shell echo '$(HASH)include <libdeflate.h>@int main() { struct libdeflate_compressor *d = libdeflate_alloc_compressor(1); return 0;}' | tr @ '\n' | $(CC) $(CFLAGS) -x c - -o .test2 -ldeflate 2>/dev/null && echo 1 || echo 0 ; rm -f .test2 )" "1"
+ CFLAGS += -DUSE_DEFLATE=1
+ LDFLAGS += -ldeflate 
+ $(info libdeflate-dev was detected, using compression)
+else
+ $(warn did not find libdeflate-dev, cannot use compression)
+endif
+
+all:	$(PROGRAMS)
+
+help:
+	@echo make options:
+	@echo STATIC - build as static binaries
+	@echo COMPRESS_TESTCASES - compress test cases
+
+afl-network-client:	afl-network-client.c
+	$(CC) $(CFLAGS) -I../../include -o afl-network-client afl-network-client.c $(LDFLAGS)
+
+afl-network-server:	afl-network-server.c
+	$(CC) $(CFLAGS) -I../../include -o afl-network-server afl-network-server.c ../../src/afl-forkserver.c ../../src/afl-sharedmem.c ../../src/afl-common.c -DBIN_PATH=\"$(BIN_PATH)\" $(LDFLAGS)
+
+clean:
+	rm -f $(PROGRAMS) *~ core
+
+install: all
+	install -d -m 755 $${DESTDIR}$(BIN_PATH) $${DESTDIR}$(DOC_PATH)
+	install -m 755 $(PROGRAMS) $${DESTDIR}$(BIN_PATH)
+	install -T -m 644 README.md $${DESTDIR}$(DOC_PATH)/README.network_proxy.md
+

examples/afl_network_proxy/Makefile

@@ -0,0 +1,2 @@
+all:
+	@echo please use GNU make, thanks!

examples/afl_network_proxy/README.md

@@ -0,0 +1,61 @@
+# afl-network-proxy
+
+If you want to run afl-fuzz over the network than this is what you need :)
+Note that the impact on fuzzing speed will be huge, expect a loss of 90%.
+
+## When to use this
+
+1. when you have to fuzz a target that has to run on a system that cannot
+   contain the fuzzing output (e.g. /tmp too small and file system is read-only)
+2. when the target instantly reboots on crashes
+3. ... any other reason you would need this
+
+## how to get it running
+
+### Compiling
+
+Just type `make` and let the autodetection do everything for you.
+
+Note that you will get a 40-50% performance increase if you have libdeflate-dev
+installed. The GNUmakefile will autodetect it if present.
+
+If your target has large test cases (10+kb) that are ascii only or large chunks
+of zero blocks then set `CFLAGS=-DCOMPRESS_TESTCASES=1` to compress them.
+For most targets this hurts performance though so it is disabled by default.
+
+### on the target
+
+Run `afl-network-server` with your target with the -m and -t values you need.
+Important is the -i parameter which is the TCP port to listen on.
+e.g.:
+```
+$ afl-network-server -i 1111 -m 25M -t 1000 -- /bin/target -f @@
+```
+
+### on the (afl-fuzz) master
+
+Just run afl-fuzz with your normal options, however the target should be
+`afl-network-client` with the IP and PORT of the `afl-network-server` and
+increase the -t value:
+```
+$ afl-fuzz -i in -o out -t 2000+ -- afl-network-client TARGET-IP 1111
+```
+Note the '+' on the -t parameter value. The afl-network-server will take
+care of proper timeouts hence afl-fuzz should not. The '+' increases the
+timeout and the value itself should be 500-1000 higher than the one on 
+afl-network-server.
+
+### networking
+
+The TARGET can be an IPv4 or IPv6 address, or a host name that resolves to
+either. Note that also the outgoing interface can be specified with a '%' for
+`afl-network-client`, e.g. `fe80::1234%eth0`.
+
+Also make sure your default TCP window size is larger than your MAP_SIZE
+(130kb is a good value).
+On Linux that is the middle value of `/proc/sys/net/ipv4/tcp_rmem` 
+
+## how to compile and install
+
+`make && sudo make install`
+

examples/afl_network_proxy/afl-network-client.c

@@ -0,0 +1,413 @@
+/*
+   american fuzzy lop++ - afl-network-client
+   ---------------------------------------
+
+   Written by Marc Heuse <mh@mh-sec.de>
+
+   Copyright 2019-2020 AFLplusplus Project. All rights reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at:
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+*/
+
+#ifdef __ANDROID__
+  #include "android-ashmem.h"
+#endif
+#include "config.h"
+#include "types.h"
+#include "debug.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <signal.h>
+#include <unistd.h>
+#include <string.h>
+#include <assert.h>
+#include <stdint.h>
+#include <errno.h>
+
+#include <netinet/in.h>
+#include <netinet/ip6.h>
+#include <arpa/inet.h>
+#include <sys/mman.h>
+#include <sys/shm.h>
+#include <sys/wait.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <netdb.h>
+#include <fcntl.h>
+
+#ifdef USE_DEFLATE
+  #include <libdeflate.h>
+#endif
+
+u8 *__afl_area_ptr;
+
+#ifdef __ANDROID__
+u32 __afl_map_size = MAP_SIZE;
+#else
+__thread u32 __afl_map_size = MAP_SIZE;
+#endif
+
+/* Error reporting to forkserver controller */
+
+void send_forkserver_error(int error) {
+
+  u32 status;
+  if (!error || error > 0xffff) return;
+  status = (FS_OPT_ERROR | FS_OPT_SET_ERROR(error));
+  if (write(FORKSRV_FD + 1, (char *)&status, 4) != 4) return;
+
+}
+
+/* SHM setup. */
+
+static void __afl_map_shm(void) {
+
+  char *id_str = getenv(SHM_ENV_VAR);
+  char *ptr;
+
+  if ((ptr = getenv("AFL_MAP_SIZE")) != NULL) {
+
+    u32 val = atoi(ptr);
+    if (val > 0) __afl_map_size = val;
+
+  }
+
+  if (__afl_map_size > MAP_SIZE) {
+
+    if (__afl_map_size > FS_OPT_MAX_MAPSIZE) {
+
+      fprintf(stderr,
+              "Error: AFL++ tools *require* to set AFL_MAP_SIZE to %u to "
+              "be able to run this instrumented program!\n",
+              __afl_map_size);
+      if (id_str) {
+
+        send_forkserver_error(FS_ERROR_MAP_SIZE);
+        exit(-1);
+
+      }
+
+    } else {
+
+      fprintf(stderr,
+              "Warning: AFL++ tools will need to set AFL_MAP_SIZE to %u to "
+              "be able to run this instrumented program!\n",
+              __afl_map_size);
+
+    }
+
+  }
+
+  if (id_str) {
+
+#ifdef USEMMAP
+    const char *   shm_file_path = id_str;
+    int            shm_fd = -1;
+    unsigned char *shm_base = NULL;
+
+    /* create the shared memory segment as if it was a file */
+    shm_fd = shm_open(shm_file_path, O_RDWR, 0600);
+    if (shm_fd == -1) {
+
+      fprintf(stderr, "shm_open() failed\n");
+      send_forkserver_error(FS_ERROR_SHM_OPEN);
+      exit(1);
+
+    }
+
+    /* map the shared memory segment to the address space of the process */
+    shm_base =
+        mmap(0, __afl_map_size, PROT_READ | PROT_WRITE, MAP_SHARED, shm_fd, 0);
+
+    if (shm_base == MAP_FAILED) {
+
+      close(shm_fd);
+      shm_fd = -1;
+
+      fprintf(stderr, "mmap() failed\n");
+      send_forkserver_error(FS_ERROR_MMAP);
+      exit(2);
+
+    }
+
+    __afl_area_ptr = shm_base;
+#else
+    u32 shm_id = atoi(id_str);
+
+    __afl_area_ptr = shmat(shm_id, 0, 0);
+
+#endif
+
+    if (__afl_area_ptr == (void *)-1) {
+
+      send_forkserver_error(FS_ERROR_SHMAT);
+      exit(1);
+
+    }
+
+    /* Write something into the bitmap so that the parent doesn't give up */
+
+    __afl_area_ptr[0] = 1;
+
+  }
+
+}
+
+/* Fork server logic. */
+
+static void __afl_start_forkserver(void) {
+
+  u8  tmp[4] = {0, 0, 0, 0};
+  u32 status = 0;
+
+  if (__afl_map_size <= FS_OPT_MAX_MAPSIZE)
+    status |= (FS_OPT_SET_MAPSIZE(__afl_map_size) | FS_OPT_MAPSIZE);
+  if (status) status |= (FS_OPT_ENABLED);
+  memcpy(tmp, &status, 4);
+
+  /* Phone home and tell the parent that we're OK. */
+
+  if (write(FORKSRV_FD + 1, tmp, 4) != 4) return;
+
+}
+
+static u32 __afl_next_testcase(u8 *buf, u32 max_len) {
+
+  s32 status, res = 0x0fffffff;  // res is a dummy pid
+
+  /* Wait for parent by reading from the pipe. Abort if read fails. */
+  if (read(FORKSRV_FD, &status, 4) != 4) return 0;
+
+  /* we have a testcase - read it */
+  status = read(0, buf, max_len);
+
+  /* report that we are starting the target */
+  if (write(FORKSRV_FD + 1, &res, 4) != 4) return 0;
+
+  if (status < 1)
+    return 0;
+  else
+    return status;
+
+}
+
+static void __afl_end_testcase(int status) {
+
+  if (write(FORKSRV_FD + 1, &status, 4) != 4) exit(1);
+
+}
+
+/* you just need to modify the while() loop in this main() */
+
+int main(int argc, char *argv[]) {
+
+  u8 *            interface, *buf, *ptr;
+  s32             s = -1;
+  struct addrinfo hints, *hres, *aip;
+  u32 *           lenptr, max_len = 65536;
+#ifdef USE_DEFLATE
+  u8 *   buf2;
+  u32 *  lenptr1, *lenptr2, buf2_len, compress_len;
+  size_t decompress_len;
+#endif
+
+  if (argc < 3 || argc > 4) {
+
+    printf("Syntax: %s host port [max-input-size]\n\n", argv[0]);
+    printf("Requires host and port of the remote afl-proxy-server instance.\n");
+    printf(
+        "IPv4 and IPv6 are supported, also binding to an interface with "
+        "\"%%\"\n");
+    printf("The max-input-size default is %u.\n", max_len);
+    printf(
+        "The default map size is %u and can be changed with setting "
+        "AFL_MAP_SIZE.\n",
+        __afl_map_size);
+    exit(-1);
+
+  }
+
+  if ((interface = index(argv[1], '%')) != NULL) *interface++ = 0;
+
+  if (argc > 3)
+    if ((max_len = atoi(argv[3])) < 0)
+      FATAL("max-input-size may not be negative or larger than 2GB: %s",
+            argv[3]);
+
+  if ((ptr = getenv("AFL_MAP_SIZE")) != NULL)
+    if ((__afl_map_size = atoi(ptr)) < 8)
+      FATAL("illegal map size, may not be < 8 or >= 2^30: %s", ptr);
+
+  if ((buf = malloc(max_len + 4)) == NULL)
+    PFATAL("can not allocate %u memory", max_len + 4);
+  lenptr = (u32 *)buf;
+
+#ifdef USE_DEFLATE
+  buf2_len = (max_len > __afl_map_size ? max_len : __afl_map_size);
+  if ((buf2 = malloc(buf2_len + 8)) == NULL)
+    PFATAL("can not allocate %u memory", buf2_len + 8);
+  lenptr1 = (u32 *)buf2;
+  lenptr2 = (u32 *)(buf2 + 4);
+#endif
+
+  memset(&hints, 0, sizeof(hints));
+  hints.ai_socktype = SOCK_STREAM;
+  hints.ai_family = PF_UNSPEC;
+
+  if (getaddrinfo(argv[1], argv[2], &hints, &hres) != 0)
+    PFATAL("could not resolve target %s", argv[1]);
+
+  for (aip = hres; aip != NULL && s == -1; aip = aip->ai_next) {
+
+    if ((s = socket(aip->ai_family, aip->ai_socktype, aip->ai_protocol)) >= 0) {
+
+#ifdef SO_BINDTODEVICE
+      if (interface != NULL)
+        if (setsockopt(s, SOL_SOCKET, SO_BINDTODEVICE, interface,
+                       strlen(interface) + 1) < 0)
+          fprintf(stderr, "Warning: could not bind to device %s\n", interface);
+#else
+      fprintf(stderr,
+              "Warning: binding to interface is not supported for your OS\n");
+#endif
+
+#ifdef SO_PRIORITY
+      int priority = 7;
+      if (setsockopt(s, SOL_SOCKET, SO_PRIORITY, &priority, sizeof(priority)) <
+          0) {
+
+        priority = 6;
+        if (setsockopt(s, SOL_SOCKET, SO_PRIORITY, &priority,
+                       sizeof(priority)) < 0)
+          WARNF("could not set priority on socket");
+
+      }
+
+#endif
+
+      if (connect(s, aip->ai_addr, aip->ai_addrlen) == -1) s = -1;
+
+    }
+
+  }
+
+#ifdef USE_DEFLATE
+  struct libdeflate_compressor *compressor;
+  compressor = libdeflate_alloc_compressor(1);
+  struct libdeflate_decompressor *decompressor;
+  decompressor = libdeflate_alloc_decompressor();
+  fprintf(stderr, "Compiled with compression support\n");
+#endif
+
+  if (s == -1)
+    FATAL("could not connect to target tcp://%s:%s", argv[1], argv[2]);
+  else
+    fprintf(stderr, "Connected to target tcp://%s:%s\n", argv[1], argv[2]);
+
+  /* we initialize the shared memory map and start the forkserver */
+  __afl_map_shm();
+  __afl_start_forkserver();
+
+  int i = 1, j, status, ret, received;
+
+  // fprintf(stderr, "Waiting for first testcase\n");
+  while ((*lenptr = __afl_next_testcase(buf + 4, max_len)) > 0) {
+
+    // fprintf(stderr, "Sending testcase with len %u\n", *lenptr);
+#ifdef USE_DEFLATE
+  #ifdef COMPRESS_TESTCASES
+    // we only compress the testcase if it does not fit in the TCP packet
+    if (*lenptr > 1500 - 20 - 32 - 4) {
+
+      // set highest byte to signify compression
+      *lenptr1 = (*lenptr | 0xff000000);
+      *lenptr2 = (u32)libdeflate_deflate_compress(compressor, buf + 4, *lenptr,
+                                                  buf2 + 8, buf2_len);
+      if (send(s, buf2, *lenptr2 + 8, 0) != *lenptr2 + 8)
+        PFATAL("sending test data failed");
+      // fprintf(stderr, "COMPRESS (%u->%u):\n", *lenptr, *lenptr2);
+      // for (u32 i = 0; i < *lenptr; i++)
+      //  fprintf(stderr, "%02x", buf[i + 4]);
+      // fprintf(stderr, "\n");
+      // for (u32 i = 0; i < *lenptr2; i++)
+      //  fprintf(stderr, "%02x", buf2[i + 8]);
+      // fprintf(stderr, "\n");
+
+    } else {
+
+  #endif
+#endif
+      if (send(s, buf, *lenptr + 4, 0) != *lenptr + 4)
+        PFATAL("sending test data failed");
+#ifdef USE_DEFLATE
+  #ifdef COMPRESS_TESTCASES
+      // fprintf(stderr, "unCOMPRESS (%u)\n", *lenptr);
+
+    }
+
+  #endif
+#endif
+
+    received = 0;
+    while (received < 4 &&
+           (ret = recv(s, &status + received, 4 - received, 0)) > 0)
+      received += ret;
+    if (received != 4)
+      FATAL("did not receive waitpid data (%d, %d)", received, ret);
+    // fprintf(stderr, "Received status\n");
+
+    received = 0;
+#ifdef USE_DEFLATE
+    while (received < 4 &&
+           (ret = recv(s, &compress_len + received, 4 - received, 0)) > 0)
+      received += ret;
+    if (received != 4)
+      FATAL("did not receive compress_len (%d, %d)", received, ret);
+    // fprintf(stderr, "Received status\n");
+
+    received = 0;
+    while (received < compress_len &&
+           (ret = recv(s, buf2 + received, buf2_len - received, 0)) > 0)
+      received += ret;
+    if (received != compress_len)
+      FATAL("did not receive coverage data (%d, %d)", received, ret);
+
+    if (libdeflate_deflate_decompress(decompressor, buf2, compress_len,
+                                      __afl_area_ptr, __afl_map_size,
+                                      &decompress_len) != LIBDEFLATE_SUCCESS ||
+        decompress_len != __afl_map_size)
+      FATAL("decompression failed");
+      // fprintf(stderr, "DECOMPRESS (%u->%u): ", compress_len, decompress_len);
+      // for (u32 i = 0; i < __afl_map_size; i++) fprintf(stderr, "%02x",
+      // __afl_area_ptr[i]); fprintf(stderr, "\n");
+#else
+    while (received < __afl_map_size &&
+           (ret = recv(s, __afl_area_ptr + received, __afl_map_size - received,
+                       0)) > 0)
+      received += ret;
+    if (received != __afl_map_size)
+      FATAL("did not receive coverage data (%d, %d)", received, ret);
+#endif
+    // fprintf(stderr, "Received coverage\n");
+
+    /* report the test case is done and wait for the next */
+    __afl_end_testcase(status);
+    // fprintf(stderr, "Waiting for next testcase %d\n", ++i);
+
+  }
+
+#ifdef USE_DEFLATE
+  libdeflate_free_compressor(compressor);
+  libdeflate_free_decompressor(decompressor);
+#endif
+
+  return 0;
+
+}
+

examples/afl_network_proxy/afl-network-server.c

@@ -0,0 +1,712 @@
+/*
+   american fuzzy lop++ - network proxy server
+   -------------------------------------------
+
+   Originally written by Michal Zalewski
+
+   Forkserver design by Jann Horn <jannhorn@googlemail.com>
+
+   Now maintained by Marc Heuse <mh@mh-sec.de>,
+                        Heiko Eißfeldt <heiko.eissfeldt@hexco.de> and
+                        Andrea Fioraldi <andreafioraldi@gmail.com> and
+                        Dominik Maier <mail@dmnk.co>
+
+   Copyright 2016, 2017 Google Inc. All rights reserved.
+   Copyright 2019-2020 AFLplusplus Project. All rights reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at:
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ */
+
+#define AFL_MAIN
+
+#ifdef __ANDROID__
+  #include "android-ashmem.h"
+#endif
+
+#include "config.h"
+#include "types.h"
+#include "debug.h"
+#include "alloc-inl.h"
+#include "hash.h"
+#include "forkserver.h"
+#include "sharedmem.h"
+#include "common.h"
+
+#include <stdio.h>
+#include <unistd.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <errno.h>
+#include <signal.h>
+#include <dirent.h>
+#include <fcntl.h>
+
+#include <sys/wait.h>
+#include <sys/time.h>
+#include <sys/shm.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <sys/resource.h>
+#include <netinet/in.h>
+#include <netinet/ip6.h>
+#include <arpa/inet.h>
+#include <sys/mman.h>
+#include <sys/shm.h>
+#include <sys/socket.h>
+#include <netdb.h>
+
+#ifdef USE_DEFLATE
+  #include <libdeflate.h>
+struct libdeflate_compressor *  compressor;
+struct libdeflate_decompressor *decompressor;
+#endif
+
+static u8 *in_file,                    /* Minimizer input test case         */
+    *out_file;
+
+static u8 *in_data;                    /* Input data for trimming           */
+static u8 *buf2;
+
+static s32    in_len;
+static u32    map_size = MAP_SIZE;
+static size_t buf2_len;
+
+static volatile u8 stop_soon;          /* Ctrl-C pressed?                   */
+
+/* See if any bytes are set in the bitmap. */
+
+static inline u8 anything_set(afl_forkserver_t *fsrv) {
+
+  u32 *ptr = (u32 *)fsrv->trace_bits;
+  u32  i = (map_size >> 2);
+
+  while (i--) {
+
+    if (*(ptr++)) { return 1; }
+
+  }
+
+  return 0;
+
+}
+
+static void at_exit_handler(void) {
+
+  afl_fsrv_killall();
+
+}
+
+/* Write output file. */
+
+static s32 write_to_file(u8 *path, u8 *mem, u32 len) {
+
+  s32 ret;
+
+  unlink(path);                                            /* Ignore errors */
+
+  ret = open(path, O_RDWR | O_CREAT | O_EXCL, 0600);
+
+  if (ret < 0) { PFATAL("Unable to create '%s'", path); }
+
+  ck_write(ret, mem, len, path);
+
+  lseek(ret, 0, SEEK_SET);
+
+  return ret;
+
+}
+
+/* Execute target application. Returns 0 if the changes are a dud, or
+   1 if they should be kept. */
+
+static u8 run_target(afl_forkserver_t *fsrv, char **argv, u8 *mem, u32 len,
+                     u8 first_run) {
+
+  afl_fsrv_write_to_testcase(fsrv, mem, len);
+
+  fsrv_run_result_t ret =
+      afl_fsrv_run_target(fsrv, fsrv->exec_tmout, &stop_soon);
+
+  if (ret == FSRV_RUN_ERROR) { FATAL("Couldn't run child"); }
+
+  if (stop_soon) {
+
+    SAYF(cRST cLRD "\n+++ aborted by user +++\n" cRST);
+    exit(1);
+
+  }
+
+  return ret;
+
+}
+
+/* Handle Ctrl-C and the like. */
+
+static void handle_stop_sig(int sig) {
+
+  stop_soon = 1;
+  afl_fsrv_killall();
+
+}
+
+/* Do basic preparations - persistent fds, filenames, etc. */
+
+static void set_up_environment(afl_forkserver_t *fsrv) {
+
+  u8 *x;
+
+  fsrv->dev_null_fd = open("/dev/null", O_RDWR);
+  if (fsrv->dev_null_fd < 0) { PFATAL("Unable to open /dev/null"); }
+
+  if (!out_file) {
+
+    u8 *use_dir = ".";
+
+    if (access(use_dir, R_OK | W_OK | X_OK)) {
+
+      use_dir = get_afl_env("TMPDIR");
+      if (!use_dir) { use_dir = "/tmp"; }
+
+    }
+
+    out_file = alloc_printf("%s/.afl-input-temp-%u", use_dir, getpid());
+
+  }
+
+  unlink(out_file);
+
+  fsrv->out_fd = open(out_file, O_RDWR | O_CREAT | O_EXCL, 0600);
+
+  if (fsrv->out_fd < 0) { PFATAL("Unable to create '%s'", out_file); }
+
+  /* Set sane defaults... */
+
+  x = get_afl_env("ASAN_OPTIONS");
+
+  if (x) {
+
+    if (!strstr(x, "abort_on_error=1")) {
+
+      FATAL("Custom ASAN_OPTIONS set without abort_on_error=1 - please fix!");
+
+    }
+
+    if (!strstr(x, "symbolize=0")) {
+
+      FATAL("Custom ASAN_OPTIONS set without symbolize=0 - please fix!");
+
+    }
+
+  }
+
+  x = get_afl_env("MSAN_OPTIONS");
+
+  if (x) {
+
+    if (!strstr(x, "exit_code=" STRINGIFY(MSAN_ERROR))) {
+
+      FATAL("Custom MSAN_OPTIONS set without exit_code=" STRINGIFY(
+          MSAN_ERROR) " - please fix!");
+
+    }
+
+    if (!strstr(x, "symbolize=0")) {
+
+      FATAL("Custom MSAN_OPTIONS set without symbolize=0 - please fix!");
+
+    }
+
+  }
+
+  setenv("ASAN_OPTIONS",
+         "abort_on_error=1:"
+         "detect_leaks=0:"
+         "symbolize=0:"
+         "allocator_may_return_null=1",
+         0);
+
+  setenv("MSAN_OPTIONS", "exit_code=" STRINGIFY(MSAN_ERROR) ":"
+                         "symbolize=0:"
+                         "abort_on_error=1:"
+                         "allocator_may_return_null=1:"
+                         "msan_track_origins=0", 0);
+
+  if (get_afl_env("AFL_PRELOAD")) {
+
+    if (fsrv->qemu_mode) {
+
+      u8 *qemu_preload = getenv("QEMU_SET_ENV");
+      u8 *afl_preload = getenv("AFL_PRELOAD");
+      u8 *buf;
+
+      s32 i, afl_preload_size = strlen(afl_preload);
+      for (i = 0; i < afl_preload_size; ++i) {
+
+        if (afl_preload[i] == ',') {
+
+          PFATAL(
+              "Comma (',') is not allowed in AFL_PRELOAD when -Q is "
+              "specified!");
+
+        }
+
+      }
+
+      if (qemu_preload) {
+
+        buf = alloc_printf("%s,LD_PRELOAD=%s,DYLD_INSERT_LIBRARIES=%s",
+                           qemu_preload, afl_preload, afl_preload);
+
+      } else {
+
+        buf = alloc_printf("LD_PRELOAD=%s,DYLD_INSERT_LIBRARIES=%s",
+                           afl_preload, afl_preload);
+
+      }
+
+      setenv("QEMU_SET_ENV", buf, 1);
+
+      ck_free(buf);
+
+    } else {
+
+      setenv("LD_PRELOAD", getenv("AFL_PRELOAD"), 1);
+      setenv("DYLD_INSERT_LIBRARIES", getenv("AFL_PRELOAD"), 1);
+
+    }
+
+  }
+
+}
+
+/* Setup signal handlers, duh. */
+
+static void setup_signal_handlers(void) {
+
+  struct sigaction sa;
+
+  sa.sa_handler = NULL;
+  sa.sa_flags = SA_RESTART;
+  sa.sa_sigaction = NULL;
+
+  sigemptyset(&sa.sa_mask);
+
+  /* Various ways of saying "stop". */
+
+  sa.sa_handler = handle_stop_sig;
+  sigaction(SIGHUP, &sa, NULL);
+  sigaction(SIGINT, &sa, NULL);
+  sigaction(SIGTERM, &sa, NULL);
+
+}
+
+/* Display usage hints. */
+
+static void usage(u8 *argv0) {
+
+  SAYF(
+      "\n%s [ options ] -- /path/to/target_app [ ... ]\n\n"
+
+      "Required parameters:\n"
+
+      "  -i port       - the port to listen for the client to connect to\n\n"
+
+      "Execution control settings:\n"
+
+      "  -f file       - input file read by the tested program (stdin)\n"
+      "  -t msec       - timeout for each run (%d ms)\n"
+      "  -m megs       - memory limit for child process (%d MB)\n"
+      "  -Q            - use binary-only instrumentation (QEMU mode)\n"
+      "  -U            - use unicorn-based instrumentation (Unicorn mode)\n"
+      "  -W            - use qemu-based instrumentation with Wine (Wine "
+      "mode)\n\n"
+
+      "Environment variables used:\n"
+      "TMPDIR: directory to use for temporary input files\n"
+      "ASAN_OPTIONS: custom settings for ASAN\n"
+      "              (must contain abort_on_error=1 and symbolize=0)\n"
+      "MSAN_OPTIONS: custom settings for MSAN\n"
+      "              (must contain exitcode="STRINGIFY(MSAN_ERROR)" and symbolize=0)\n"
+      "AFL_MAP_SIZE: the shared memory size for that target. must be >= the size\n"
+      "              the target was compiled for\n"
+      "AFL_PRELOAD:  LD_PRELOAD / DYLD_INSERT_LIBRARIES settings for target\n"
+
+      , argv0, EXEC_TIMEOUT, MEM_LIMIT);
+
+  exit(1);
+
+}
+
+int recv_testcase(int s, void **buf, size_t *max_len) {
+
+  u32    size;
+  s32    ret;
+  size_t received;
+
+  received = 0;
+  while (received < 4 && (ret = recv(s, &size + received, 4 - received, 0)) > 0)
+    received += ret;
+  if (received != 4) FATAL("did not receive size information");
+  if (size == 0) FATAL("did not receive valid size information");
+  // fprintf(stderr, "received size information of %d\n", size);
+
+  if ((size & 0xff000000) != 0xff000000) {
+
+    *buf = ck_maybe_grow(buf, max_len, size);
+    received = 0;
+    // fprintf(stderr, "unCOMPRESS (%u)\n", size);
+    while (received < size &&
+           (ret = recv(s, ((char *)*buf) + received, size - received, 0)) > 0)
+      received += ret;
+
+  } else {
+
+#ifdef USE_DEFLATE
+    u32 clen;
+    size -= 0xff000000;
+    *buf = ck_maybe_grow(buf, max_len, size);
+    received = 0;
+    while (received < 4 &&
+           (ret = recv(s, &clen + received, 4 - received, 0)) > 0)
+      received += ret;
+    if (received != 4) FATAL("did not receive clen1 information");
+    // fprintf(stderr, "received clen information of %d\n", clen);
+    if (clen < 1)
+      FATAL("did not receive valid compressed len information: %u", clen);
+    buf2 = ck_maybe_grow((void **)&buf2, &buf2_len, clen);
+    received = 0;
+    while (received < clen &&
+           (ret = recv(s, buf2 + received, clen - received, 0)) > 0)
+      received += ret;
+    if (received != clen) FATAL("did not receive compressed information");
+    if (libdeflate_deflate_decompress(decompressor, buf2, clen, (char *)*buf,
+                                      *max_len,
+                                      &received) != LIBDEFLATE_SUCCESS)
+      FATAL("decompression failed");
+      // fprintf(stderr, "DECOMPRESS (%u->%u):\n", clen, received);
+      // for (u32 i = 0; i < clen; i++) fprintf(stderr, "%02x", buf2[i]);
+      // fprintf(stderr, "\n");
+      // for (u32 i = 0; i < received; i++) fprintf(stderr, "%02x",
+      // ((u8*)(*buf))[i]); fprintf(stderr, "\n");
+#else
+    FATAL("Received compressed data but not compiled with compression support");
+#endif
+
+  }
+
+  // fprintf(stderr, "receiving testcase %p %p max %u\n", buf, *buf, *max_len);
+  if (received != size)
+    FATAL("did not receive testcase data %lu != %u, %d", received, size, ret);
+  // fprintf(stderr, "received testcase\n");
+  return size;
+
+}
+
+/* Main entry point */
+
+int main(int argc, char **argv_orig, char **envp) {
+
+  s32    opt, s, sock, on = 1, port = -1;
+  size_t max_len = 0;
+  u8     mem_limit_given = 0, timeout_given = 0, unicorn_mode = 0, use_wine = 0;
+  char **use_argv;
+  struct sockaddr_in6 serveraddr, clientaddr;
+  int                 addrlen = sizeof(clientaddr);
+  char                str[INET6_ADDRSTRLEN];
+  char **             argv = argv_cpy_dup(argc, argv_orig);
+  u8 *                send_buf;
+#ifdef USE_DEFLATE
+  u32 *lenptr;
+#endif
+
+  afl_forkserver_t  fsrv_var = {0};
+  afl_forkserver_t *fsrv = &fsrv_var;
+  afl_fsrv_init(fsrv);
+  map_size = get_map_size();
+  fsrv->map_size = map_size;
+
+  if ((send_buf = malloc(map_size + 4)) == NULL) PFATAL("malloc");
+
+  while ((opt = getopt(argc, argv, "+i:f:m:t:QUWh")) > 0) {
+
+    switch (opt) {
+
+      case 'i':
+
+        if (port > 0) { FATAL("Multiple -i options not supported"); }
+        port = atoi(optarg);
+        if (port < 1 || port > 65535)
+          FATAL("invalid port definition, must be between 1-65535: %s", optarg);
+        break;
+
+      case 'f':
+
+        if (out_file) { FATAL("Multiple -f options not supported"); }
+        fsrv->use_stdin = 0;
+        out_file = optarg;
+        break;
+
+      case 'm': {
+
+        u8 suffix = 'M';
+
+        if (mem_limit_given) { FATAL("Multiple -m options not supported"); }
+        mem_limit_given = 1;
+
+        if (!optarg) { FATAL("Wrong usage of -m"); }
+
+        if (!strcmp(optarg, "none")) {
+
+          fsrv->mem_limit = 0;
+          break;
+
+        }
+
+        if (sscanf(optarg, "%llu%c", &fsrv->mem_limit, &suffix) < 1 ||
+            optarg[0] == '-') {
+
+          FATAL("Bad syntax used for -m");
+
+        }
+
+        switch (suffix) {
+
+          case 'T':
+            fsrv->mem_limit *= 1024 * 1024;
+            break;
+          case 'G':
+            fsrv->mem_limit *= 1024;
+            break;
+          case 'k':
+            fsrv->mem_limit /= 1024;
+            break;
+          case 'M':
+            break;
+
+          default:
+            FATAL("Unsupported suffix or bad syntax for -m");
+
+        }
+
+        if (fsrv->mem_limit < 5) { FATAL("Dangerously low value of -m"); }
+
+        if (sizeof(rlim_t) == 4 && fsrv->mem_limit > 2000) {
+
+          FATAL("Value of -m out of range on 32-bit systems");
+
+        }
+
+      }
+
+      break;
+
+      case 't':
+
+        if (timeout_given) { FATAL("Multiple -t options not supported"); }
+        timeout_given = 1;
+
+        if (!optarg) { FATAL("Wrong usage of -t"); }
+
+        fsrv->exec_tmout = atoi(optarg);
+
+        if (fsrv->exec_tmout < 10 || optarg[0] == '-') {
+
+          FATAL("Dangerously low value of -t");
+
+        }
+
+        break;
+
+      case 'Q':
+
+        if (fsrv->qemu_mode) { FATAL("Multiple -Q options not supported"); }
+        if (!mem_limit_given) { fsrv->mem_limit = MEM_LIMIT_QEMU; }
+
+        fsrv->qemu_mode = 1;
+        break;
+
+      case 'U':
+
+        if (unicorn_mode) { FATAL("Multiple -Q options not supported"); }
+        if (!mem_limit_given) { fsrv->mem_limit = MEM_LIMIT_UNICORN; }
+
+        unicorn_mode = 1;
+        break;
+
+      case 'W':                                           /* Wine+QEMU mode */
+
+        if (use_wine) { FATAL("Multiple -W options not supported"); }
+        fsrv->qemu_mode = 1;
+        use_wine = 1;
+
+        if (!mem_limit_given) { fsrv->mem_limit = 0; }
+
+        break;
+
+      case 'h':
+        usage(argv[0]);
+        return -1;
+        break;
+
+      default:
+        usage(argv[0]);
+
+    }
+
+  }
+
+  if (optind == argc || port < 1) { usage(argv[0]); }
+
+  check_environment_vars(envp);
+
+  sharedmem_t shm = {0};
+  fsrv->trace_bits = afl_shm_init(&shm, map_size, 0);
+
+  in_data = ck_maybe_grow((void **)&in_data, &max_len, 65536);
+
+  atexit(at_exit_handler);
+  setup_signal_handlers();
+
+  set_up_environment(fsrv);
+
+  fsrv->target_path = find_binary(argv[optind]);
+  detect_file_args(argv + optind, out_file, &fsrv->use_stdin);
+
+  if (fsrv->qemu_mode) {
+
+    if (use_wine) {
+
+      use_argv = get_wine_argv(argv[0], &fsrv->target_path, argc - optind,
+                               argv + optind);
+
+    } else {
+
+      use_argv = get_qemu_argv(argv[0], &fsrv->target_path, argc - optind,
+                               argv + optind);
+
+    }
+
+  } else {
+
+    use_argv = argv + optind;
+
+  }
+
+  if ((sock = socket(AF_INET6, SOCK_STREAM, 0)) < 0) PFATAL("socket() failed");
+
+#ifdef SO_REUSEADDR
+  if (setsockopt(sock, SOL_SOCKET, SO_REUSEADDR, (char *)&on, sizeof(on)) < 0) {
+
+    WARNF("setsockopt(SO_REUSEADDR) failed");
+
+  }
+
+#endif
+
+#ifdef SO_PRIORITY
+  int priority = 7;
+  if (setsockopt(sock, SOL_SOCKET, SO_PRIORITY, &priority, sizeof(priority)) <
+      0) {
+
+    priority = 6;
+    if (setsockopt(sock, SOL_SOCKET, SO_PRIORITY, &priority, sizeof(priority)) <
+        0)
+      WARNF("could not set priority on socket");
+
+  }
+
+#endif
+
+  memset(&serveraddr, 0, sizeof(serveraddr));
+  serveraddr.sin6_family = AF_INET6;
+  serveraddr.sin6_port = htons(port);
+  serveraddr.sin6_addr = in6addr_any;
+
+  if (bind(sock, (struct sockaddr *)&serveraddr, sizeof(serveraddr)) < 0)
+    PFATAL("bind() failed");
+
+  if (listen(sock, 1) < 0) { PFATAL("listen() failed"); }
+
+  afl_fsrv_start(fsrv, use_argv, &stop_soon,
+                 get_afl_env("AFL_DEBUG_CHILD_OUTPUT") ? 1 : 0);
+
+#ifdef USE_DEFLATE
+  compressor = libdeflate_alloc_compressor(1);
+  decompressor = libdeflate_alloc_decompressor();
+  buf2 = ck_maybe_grow((void **)&buf2, &buf2_len, map_size + 16);
+  lenptr = (u32 *)(buf2 + 4);
+  fprintf(stderr, "Compiled with compression support\n");
+#endif
+
+  fprintf(stderr,
+          "Waiting for incoming connection from afl-network-client on port %d "
+          "...\n",
+          port);
+
+  if ((s = accept(sock, NULL, NULL)) < 0) { PFATAL("accept() failed"); }
+  fprintf(stderr, "Received connection, starting ...\n");
+
+#ifdef SO_PRIORITY
+  priority = 7;
+  if (setsockopt(s, SOL_SOCKET, SO_PRIORITY, &priority, sizeof(priority)) < 0) {
+
+    priority = 6;
+    if (setsockopt(s, SOL_SOCKET, SO_PRIORITY, &priority, sizeof(priority)) < 0)
+      WARNF("could not set priority on socket");
+
+  }
+
+#endif
+
+  while ((in_len = recv_testcase(s, (void **)&in_data, &max_len)) > 0) {
+
+    // fprintf(stderr, "received %u\n", in_len);
+    (void)run_target(fsrv, use_argv, in_data, in_len, 1);
+
+    memcpy(send_buf + 4, fsrv->trace_bits, fsrv->map_size);
+
+#ifdef USE_DEFLATE
+    memcpy(buf2, &fsrv->child_status, 4);
+    *lenptr = (u32)libdeflate_deflate_compress(
+        compressor, send_buf + 4, fsrv->map_size, buf2 + 8, buf2_len - 8);
+    // fprintf(stderr, "COMPRESS (%u->%u): ", fsrv->map_size, *lenptr);
+    // for (u32 i = 0; i < fsrv->map_size; i++) fprintf(stderr, "%02x",
+    // fsrv->trace_bits[i]); fprintf(stderr, "\n");
+    if (send(s, buf2, *lenptr + 8, 0) != 8 + *lenptr)
+      FATAL("could not send data");
+#else
+    memcpy(send_buf, &fsrv->child_status, 4);
+    if (send(s, send_buf, fsrv->map_size + 4, 0) != 4 + fsrv->map_size)
+      FATAL("could not send data");
+#endif
+
+    // fprintf(stderr, "sent result\n");
+
+  }
+
+  unlink(out_file);
+  if (out_file) { ck_free(out_file); }
+  out_file = NULL;
+
+  afl_shm_deinit(&shm);
+  afl_fsrv_deinit(fsrv);
+  if (fsrv->target_path) { ck_free(fsrv->target_path); }
+  if (in_data) { ck_free(in_data); }
+#if USE_DEFLATE
+  if (buf2) { ck_free(buf2); }
+  libdeflate_free_compressor(compressor);
+  libdeflate_free_decompressor(decompressor);
+#endif
+
+  argv_cpy_free(argv);
+
+  exit(0);
+
+}
+

examples/afl_proxy/Makefile

@@ -0,0 +1,7 @@
+all:	afl-proxy
+
+afl-proxy:	afl-proxy.c
+	$(CC) -I../../include -o afl-proxy afl-proxy.c
+
+clean:
+	rm -f afl-proxy *~ core

examples/afl_proxy/README.md

@@ -0,0 +1,9 @@
+# afl-proxy
+
+afl-proxy is an example skeleton file which can easily be used to fuzz
+and instrument non-standard things.
+
+You only need to change the while() loop of the main() to send the
+data of buf[] with length len to the target and write the coverage
+information to __afl_area_ptr[__afl_map_size]
+

examples/afl_proxy/afl-proxy.c

@@ -0,0 +1,238 @@
+/*
+   american fuzzy lop++ - afl-proxy skeleton example
+   ---------------------------------------------------
+
+   Written by Marc Heuse <mh@mh-sec.de>
+
+   Copyright 2019-2020 AFLplusplus Project. All rights reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at:
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+
+   HOW-TO
+   ======
+
+   You only need to change the while() loop of the main() to send the
+   data of buf[] with length len to the target and write the coverage
+   information to __afl_area_ptr[__afl_map_size]
+
+
+*/
+
+#ifdef __ANDROID__
+  #include "android-ashmem.h"
+#endif
+#include "config.h"
+#include "types.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <signal.h>
+#include <unistd.h>
+#include <string.h>
+#include <assert.h>
+#include <stdint.h>
+#include <errno.h>
+
+#include <sys/mman.h>
+#include <sys/shm.h>
+#include <sys/wait.h>
+#include <sys/types.h>
+#include <fcntl.h>
+
+u8 *__afl_area_ptr;
+
+#ifdef __ANDROID__
+u32 __afl_map_size = MAP_SIZE;
+#else
+__thread u32 __afl_map_size = MAP_SIZE;
+#endif
+
+/* Error reporting to forkserver controller */
+
+void send_forkserver_error(int error) {
+
+  u32 status;
+  if (!error || error > 0xffff) return;
+  status = (FS_OPT_ERROR | FS_OPT_SET_ERROR(error));
+  if (write(FORKSRV_FD + 1, (char *)&status, 4) != 4) return;
+
+}
+
+/* SHM setup. */
+
+static void __afl_map_shm(void) {
+
+  char *id_str = getenv(SHM_ENV_VAR);
+  char *ptr;
+
+  if ((ptr = getenv("AFL_MAP_SIZE")) != NULL) {
+
+    u32 val = atoi(ptr);
+    if (val > 0) __afl_map_size = val;
+
+  }
+
+  if (__afl_map_size > MAP_SIZE) {
+
+    if (__afl_map_size > FS_OPT_MAX_MAPSIZE) {
+
+      fprintf(stderr,
+              "Error: AFL++ tools *require* to set AFL_MAP_SIZE to %u to "
+              "be able to run this instrumented program!\n",
+              __afl_map_size);
+      if (id_str) {
+
+        send_forkserver_error(FS_ERROR_MAP_SIZE);
+        exit(-1);
+
+      }
+
+    } else {
+
+      fprintf(stderr,
+              "Warning: AFL++ tools will need to set AFL_MAP_SIZE to %u to "
+              "be able to run this instrumented program!\n",
+              __afl_map_size);
+
+    }
+
+  }
+
+  if (id_str) {
+
+#ifdef USEMMAP
+    const char *   shm_file_path = id_str;
+    int            shm_fd = -1;
+    unsigned char *shm_base = NULL;
+
+    /* create the shared memory segment as if it was a file */
+    shm_fd = shm_open(shm_file_path, O_RDWR, 0600);
+    if (shm_fd == -1) {
+
+      fprintf(stderr, "shm_open() failed\n");
+      send_forkserver_error(FS_ERROR_SHM_OPEN);
+      exit(1);
+
+    }
+
+    /* map the shared memory segment to the address space of the process */
+    shm_base =
+        mmap(0, __afl_map_size, PROT_READ | PROT_WRITE, MAP_SHARED, shm_fd, 0);
+
+    if (shm_base == MAP_FAILED) {
+
+      close(shm_fd);
+      shm_fd = -1;
+
+      fprintf(stderr, "mmap() failed\n");
+      send_forkserver_error(FS_ERROR_MMAP);
+      exit(2);
+
+    }
+
+    __afl_area_ptr = shm_base;
+#else
+    u32 shm_id = atoi(id_str);
+
+    __afl_area_ptr = shmat(shm_id, 0, 0);
+
+#endif
+
+    if (__afl_area_ptr == (void *)-1) {
+
+      send_forkserver_error(FS_ERROR_SHMAT);
+      exit(1);
+
+    }
+
+    /* Write something into the bitmap so that the parent doesn't give up */
+
+    __afl_area_ptr[0] = 1;
+
+  }
+
+}
+
+/* Fork server logic. */
+
+static void __afl_start_forkserver(void) {
+
+  u8  tmp[4] = {0, 0, 0, 0};
+  u32 status = 0;
+
+  if (__afl_map_size <= FS_OPT_MAX_MAPSIZE)
+    status |= (FS_OPT_SET_MAPSIZE(__afl_map_size) | FS_OPT_MAPSIZE);
+  if (status) status |= (FS_OPT_ENABLED);
+  memcpy(tmp, &status, 4);
+
+  /* Phone home and tell the parent that we're OK. */
+
+  if (write(FORKSRV_FD + 1, tmp, 4) != 4) return;
+
+}
+
+static u32 __afl_next_testcase(u8 *buf, u32 max_len) {
+
+  s32 status, res = 0xffffff;
+
+  /* Wait for parent by reading from the pipe. Abort if read fails. */
+  if (read(FORKSRV_FD, &status, 4) != 4) return 0;
+
+  /* we have a testcase - read it */
+  status = read(0, buf, max_len);
+
+  /* report that we are starting the target */
+  if (write(FORKSRV_FD + 1, &res, 4) != 4) return 0;
+
+  if (status < 1)
+    return 0;
+  else
+    return status;
+
+}
+
+static void __afl_end_testcase(void) {
+
+  int status = 0xffffff;
+
+  if (write(FORKSRV_FD + 1, &status, 4) != 4) exit(1);
+
+}
+
+/* you just need to modify the while() loop in this main() */
+
+int main(int argc, char *argv[]) {
+
+  /* This is were the testcase data is written into */
+  u8  buf[1024];  // this is the maximum size for a test case! set it!
+  u32 len;
+
+  /* here you specify the map size you need that you are reporting to
+     afl-fuzz. */
+  __afl_map_size = MAP_SIZE;  // default is 65536
+
+  /* then we initialize the shared memory map and start the forkserver */
+  __afl_map_shm();
+  __afl_start_forkserver();
+
+  while ((len = __afl_next_testcase(buf, sizeof(buf))) > 0) {
+
+    /* here you have to create the magic that feeds the buf/len to the
+       target and write the coverage to __afl_area_ptr */
+
+    // ... the magic ...
+
+    /* report the test case is done and wait for the next */
+    __afl_end_testcase();
+
+  }
+
+  return 0;
+
+}
+

examples/afl_untracer/Makefile

@@ -0,0 +1,16 @@
+ifdef DEBUG
+  OPT=-O0
+else
+  OPT=-O3
+endif
+
+all:	afl-untracer libtestinstr.so
+
+afl-untracer:	afl-untracer.c
+	$(CC) $(OPT) -I../../include -g -o afl-untracer afl-untracer.c -ldl
+
+libtestinstr.so:	libtestinstr.c
+	$(CC) -g -O0 -fPIC -o libtestinstr.so -shared libtestinstr.c
+
+clean:
+	rm -f afl-untracer libtestinstr.so *~ core

examples/afl_untracer/README.md

@@ -0,0 +1,59 @@
+# afl-untracer - fast fuzzing of binary-only libraries
+
+## Introduction
+
+afl-untracer is an example skeleton file which can easily be used to fuzz
+a closed source library.
+
+It requires less memory and is x3-5 faster than qemu_mode however it is way
+more course grained and does not provide interesting features like compcov
+or cmplog.
+
+Supported is so far Intel (i386/x86_64) and AARCH64.
+
+## How-to
+
+### Modify afl-untracer.c
+
+Read and modify afl-untracer.c then `make`.
+To adapt afl-untracer.c to your needs, read the header of the file and then
+search and edit the `STEP 1`, `STEP 2` and `STEP 3` locations.
+
+### Generate patches.txt file
+
+To generate the `patches.txt` file for your target library use the
+`ida_get_patchpoints.py` script for IDA Pro or
+`ghidra_get_patchpoints.java` for Ghidra.
+
+The patches.txt file has to be pointed to by `AFL_UNTRACER_FILE`.
+
+To easily run the scripts without needing to run the GUI with Ghidra:
+```
+$ /opt/ghidra/support/analyzeHeadless /tmp/ tmp$$ -import libtestinstr.so -postscript ./ghidra_get_patchpoints.java
+$ rm -rf /tmp/tmp$$
+```
+
+### Fuzzing
+
+Example (after modifying afl-untracer.c to your needs, compiling and creating
+patches.txt):
+```
+AFL_UNTRACER_FILE=./patches.txt afl-fuzz -i in -o out -- ./afl-untracer
+```
+(or even remote via afl-network-proxy).
+
+### Testing and debugging
+
+For testing/debugging you can try:
+```
+make DEBUG=1
+AFL_UNTRACER_FILE=./patches.txt AFL_DEBUG=1 gdb ./afl-untracer
+```
+and then you can easily set breakpoints to "breakpoint" and "fuzz".
+
+# Background
+
+This idea is based on [UnTracer](https://github.com/FoRTE-Research/UnTracer-AFL)
+and modified by [Trapfuzz](https://github.com/googleprojectzero/p0tools/tree/master/TrapFuzz).
+This implementation is slower because the traps are not patched out with each
+run, but on the other hand gives much better coverage information.

examples/afl_untracer/afl-untracer.c

@@ -0,0 +1,756 @@
+/*
+   american fuzzy lop++ - afl-untracer skeleton example
+   ---------------------------------------------------
+
+   Written by Marc Heuse <mh@mh-sec.de>
+
+   Copyright 2019-2020 AFLplusplus Project. All rights reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at:
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+
+   HOW-TO
+   ======
+
+   You only need to change the following:
+
+   1. decide if you want to receive data from stdin [DEFAULT] or file(name)
+      -> use_stdin = 0 if via file, and what the maximum input size is
+   2. dl load the library you want to fuzz, lookup the functions you need
+      and setup the calls to these
+   3. in the while loop you call the functions in the necessary order -
+      incl the cleanup. the cleanup is important!
+
+   Just look these steps up in the code, look for "// STEP x:"
+
+
+*/
+
+#define __USE_GNU
+#define _GNU_SOURCE
+
+#ifdef __ANDROID__
+  #include "android-ashmem.h"
+#endif
+#include "config.h"
+#include "types.h"
+#include "debug.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <signal.h>
+#include <unistd.h>
+#include <string.h>
+#include <assert.h>
+#include <stdint.h>
+#include <errno.h>
+#include <dlfcn.h>
+#include <fcntl.h>
+#include <pthread.h>
+
+#include <sys/mman.h>
+#include <sys/shm.h>
+#include <sys/wait.h>
+#include <sys/types.h>
+
+#if defined(__linux__)
+  #include <sys/ucontext.h>
+#elif defined(__APPLE__) && defined(__LP64__)
+  #include <mach-o/dyld_images.h>
+#elif defined(__FreeBSD__)
+  #include <sys/sysctl.h>
+  #include <sys/user.h>
+#else
+  #error "Unsupported platform"
+#endif
+
+#define MEMORY_MAP_DECREMENT 0x200000000000
+#define MAX_LIB_COUNT 128
+
+// STEP 1:
+
+/* use stdin (1) or a file on the commandline (0) */
+static u32 use_stdin = 1;
+
+/* This is were the testcase data is written into */
+static u8 buf[10000];  // this is the maximum size for a test case! set it!
+
+/* If you want to have debug output set this to 1, can also be set with
+   AFL_DEBUG  */
+static u32 debug = 0;
+
+// END STEP 1
+
+typedef struct library_list {
+
+  u8 *name;
+  u64 addr_start, addr_end;
+
+} library_list_t;
+
+#ifdef __ANDROID__
+u32 __afl_map_size = MAP_SIZE;
+u32 do_exit;
+#else
+__thread u32 __afl_map_size = MAP_SIZE;
+__thread u32 do_exit;
+#endif
+
+static pid_t     pid = 65537;
+static pthread_t __afl_thread;
+static u8        __afl_dummy[MAP_SIZE];
+static u8 *      __afl_area_ptr = __afl_dummy;
+static u8 *      inputfile;  // this will point to argv[1]
+static u32       len;
+
+static library_list_t liblist[MAX_LIB_COUNT];
+static u32            liblist_cnt;
+
+static void sigtrap_handler(int signum, siginfo_t *si, void *context);
+static void fuzz();
+
+/* read the library information */
+void read_library_information() {
+
+#if defined(__linux__)
+  FILE *f;
+  u8    buf[1024], *b, *m, *e, *n;
+
+  if ((f = fopen("/proc/self/maps", "r")) == NULL)
+    FATAL("cannot open /proc/self/maps");
+
+  if (debug) fprintf(stderr, "Library list:\n");
+  while (fgets(buf, sizeof(buf), f)) {
+
+    if (strstr(buf, " r-x")) {
+
+      if (liblist_cnt >= MAX_LIB_COUNT) {
+
+        WARNF("too many libraries to old, maximum count of %d reached",
+              liblist_cnt);
+        return;
+
+      }
+
+      b = buf;
+      m = index(buf, '-');
+      e = index(buf, ' ');
+      if ((n = rindex(buf, '/')) == NULL) n = rindex(buf, ' ');
+      if (n &&
+          ((*n >= '0' && *n <= '9') || *n == '[' || *n == '{' || *n == '('))
+        n = NULL;
+      else
+        n++;
+      if (b && m && e && n && *n) {
+
+        *m++ = 0;
+        *e = 0;
+        if (n[strlen(n) - 1] == '\n') n[strlen(n) - 1] = 0;
+
+        liblist[liblist_cnt].name = strdup(n);
+        liblist[liblist_cnt].addr_start = strtoull(b, NULL, 16);
+        liblist[liblist_cnt].addr_end = strtoull(m, NULL, 16);
+        if (debug)
+          fprintf(
+              stderr, "%s:%llx (%llx-%llx)\n", liblist[liblist_cnt].name,
+              liblist[liblist_cnt].addr_end - liblist[liblist_cnt].addr_start,
+              liblist[liblist_cnt].addr_start,
+              liblist[liblist_cnt].addr_end - 1);
+        liblist_cnt++;
+
+      }
+
+    }
+
+  }
+
+  if (debug) fprintf(stderr, "\n");
+
+#elif defined(__FreeBSD__)
+  int    mib[] = {CTL_KERN, KERN_PROC, KERN_PROC_VMMAP, getpid()};
+  char * buf, *start, *end;
+  size_t miblen = sizeof(mib) / sizeof(mib[0]);
+  size_t len;
+
+  if (debug) fprintf(stderr, "Library list:\n");
+  if (sysctl(mib, miblen, NULL, &len, NULL, 0) == -1) { return; }
+
+  len = len * 4 / 3;
+
+  buf = mmap(NULL, len, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANON, -1, 0);
+  if (buf == MAP_FAILED) { return; }
+
+  if (sysctl(mib, miblen, buf, &len, NULL, 0) == -1) {
+
+    munmap(buf, len);
+    return;
+
+  }
+
+  start = buf;
+  end = buf + len;
+
+  while (start < end) {
+
+    struct kinfo_vmentry *region = (struct kinfo_vmentry *)start;
+    size_t                size = region->kve_structsize;
+
+    if (size == 0) { break; }
+
+    if ((region->kve_protection & KVME_PROT_READ) &&
+        !(region->kve_protection & KVME_PROT_EXEC)) {
+
+      liblist[liblist_cnt].name =
+          region->kve_path[0] != '\0' ? strdup(region->kve_path) : 0;
+      liblist[liblist_cnt].addr_start = region->kve_start;
+      liblist[liblist_cnt].addr_end = region->kve_end;
+
+      if (debug) {
+
+        fprintf(stderr, "%s:%x (%lx-%lx)\n", liblist[liblist_cnt].name,
+                liblist[liblist_cnt].addr_end - liblist[liblist_cnt].addr_start,
+                liblist[liblist_cnt].addr_start,
+                liblist[liblist_cnt].addr_end - 1);
+
+      }
+
+      liblist_cnt++;
+
+    }
+
+    start += size;
+
+  }
+
+#endif
+
+}
+
+library_list_t *find_library(char *name) {
+
+#if defined(__linux__)
+  u32 i;
+
+  for (i = 0; i < liblist_cnt; i++)
+    if (strncmp(liblist[i].name, name, strlen(name)) == 0) return &liblist[i];
+#elif defined(__APPLE__) && defined(__LP64__)
+  kern_return_t         err;
+  static library_list_t lib;
+
+  // get the list of all loaded modules from dyld
+  // the task_info mach API will get the address of the dyld all_image_info
+  // struct for the given task from which we can get the names and load
+  // addresses of all modules
+  task_dyld_info_data_t  task_dyld_info;
+  mach_msg_type_number_t count = TASK_DYLD_INFO_COUNT;
+  err = task_info(mach_task_self(), TASK_DYLD_INFO,
+                  (task_info_t)&task_dyld_info, &count);
+
+  const struct dyld_all_image_infos *all_image_infos =
+      (const struct dyld_all_image_infos *)task_dyld_info.all_image_info_addr;
+  const struct dyld_image_info *image_infos = all_image_infos->infoArray;
+
+  for (size_t i = 0; i < all_image_infos->infoArrayCount; i++) {
+
+    const char *      image_name = image_infos[i].imageFilePath;
+    mach_vm_address_t image_load_address =
+        (mach_vm_address_t)image_infos[i].imageLoadAddress;
+    if (strstr(image_name, name)) {
+
+      lib.name = name;
+      lib.addr_start = (u64)image_load_address;
+      lib.addr_end = 0;
+      return &lib;
+
+    }
+
+  }
+
+#endif
+
+  return NULL;
+
+}
+
+/* for having an easy breakpoint location after loading the shared library */
+// this seems to work for clang too. nice :) requires gcc 4.4+
+#pragma GCC push_options
+#pragma GCC optimize("O0")
+void        breakpoint() {
+
+  if (debug) fprintf(stderr, "Breakpoint function \"breakpoint\" reached.\n");
+
+}
+
+#pragma GCC pop_options
+
+/* Error reporting to forkserver controller */
+
+void send_forkserver_error(int error) {
+
+  u32 status;
+  if (!error || error > 0xffff) return;
+  status = (FS_OPT_ERROR | FS_OPT_SET_ERROR(error));
+  if (write(FORKSRV_FD + 1, (char *)&status, 4) != 4) return;
+
+}
+
+/* SHM setup. */
+
+static void __afl_map_shm(void) {
+
+  char *id_str = getenv(SHM_ENV_VAR);
+  char *ptr;
+
+  if ((ptr = getenv("AFL_MAP_SIZE")) != NULL) {
+
+    u32 val = atoi(ptr);
+    if (val > 0) __afl_map_size = val;
+
+  }
+
+  if (__afl_map_size > MAP_SIZE) {
+
+    if (__afl_map_size > FS_OPT_MAX_MAPSIZE) {
+
+      fprintf(stderr,
+              "Error: AFL++ tools *require* to set AFL_MAP_SIZE to %u to "
+              "be able to run this instrumented program!\n",
+              __afl_map_size);
+      if (id_str) {
+
+        send_forkserver_error(FS_ERROR_MAP_SIZE);
+        exit(-1);
+
+      }
+
+    } else {
+
+      fprintf(stderr,
+              "Warning: AFL++ tools will need to set AFL_MAP_SIZE to %u to "
+              "be able to run this instrumented program!\n",
+              __afl_map_size);
+
+    }
+
+  }
+
+  if (id_str) {
+
+#ifdef USEMMAP
+    const char *   shm_file_path = id_str;
+    int            shm_fd = -1;
+    unsigned char *shm_base = NULL;
+
+    /* create the shared memory segment as if it was a file */
+    shm_fd = shm_open(shm_file_path, O_RDWR, 0600);
+    if (shm_fd == -1) {
+
+      fprintf(stderr, "shm_open() failed\n");
+      send_forkserver_error(FS_ERROR_SHM_OPEN);
+      exit(1);
+
+    }
+
+    /* map the shared memory segment to the address space of the process */
+    shm_base =
+        mmap(0, __afl_map_size, PROT_READ | PROT_WRITE, MAP_SHARED, shm_fd, 0);
+
+    if (shm_base == MAP_FAILED) {
+
+      close(shm_fd);
+      shm_fd = -1;
+
+      fprintf(stderr, "mmap() failed\n");
+      send_forkserver_error(FS_ERROR_MMAP);
+      exit(2);
+
+    }
+
+    __afl_area_ptr = shm_base;
+#else
+    u32 shm_id = atoi(id_str);
+
+    __afl_area_ptr = shmat(shm_id, 0, 0);
+
+#endif
+
+    if (__afl_area_ptr == (void *)-1) {
+
+      send_forkserver_error(FS_ERROR_SHMAT);
+      exit(1);
+
+    }
+
+    /* Write something into the bitmap so that the parent doesn't give up */
+
+    __afl_area_ptr[0] = 1;
+
+  }
+
+}
+
+/* Fork server logic. */
+static void __afl_start_forkserver(void) {
+
+  u8  tmp[4] = {0, 0, 0, 0};
+  u32 status = 0;
+
+  if (__afl_map_size <= FS_OPT_MAX_MAPSIZE)
+    status |= (FS_OPT_SET_MAPSIZE(__afl_map_size) | FS_OPT_MAPSIZE);
+  if (status) status |= (FS_OPT_ENABLED);
+  memcpy(tmp, &status, 4);
+
+  /* Phone home and tell the parent that we're OK. */
+  if (write(FORKSRV_FD + 1, tmp, 4) != 4) do_exit = 1;
+  // fprintf(stderr, "write0 %d\n", do_exit);
+
+}
+
+static u32 __afl_next_testcase(u8 *buf, u32 max_len) {
+
+  s32 status;
+
+  /* Wait for parent by reading from the pipe. Abort if read fails. */
+  if (read(FORKSRV_FD, &status, 4) != 4) do_exit = 1;
+  // fprintf(stderr, "read %d\n", do_exit);
+
+  /* we have a testcase - read it if we read from stdin */
+  if (use_stdin) {
+
+    if ((status = read(0, buf, max_len)) <= 0) exit(-1);
+
+  } else
+
+    status = 1;
+  // fprintf(stderr, "stdin: %d %d\n", use_stdin, status);
+
+  /* report that we are starting the target */
+  if (write(FORKSRV_FD + 1, &pid, 4) != 4) do_exit = 1;
+  // fprintf(stderr, "write1 %d\n", do_exit);
+
+  return status;
+
+}
+
+static void __afl_end_testcase(int status) {
+
+  if (write(FORKSRV_FD + 1, &status, 4) != 4) do_exit = 1;
+  // fprintf(stderr, "write2 %d\n", do_exit);
+  if (do_exit) exit(0);
+
+}
+
+#ifdef __aarch64__
+  #define SHADOW(addr)                                     \
+    ((uint64_t *)(((uintptr_t)addr & 0xfffffffffffffff8) - \
+                  MEMORY_MAP_DECREMENT -                   \
+                  ((uintptr_t)addr & 0x7) * 0x10000000000))
+#else
+  #define SHADOW(addr)                                     \
+    ((uint32_t *)(((uintptr_t)addr & 0xfffffffffffffffc) - \
+                  MEMORY_MAP_DECREMENT -                   \
+                  ((uintptr_t)addr & 0x3) * 0x10000000000))
+#endif
+
+void setup_trap_instrumentation() {
+
+  library_list_t *lib_base = NULL;
+  size_t          lib_size = 0;
+  u8 *            lib_addr;
+  char *          line = NULL;
+  size_t          nread, len = 0;
+  char *          filename = getenv("AFL_UNTRACER_FILE");
+  if (!filename) filename = getenv("TRAPFUZZ_FILE");
+  if (!filename) FATAL("AFL_UNTRACER_FILE environment variable not set");
+
+  FILE *patches = fopen(filename, "r");
+  if (!patches) FATAL("Couldn't open AFL_UNTRACER_FILE file %s", filename);
+
+    // Index into the coverage bitmap for the current trap instruction.
+#ifdef __aarch64__
+  uint64_t bitmap_index = 0;
+#else
+  uint32_t bitmap_index = 0;
+#endif
+
+  while ((nread = getline(&line, &len, patches)) != -1) {
+
+    char *end = line + len;
+
+    char *col = strchr(line, ':');
+    if (col) {
+
+      // It's a library:size pair
+      *col++ = 0;
+
+      lib_base = find_library(line);
+      if (!lib_base) FATAL("Library %s does not appear to be loaded", line);
+
+      // we ignore the defined lib_size
+      lib_size = strtoul(col, NULL, 16);
+#if (__linux__)
+      if (lib_size < lib_base->addr_end - lib_base->addr_start)
+        lib_size = lib_base->addr_end - lib_base->addr_start;
+#endif
+      if (lib_size % 0x1000 != 0)
+        WARNF("Invalid library size 0x%zx. Must be multiple of 0x1000",
+              lib_size);
+
+      lib_addr = (u8 *)lib_base->addr_start;
+
+      // Make library code writable.
+      if (mprotect((void *)lib_addr, lib_size,
+                   PROT_READ | PROT_WRITE | PROT_EXEC) != 0)
+        FATAL("Failed to mprotect library %s writable", line);
+
+        // Create shadow memory.
+#ifdef __aarch64__
+      for (int i = 0; i < 8; i++) {
+
+#else
+      for (int i = 0; i < 4; i++) {
+
+#endif
+
+        void *shadow_addr = SHADOW(lib_addr + i);
+        void *shadow = mmap(shadow_addr, lib_size, PROT_READ | PROT_WRITE,
+                            MAP_PRIVATE | MAP_ANON | MAP_FIXED, 0, 0);
+        if (debug)
+          fprintf(stderr, "Shadow: %s %d = %p-%p for %p\n", line, i, shadow,
+                  shadow + lib_size - 1, lib_addr);
+        if (shadow == MAP_FAILED) FATAL("Failed to mmap shadow memory");
+
+      }
+
+      // Done, continue with next line.
+      continue;
+
+    }
+
+    // It's an offset, parse it and do the patching.
+    unsigned long offset = strtoul(line, NULL, 16);
+
+    if (offset > lib_size)
+      FATAL("Invalid offset: 0x%lx. Current library is 0x%zx bytes large",
+            offset, lib_size);
+
+    if (bitmap_index >= __afl_map_size)
+      FATAL("Too many basic blocks to instrument");
+
+#ifdef __arch64__
+    uint64_t
+#else
+    uint32_t
+#endif
+        *shadow = SHADOW(lib_addr + offset);
+    if (*shadow != 0) continue;  // skip duplicates
+
+      // Make lookup entry in shadow memory.
+
+#if ((defined(__APPLE__) && defined(__LP64__)) || defined(__x86_64__) || \
+     defined(__i386__))
+
+    // this is for Intel x64
+
+    uint8_t orig_byte = lib_addr[offset];
+    *shadow = (bitmap_index << 8) | orig_byte;
+    lib_addr[offset] = 0xcc;  // replace instruction with debug trap
+    if (debug)
+      fprintf(stderr,
+              "Patch entry: %p[%x] = %p = %02x -> SHADOW(%p) #%d -> %08x\n",
+              lib_addr, offset, lib_addr + offset, orig_byte, shadow,
+              bitmap_index, *shadow);
+
+#elif defined(__aarch64__)
+
+    // this is for aarch64
+
+    uint32_t *patch_bytes = (uint32_t *)(lib_addr + offset);
+    uint32_t  orig_bytes = *patch_bytes;
+    *shadow = (bitmap_index << 32) | orig_bytes;
+    *patch_bytes = 0xd4200000;  // replace instruction with debug trap
+    if (debug)
+      fprintf(stderr,
+              "Patch entry: %p[%x] = %p = %02x -> SHADOW(%p) #%d -> %016x\n",
+              lib_addr, offset, lib_addr + offset, orig_bytes, shadow,
+              bitmap_index, *shadow);
+
+#else
+    // this will be ARM and AARCH64
+    // for ARM we will need to identify if the code is in thumb or ARM
+  #error "non x86_64/aarch64 not supported yet"
+    //__arm__:
+    // linux thumb: 0xde01
+    // linux arm: 0xe7f001f0
+    //__aarch64__:
+    // linux aarch64: 0xd4200000
+#endif
+
+    bitmap_index++;
+
+  }
+
+  free(line);
+  fclose(patches);
+
+  // Install signal handler for SIGTRAP.
+  struct sigaction s;
+  s.sa_flags = SA_SIGINFO;
+  s.sa_sigaction = sigtrap_handler;
+  sigemptyset(&s.sa_mask);
+  sigaction(SIGTRAP, &s, 0);
+
+  if (debug) fprintf(stderr, "Patched %u locations.\n", bitmap_index);
+  __afl_map_size = bitmap_index;
+  if (__afl_map_size % 8) __afl_map_size = (((__afl_map_size + 7) >> 3) << 3);
+
+}
+
+/* the signal handler for the traps / debugging interrupts
+   No debug output here because this would cost speed      */
+static void sigtrap_handler(int signum, siginfo_t *si, void *context) {
+
+  uint64_t addr;
+  // Must re-execute the instruction, so decrement PC by one instruction.
+  ucontext_t *ctx = (ucontext_t *)context;
+#if defined(__APPLE__) && defined(__LP64__)
+  ctx->uc_mcontext->__ss.__rip -= 1;
+  addr = ctx->uc_mcontext->__ss.__rip;
+#elif defined(__linux__)
+  #if defined(__x86_64__) || defined(__i386__)
+  ctx->uc_mcontext.gregs[REG_RIP] -= 1;
+  addr = ctx->uc_mcontext.gregs[REG_RIP];
+  #elif defined(__aarch64__)
+  ctx->uc_mcontext.pc -= 4;
+  addr = ctx->uc_mcontext.pc;
+  #else
+    #error "Unsupported processor"
+  #endif
+#elif defined(__FreeBSD__) && defined(__LP64__)
+  ctx->uc_mcontext.mc_rip -= 1;
+  addr = ctx->uc_mcontext.mc_rip;
+#else
+  #error "Unsupported platform"
+#endif
+
+  // fprintf(stderr, "TRAP at context addr = %lx, fault addr = %lx\n", addr,
+  // si->si_addr);
+
+  // If the trap didn't come from our instrumentation, then we probably will
+  // just segfault here
+  uint8_t *faultaddr;
+  if (unlikely(si->si_addr))
+    faultaddr = (u8 *)si->si_addr - 1;
+  else
+    faultaddr = (u8 *)addr;
+  // if (debug) fprintf(stderr, "Shadow location: %p\n", SHADOW(faultaddr));
+  uint32_t shadow = *SHADOW(faultaddr);
+  uint8_t  orig_byte = shadow & 0xff;
+  uint32_t index = shadow >> 8;
+
+  // if (debug) fprintf(stderr, "shadow data: %x, orig_byte %02x, index %d\n",
+  // shadow, orig_byte, index);
+
+  // Index zero is invalid so that it is still possible to catch actual trap
+  // instructions in instrumented libraries.
+  if (unlikely(index == 0)) abort();
+
+  // Restore original instruction
+  *faultaddr = orig_byte;
+
+  __afl_area_ptr[index] = 128;
+
+}
+
+/* here you need to specify the parameter for the target function */
+static void *(*o_function)(u8 *buf, int len);
+
+/* the MAIN function */
+int main(int argc, char *argv[]) {
+
+  pid = getpid();
+  if (getenv("AFL_DEBUG")) debug = 1;
+
+  /* by default we use stdin, but also a filename can be passed, in this
+     case the input is argv[1] and we have to disable stdin */
+  if (argc > 1) {
+
+    use_stdin = 0;
+    inputfile = argv[1];
+
+  }
+
+  // STEP 2: load the library you want to fuzz and lookup the functions,
+  //         inclusive of the cleanup functions
+  //         NOTE: above the main() you have to define the functions!
+
+  void *dl = dlopen("./libtestinstr.so", RTLD_LAZY);
+  if (!dl) FATAL("could not find target library");
+  o_function = dlsym(dl, "testinstr");
+  if (!o_function) FATAL("could not resolve target function from library");
+  if (debug) fprintf(stderr, "Function address: %p\n", o_function);
+
+  // END STEP 2
+
+  /* setup instrumentation, shared memory and forkserver */
+  breakpoint();
+  read_library_information();
+  setup_trap_instrumentation();
+  __afl_map_shm();
+  __afl_start_forkserver();
+
+  while (1) {
+
+    if ((pid = fork()) == -1) PFATAL("fork failed");
+
+    if (pid) {
+
+      u32 status;
+      if (waitpid(pid, &status, 0) < 0) exit(1);
+      /* report the test case is done and wait for the next */
+      __afl_end_testcase(status);
+
+    } else {
+
+      pid = getpid();
+      while ((len = __afl_next_testcase(buf, sizeof(buf))) > 0) {
+
+        // in this function the fuzz magic happens, this is STEP 3
+        fuzz();
+
+        // we can use _exit which is faster because our target library
+        // was loaded via dlopen and therefore cannot have deconstructors
+        // registered.
+        _exit(0);
+
+      }
+
+    }
+
+  }
+
+  return 0;
+
+}
+
+static void fuzz() {
+
+  // STEP 3: call the function to fuzz, also the functions you might
+  //         need to call to prepare the function and - important! -
+  //         to clean everything up
+
+  // in this example we use the input file, not stdin!
+  (*o_function)(buf, len);
+
+  // normally you also need to cleanup
+  //(*o_LibFree)(foo);
+
+  // END STEP 3
+
+}
+

examples/afl_untracer/ghidra_get_patchpoints.java

@@ -0,0 +1,84 @@
+/* ###
+ * IP: GHIDRA
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Find patch points for untracer tools (e.g. afl++ examples/afl_untracer)
+//
+//   Copy to ..../Ghidra/Features/Search/ghidra_scripts/
+//   Writes the results to ~/Desktop/patches.txt
+//
+//   This is my very first Ghidra script. I am sure this could be done better.
+//
+//@category Search
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.*;
+import ghidra.program.model.block.*;
+import ghidra.program.model.listing.*;
+import ghidra.program.model.symbol.*;
+import ghidra.program.model.mem.*;
+
+import java.io.*;
+
+public class ghidra_get_patchpoints extends GhidraScript {
+
+	@Override
+	public void run() throws Exception {
+
+		long segment_start = 0;
+		Memory memory = currentProgram.getMemory();
+		MultEntSubModel model = new MultEntSubModel(currentProgram);
+		CodeBlockIterator subIter = model.getCodeBlocks(monitor);
+		BufferedWriter out = new BufferedWriter(new FileWriter(System.getProperty("user.home") + File.separator + "Desktop" + File.separator + "patches.txt"));
+
+		while (subIter.hasNext()) {
+
+			CodeBlock multiEntryBlock = subIter.next();
+			SimpleBlockModel basicBlockModel = new SimpleBlockModel(currentProgram);
+			CodeBlockIterator bbIter = basicBlockModel.getCodeBlocksContaining(multiEntryBlock, monitor);
+
+			while (bbIter.hasNext()) {
+
+				CodeBlock basicBlock = bbIter.next();
+
+				if (segment_start == 0) {
+
+					Address firstAddr = basicBlock.getFirstStartAddress();
+					long firstBlockAddr = firstAddr.getAddressableWordOffset();
+					MemoryBlock mb = memory.getBlock(firstAddr);
+					Address startAddr = mb.getStart();
+					Address endAddr = mb.getEnd();
+					segment_start = startAddr.getAddressableWordOffset();
+					if ((firstBlockAddr - segment_start) >= 0x1000)
+					  segment_start += 0x1000;
+					long segment_end = endAddr.getAddressableWordOffset();
+					long segment_size = segment_end - segment_start;
+					if ((segment_size % 0x1000) > 0)
+					  segment_size = (((segment_size / 0x1000) + 1) * 0x1000);
+					out.write(currentProgram.getName() + ":0x" + Long.toHexString(segment_size) + "\n"); 
+					//println("Start: " + Long.toHexString(segment_start));
+					//println("End: " + Long.toHexString(segment_end));
+
+				}
+ 	   		        
+ 	   		        if (basicBlock.getFirstStartAddress().getAddressableWordOffset() - segment_start > 0)
+ 	   		        	out.write("0x" + Long.toHexString(basicBlock.getFirstStartAddress().getAddressableWordOffset() - segment_start) + "\n");
+
+			}
+		}
+
+		out.close();
+
+	}
+}

examples/afl_untracer/ida_get_patchpoints.py

@@ -0,0 +1,62 @@
+#
+# IDAPython script for IDA Pro
+# Slightly modified from https://github.com/googleprojectzero/p0tools/blob/master/TrapFuzz/findPatchPoints.py
+#
+
+import idautils
+import idaapi
+import ida_nalt
+import idc
+
+# See https://www.hex-rays.com/products/ida/support/ida74_idapython_no_bc695_porting_guide.shtml
+
+from os.path import expanduser
+home = expanduser("~")
+
+patchpoints = set()
+
+max_offset = 0
+for seg_ea in idautils.Segments():
+    name = idc.get_segm_name(seg_ea)
+    #print("Segment: " + name)
+    if name != "__text" and name != ".text":
+        continue
+
+    start = idc.get_segm_start(seg_ea)
+    end = idc.get_segm_end(seg_ea)
+    first = 0
+    subtract_addr = 0
+    #print("Start: " + hex(start) + " End: " + hex(end))
+    for func_ea in idautils.Functions(start, end):
+        f = idaapi.get_func(func_ea)
+        if not f:
+            continue
+        for block in idaapi.FlowChart(f):
+            if start <= block.start_ea < end:
+                if first == 0:
+                    if block.start_ea >= 0x1000:
+                        subtract_addr = 0x1000
+                        first = 1
+                        
+                max_offset = max(max_offset, block.start_ea)
+                patchpoints.add(block.start_ea - subtract_addr)
+            #else:
+            #    print("Warning: broken CFG?")
+
+# Round up max_offset to page size
+size = max_offset
+rem = size % 0x1000
+if rem != 0:
+    size += 0x1000 - rem
+
+print("Writing to " + home + "/Desktop/patches.txt")
+
+with open(home + "/Desktop/patches.txt", "w") as f:
+    f.write(ida_nalt.get_root_filename() + ':' + hex(size) + '\n')
+    f.write('\n'.join(map(hex, sorted(patchpoints))))
+    f.write('\n')
+
+print("Done, found {} patchpoints".format(len(patchpoints)))
+
+# For headless script running remove the comment from the next line
+#ida_pro.qexit()

examples/afl_untracer/libtestinstr.c

@@ -0,0 +1,35 @@
+/*
+   american fuzzy lop++ - a trivial program to test the build
+   --------------------------------------------------------
+   Originally written by Michal Zalewski
+   Copyright 2014 Google Inc. All rights reserved.
+   Copyright 2019-2020 AFLplusplus Project. All rights reserved.
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at:
+     http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+
+void testinstr(char *buf, int len) {
+
+  if (len < 1) return;
+  buf[len] = 0;
+
+  // we support three input cases
+  if (buf[0] == '0')
+    printf("Looks like a zero to me!\n");
+  else if (buf[0] == '1')
+    printf("Pretty sure that is a one!\n");
+  else
+    printf("Neither one or zero? How quaint!\n");
+
+}
+

examples/afl_untracer/patches.txt

@@ -0,0 +1,23 @@
+libtestinstr.so:0x2000L
+0x1050L
+0x1063L
+0x106fL
+0x1078L
+0x1080L
+0x10a4L
+0x10b0L
+0x10b8L
+0x10c0L
+0x10c9L
+0x10d7L
+0x10e3L
+0x10f8L
+0x1100L
+0x1105L
+0x111aL
+0x1135L
+0x1143L
+0x114eL
+0x115cL
+0x116aL
+0x116bL

examples/argv_fuzzing/Makefile

@@ -0,0 +1,58 @@
+#
+# american fuzzy lop++ - argvfuzz
+# --------------------------------
+#
+# Copyright 2019-2020 Kjell Braden <afflux@pentabarf.de>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+
+.PHONY: all install clean
+
+PREFIX     ?= /usr/local
+BIN_PATH    = $(PREFIX)/bin
+HELPER_PATH = $(PREFIX)/lib/afl
+
+CFLAGS = -fPIC -Wall -Wextra
+LDFLAGS = -shared
+
+UNAME_SAYS_LINUX=$(shell uname | grep -E '^Linux|^GNU' >/dev/null; echo $$?)
+UNAME_SAYS_LINUX:sh=uname | grep -E '^Linux|^GNU' >/dev/null; echo $$?
+
+_LDFLAGS_ADD=$(UNAME_SAYS_LINUX:1=)
+LDFLAGS_ADD=$(_LDFLAGS_ADD:0=-ldl)
+LDFLAGS  += $(LDFLAGS_ADD)
+
+# on gcc for arm there is no -m32, but -mbe32
+M32FLAG = -m32
+M64FLAG = -m64
+
+CC_IS_GCC=$(shell $(CC) --version 2>/dev/null | grep -q gcc; echo $$?)
+CC_IS_GCC:sh=$(CC) --version 2>/dev/null | grep -q gcc; echo $$?
+CC_IS_ARMCOMPILER=$(shell $(CC) -v 2>&1 >/dev/null | grep -q arm; echo $$?)
+CC_IS_ARMCOMPILER:sh=$(CC) -v 2>&1 >/dev/null | grep -q arm; echo $$?
+
+_M32FLAG=$(CC_IS_GCC)$(CC_IS_ARMCOMPILER)
+__M32FLAG=$(_M32FLAG:00=-mbe32)
+___M32FLAG=$(__M32FLAG:$(CC_IS_GCC)$(CC_IS_ARMCOMPILER)=-m32)
+M32FLAG=$(___M32FLAG)
+
+all: argvfuzz32.so argvfuzz64.so
+
+argvfuzz32.so: argvfuzz.c
+	-@$(CC) $(M32FLAG) $(CFLAGS) $^ $(LDFLAGS) -o $@ 2>/dev/null || echo "argvfuzz32 build failure (that's fine)"
+
+argvfuzz64.so: argvfuzz.c
+	-@$(CC) $(M64FLAG) $(CFLAGS) $^ $(LDFLAGS) -o $@ 2>/dev/null || echo "argvfuzz64 build failure (that's fine)"
+
+install: argvfuzz32.so argvfuzz64.so
+	install -d -m 755 $(DESTDIR)$(HELPER_PATH)/
+	if [ -f argvfuzz32.so ]; then set -e; install -m 755 argvfuzz32.so $(DESTDIR)$(HELPER_PATH)/; fi
+	if [ -f argvfuzz64.so ]; then set -e; install -m 755 argvfuzz64.so $(DESTDIR)$(HELPER_PATH)/; fi
+
+clean:
+	rm -f argvfuzz32.so argvfuzz64.so

examples/argv_fuzzing/README.md

@@ -0,0 +1,16 @@
+# argvfuzz
+
+afl supports fuzzing file inputs or stdin. When source is available,
+`argv-fuzz-inl.h` can be used to change `main()` to build argv from stdin.
+
+`argvfuzz` tries to provide the same functionality for binaries. When loaded
+using `LD_PRELOAD`, it will hook the call to `__libc_start_main` and replace
+argv using the same logic of `argv-fuzz-inl.h`.
+
+A few conditions need to be fulfilled for this mechanism to work correctly:
+
+1. As it relies on hooking the loader, it cannot work on static binaries.
+2. If the target binary does not use the default libc's `_start` implementation
+   (crt1.o), the hook may not run.
+3. The hook will replace argv with pointers to `.data` of `argvfuzz.so`. If the
+   target binary expects argv to be living on the stack, things may go wrong.

examples/argv_fuzzing/argv-fuzz-inl.h

@@ -1,8 +1,8 @@
 /*
-   american fuzzy lop - sample argv fuzzing wrapper
+   american fuzzy lop++ - sample argv fuzzing wrapper
    ------------------------------------------------
 
-   Written by Michal Zalewski <lcamtuf@google.com>
+   Originally written by Michal Zalewski
 
    Copyright 2015 Google Inc. All rights reserved.
 
@@ -17,7 +17,7 @@
 
    #include "/path/to/argv-fuzz-inl.h"
 
-   ...to the file containing main(), ideally placing it after all the 
+   ...to the file containing main(), ideally placing it after all the
    standard includes. Next, put AFL_INIT_ARGV(); near the very beginning of
    main().
 
@@ -36,34 +36,43 @@
 
 #include <unistd.h>
 
-#define AFL_INIT_ARGV() do { argv = afl_init_argv(&argc); } while (0)
-
-#define AFL_INIT_SET0(_p) do { \
+#define AFL_INIT_ARGV()          \
+  do {                           \
+                                 \
     argv = afl_init_argv(&argc); \
-    argv[0] = (_p); \
-    if (!argc) argc = 1; \
+                                 \
+  } while (0)
+
+#define AFL_INIT_SET0(_p)        \
+  do {                           \
+                                 \
+    argv = afl_init_argv(&argc); \
+    argv[0] = (_p);              \
+    if (!argc) argc = 1;         \
+                                 \
   } while (0)
 
 #define MAX_CMDLINE_LEN 100000
-#define MAX_CMDLINE_PAR 1000
+#define MAX_CMDLINE_PAR 50000
 
-static char** afl_init_argv(int* argc) {
+static char **afl_init_argv(int *argc) {
 
   static char  in_buf[MAX_CMDLINE_LEN];
-  static char* ret[MAX_CMDLINE_PAR];
+  static char *ret[MAX_CMDLINE_PAR];
 
-  char* ptr = in_buf;
-  int   rc  = 0;
+  char *ptr = in_buf;
+  int   rc = 0;
 
-  if (read(0, in_buf, MAX_CMDLINE_LEN - 2) < 0);
+  if (read(0, in_buf, MAX_CMDLINE_LEN - 2) < 0) {}
 
-  while (*ptr) {
+  while (*ptr && rc < MAX_CMDLINE_PAR) {
 
     ret[rc] = ptr;
     if (ret[rc][0] == 0x02 && !ret[rc][1]) ret[rc]++;
     rc++;
 
-    while (*ptr) ptr++;
+    while (*ptr)
+      ptr++;
     ptr++;
 
   }
@@ -77,4 +86,5 @@ static char** afl_init_argv(int* argc) {
 #undef MAX_CMDLINE_LEN
 #undef MAX_CMDLINE_PAR
 
-#endif /* !_HAVE_ARGV_FUZZ_INL */
+#endif                                              /* !_HAVE_ARGV_FUZZ_INL */
+

examples/argv_fuzzing/argvfuzz.c

@@ -0,0 +1,49 @@
+/*
+   american fuzzy lop++ - LD_PRELOAD for fuzzing argv in binaries
+   ------------------------------------------------------------
+
+   Copyright 2019-2020 Kjell Braden <afflux@pentabarf.de>
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at:
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ */
+
+#define _GNU_SOURCE                                        /* for RTLD_NEXT */
+#include <dlfcn.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <unistd.h>
+#include "argv-fuzz-inl.h"
+
+int __libc_start_main(int (*main)(int, char **, char **), int argc, char **argv,
+                      void (*init)(void), void (*fini)(void),
+                      void (*rtld_fini)(void), void *stack_end) {
+
+  int (*orig)(int (*main)(int, char **, char **), int argc, char **argv,
+              void (*init)(void), void (*fini)(void), void (*rtld_fini)(void),
+              void *stack_end);
+  int    sub_argc;
+  char **sub_argv;
+
+  (void)argc;
+  (void)argv;
+
+  orig = dlsym(RTLD_NEXT, __func__);
+
+  if (!orig) {
+
+    fprintf(stderr, "hook did not find original %s: %s\n", __func__, dlerror());
+    exit(EXIT_FAILURE);
+
+  }
+
+  sub_argv = afl_init_argv(&sub_argc);
+
+  return orig(main, sub_argc, sub_argv, init, fini, rtld_fini, stack_end);
+
+}
+

examples/asan_cgroups/limit_memory.sh

@@ -1,13 +1,13 @@
 #!/usr/bin/env bash
 #
-# american fuzzy lop - limit memory using cgroups
+# american fuzzy lop++ - limit memory using cgroups
 # -----------------------------------------------
 #
 # Written by Samir Khakimov <samir.hakim@nyu.edu> and
 #            David A. Wheeler <dwheeler@ida.org>
 #
 # Edits to bring the script in line with afl-cmin and other companion scripts
-# by Michal Zalewski <lcamtuf@google.com>. All bugs are my fault.
+# by Michal Zalewski. All bugs are my fault.
 #
 # Copyright 2015 Institute for Defense Analyses.
 #
@@ -20,7 +20,7 @@
 # This tool allows the amount of actual memory allocated to a program
 # to be limited on Linux systems using cgroups, instead of the traditional
 # setrlimit() API. This helps avoid the address space problems discussed in
-# docs/notes_for_asan.txt.
+# docs/notes_for_asan.md.
 #
 # Important: the limit covers *both* afl-fuzz and the fuzzed binary. In some
 # hopefully rare circumstances, afl-fuzz could be killed before the fuzzed

examples/canvas_harness/canvas_harness.html

@@ -1,10 +1,10 @@
 <html>
 <!--
 
-  american fuzzy lop - <canvas> harness
+  american fuzzy lop++ - <canvas> harness
   -------------------------------------
  
-  Written and maintained by Michal Zalewski <lcamtuf@google.com>
+  Originally written by Michal Zalewski
  
   Copyright 2013, 2014 Google Inc. All rights reserved.
  

examples/clang_asm_normalize/as

@@ -1,9 +1,9 @@
 #!/bin/sh
 #
-# american fuzzy lop - clang assembly normalizer
+# american fuzzy lop++ - clang assembly normalizer
 # ----------------------------------------------
 #
-# Written and maintained by Michal Zalewski <lcamtuf@google.com>
+# Originally written by Michal Zalewski
 # The idea for this wrapper comes from Ryan Govostes.
 #
 # Copyright 2013, 2014 Google Inc. All rights reserved.

examples/crash_triage/triage_crashes.sh

@@ -1,9 +1,9 @@
 #!/bin/sh
 #
-# american fuzzy lop - crash triage utility
+# american fuzzy lop++ - crash triage utility
 # -----------------------------------------
 #
-# Written and maintained by Michal Zalewski <lcamtuf@google.com>
+# Originally written by Michal Zalewski
 #
 # Copyright 2013, 2014, 2017 Google Inc. All rights reserved.
 #
@@ -22,7 +22,7 @@
 # necessary.
 #
 
-echo "crash triage utility for afl-fuzz by <lcamtuf@google.com>"
+echo "crash triage utility for afl-fuzz by Michal Zalewski"
 echo
 
 ulimit -v 100000 2>/dev/null
@@ -91,10 +91,10 @@ for crash in $DIR/crashes/id:*; do
   for a in $@; do
 
     if [ "$a" = "@@" ] ; then
-      args="$use_args $crash"
+      use_args="$use_args $crash"
       unset use_stdio
     else
-      args="$use_args $a"
+      use_args="$use_args $a"
     fi
 
   done

examples/custom_mutators/Makefile

@@ -0,0 +1,7 @@
+all: libexamplemutator.so
+
+libexamplemutator.so:
+	$(CC) $(CFLAGS) -D_FORTIFY_SOURCE=2 -O3 -fPIC -shared -g -I ../../include example.c -o libexamplemutator.so
+
+clean:
+	rm -rf libexamplemutator.so

examples/custom_mutators/README.md

@@ -0,0 +1,31 @@
+# Examples for the custom mutator
+
+These are example and helper files for the custom mutator feature.
+See [docs/custom_mutators.md](../docs/custom_mutators.md) for more information
+
+Note that if you compile with python3.7 you must use python3 scripts, and if
+you use python2.7 to compile python2 scripts!
+
+simple_example.c - most simplest example. generates a random sized buffer
+          filled with 'A'
+
+example.c - this is a simple example written in C and should be compiled to a
+          shared library. Use make to compile it and produce libexamplemutator.so
+
+example.py - this is the template you can use, the functions are there but they
+           are empty
+
+simple-chunk-replace.py - this is a simple example where chunks are replaced
+
+common.py - this can be used for common functions and helpers.
+          the examples do not use this though. But you can :)
+
+wrapper_afl_min.py - mutation of XML documents, loads XmlMutatorMin.py
+
+XmlMutatorMin.py - module for XML mutation
+
+custom_mutator_helpers.h is an header that defines some helper routines
+like surgical_havoc_mutate() that allow to perform a randomly chosen
+mutation from a subset of the havoc mutations.
+If you do so, you have to specify -I /path/to/AFLplusplus/include when
+compiling.

examples/custom_mutators/XmlMutatorMin.py

@@ -7,6 +7,7 @@ from copy import deepcopy
 from lxml import etree as ET
 import random, re, io
 
+
 ###########################
 # The XmlMutatorMin class #
 ###########################
@@ -40,19 +41,19 @@ class XmlMutatorMin:
         self.tree = None
 
         # High-level mutators (no database needed)
-        hl_mutators_delete = [ "del_node_and_children", "del_node_but_children", "del_attribute", "del_content" ] # Delete items
-        hl_mutators_fuzz = ["fuzz_attribute"] # Randomly change attribute values
+        hl_mutators_delete = ["del_node_and_children", "del_node_but_children", "del_attribute", "del_content"]  # Delete items
+        hl_mutators_fuzz = ["fuzz_attribute"]  # Randomly change attribute values
 
         # Exposed mutators
         self.hl_mutators_all = hl_mutators_fuzz + hl_mutators_delete
-        
-    def __parse_xml (self, xml):
+
+    def __parse_xml(self, xml):
 
         """ Parse an XML string. Basic wrapper around lxml.parse() """
 
         try:
             # Function parse() takes care of comments / DTD / processing instructions / ...
-        	tree = ET.parse(io.BytesIO(xml))
+            tree = ET.parse(io.BytesIO(xml))
         except ET.ParseError:
             raise RuntimeError("XML isn't well-formed!")
         except LookupError as e:
@@ -61,34 +62,34 @@ class XmlMutatorMin:
         # Return a document wrapper
         return tree
 
-    def __exec_among (self, module, functions, min_times, max_times):
+    def __exec_among(self, module, functions, min_times, max_times):
 
         """ Randomly execute $functions between $min and $max times """
 
-        for i in xrange (random.randint (min_times, max_times)):
+        for i in xrange(random.randint(min_times, max_times)):
             # Function names are mangled because they are "private"
-            getattr (module, "_XmlMutatorMin__" + random.choice(functions)) ()
+            getattr(module, "_XmlMutatorMin__" + random.choice(functions))()
 
-    def __serialize_xml (self, tree):
+    def __serialize_xml(self, tree):
 
         """ Serialize a XML document. Basic wrapper around lxml.tostring() """
 
         return ET.tostring(tree, with_tail=False, xml_declaration=True, encoding=tree.docinfo.encoding)
 
-    def __ver (self, version):
+    def __ver(self, version):
 
         """ Helper for displaying lxml version numbers """
 
         return ".".join(map(str, version))
 
-    def reset (self):
-    
+    def reset(self):
+
         """ Reset the mutator """
 
         self.tree = deepcopy(self.input_tree)
 
-    def init_from_string (self, input_string):
-    
+    def init_from_string(self, input_string):
+
         """ Initialize the mutator from a XML string """
 
         # Get a pointer to the top-element
@@ -97,15 +98,15 @@ class XmlMutatorMin:
         # Get a working copy
         self.tree = deepcopy(self.input_tree)
 
-    def save_to_string (self):
-    
+    def save_to_string(self):
+
         """ Return the current XML document as UTF-8 string """
 
         # Return a text version of the tree
         return self.__serialize_xml(self.tree)
 
-    def __pick_element (self, exclude_root_node = False):
-    
+    def __pick_element(self, exclude_root_node=False):
+
         """ Pick a random element from the current document """
 
         # Get a list of all elements, but nodes like PI and comments
@@ -119,7 +120,7 @@ class XmlMutatorMin:
 
         # Pick a random element
         try:
-            elem_id = random.randint (start, len(elems) - 1)
+            elem_id = random.randint(start, len(elems) - 1)
             elem = elems[elem_id]
         except ValueError:
             # Should only occurs if "exclude_root_node = True"
@@ -127,8 +128,8 @@ class XmlMutatorMin:
 
         return (elem_id, elem)
 
-    def __fuzz_attribute (self):
-    
+    def __fuzz_attribute(self):
+
         """ Fuzz (part of) an attribute value """
 
         # Select a node to modify
@@ -144,19 +145,19 @@ class XmlMutatorMin:
             return
 
         # Pick a random attribute
-        rand_attrib_id = random.randint (0, len(attribs) - 1)
+        rand_attrib_id = random.randint(0, len(attribs) - 1)
         rand_attrib = attribs[rand_attrib_id]
 
         # We have the attribute to modify
         # Get its value
-        attrib_value = rand_elem.get(rand_attrib);
+        attrib_value = rand_elem.get(rand_attrib)
         # print("- Value: " + attrib_value)
 
         # Should we work on the whole value?
         func_call = "(?P<func>[a-zA-Z:\-]+)\((?P<args>.*?)\)"
         p = re.compile(func_call)
         l = p.findall(attrib_value)
-        if random.choice((True,False)) and l:
+        if random.choice((True, False)) and l:
             # Randomly pick one the function calls
             (func, args) = random.choice(l)
             # Split by "," and randomly pick one of the arguments
@@ -236,29 +237,29 @@ class XmlMutatorMin:
         # Modify the attribute
         rand_elem.set(rand_attrib, new_value.decode("utf-8"))
 
-    def __del_node_and_children (self):
+    def __del_node_and_children(self):
 
         """ High-level minimizing mutator
             Delete a random node and its children (i.e. delete a random tree) """
 
         self.__del_node(True)
 
-    def __del_node_but_children (self):
+    def __del_node_but_children(self):
 
         """ High-level minimizing mutator
             Delete a random node but its children (i.e. link them to the parent of the deleted node) """
 
         self.__del_node(False)
 
-    def __del_node (self, delete_children):
-    
+    def __del_node(self, delete_children):
+
         """ Called by the __del_node_* mutators """
 
         # Select a node to modify (but the root one)
-        (rand_elem_id, rand_elem) = self.__pick_element (exclude_root_node = True)
+        (rand_elem_id, rand_elem) = self.__pick_element(exclude_root_node=True)
 
         # If the document includes only a top-level element
-        # Then we can't pick a element (given that "exclude_root_node = True") 
+        # Then we can't pick a element (given that "exclude_root_node = True")
 
         # Is the document deep enough?
         if rand_elem is None:
@@ -275,12 +276,12 @@ class XmlMutatorMin:
             # Link children of the random (soon to be deleted) node to its parent
             for child in rand_elem:
                 rand_elem.getparent().append(child)
-            
+
         # Remove the node
         rand_elem.getparent().remove(rand_elem)
 
-    def __del_content (self):
-    
+    def __del_content(self):
+
         """ High-level minimizing mutator
             Delete the attributes and children of a random node """
 
@@ -294,8 +295,8 @@ class XmlMutatorMin:
         # Reset the node
         rand_elem.clear()
 
-    def __del_attribute (self):
-     
+    def __del_attribute(self):
+
         """ High-level minimizing mutator
             Delete a random attribute from a random node """
 
@@ -312,7 +313,7 @@ class XmlMutatorMin:
             return
 
         # Pick a random attribute
-        rand_attrib_id = random.randint (0, len(attribs) - 1)
+        rand_attrib_id = random.randint(0, len(attribs) - 1)
         rand_attrib = attribs[rand_attrib_id]
 
         # Log something
@@ -322,8 +323,8 @@ class XmlMutatorMin:
         # Delete the attribute
         rand_elem.attrib.pop(rand_attrib)
 
-    def mutate (self, min=1, max=5):
-    
+    def mutate(self, min=1, max=5):
+
         """ Execute some high-level mutators between $min and $max times, then some medium-level ones """
 
         # High-level mutation

examples/custom_mutators/common.py

@@ -19,19 +19,22 @@ import random
 import os
 import re
 
+
 def randel(l):
     if not l:
         return None
-    return l[random.randint(0,len(l)-1)]
+    return l[random.randint(0, len(l)-1)]
+
 
 def randel_pop(l):
     if not l:
         return None
-    return l.pop(random.randint(0,len(l)-1))
+    return l.pop(random.randint(0, len(l)-1))
+
 
 def write_exc_example(data, exc):
     exc_name = re.sub(r'[^a-zA-Z0-9]', '_', repr(exc))
-    
+
     if not os.path.exists(exc_name):
         with open(exc_name, 'w') as f:
-            f.write(data)    
+            f.write(data)