speedy unicorn

Author: domenukk

AFLplusplus

@@ -0,0 +1,92 @@
+# UCF Development
+
+In this markdown file, we collect some tips about debugging and developing ucf further.
+
+## Typing
+
+For good measure, try to add type hints wherever you are.
+We currently develop with backwards compatible python3 in mind.
+Functions may be annotated inline `dev like(this: str) -> None:`.
+However to annotate types, we prefer to add type comments (PEP something) `like = this # type: str`.
+
+## Debugging
+
+There are different layers to be debugged.
+The python code and afl++/unicorn code. 
+
+### Python Debugging
+
+Debugging the python stuff should be easy. Use your favorite pdb interface or pycharm to step thorugh the code, or simply sprinkle printfs around.
+
+### Unicorn Debugging
+
+Debugging bugs in unicorn is a different beast.
+Sometimes it's necessary to debug `libunicorn.so` with the real AFL forkserver attached.
+A possible best way is via GDB.
+
+#### Building Unicorn With Debug Symbols
+
+This is not super straight forward, but easy enough. We do it by following these steps.
+For this, it's adviced to build unicorn with debug symbols.
+Change dir to unicorn.
+```cd ./AFLplusplus/unicorn_mode/unicorn```
+There, edit `config.mk` and change `UNICORN_DEBUG` to `UNICORN_DEBUG ?= yes`.
+
+Afterwards, rebuild Unicorn using something like
+```make clean -j8; make -j8```
+
+#### Starting the debugger:
+
+With libunicorn.so built with symbols, let's start ucf in a debugger.
+```bash
+UCF_DEBUG_SLEEP_BEFORE_FORK=10 UCF_DEBUG_START_GDB=1 ucf fuzz -P -c ./unicorefuzz_cifs/config.py
+```
+`UCF_DEBUG_START_GDB=1` will load ucf inside afl-fuzz inside gdb.
+`UCF_DEBUG_SLEEP_BEFORE_FORK=10` will add a sleep of 10 seconds right before the afl-unicorn forkserver starts. This will be important in the next step
+
+### Debugging unicorn, as child of afl
+
+Inside the gdb shell, make sure you follow the child AFL will spawn for the fork server:
+
+```
+set follow-fork-mode child
+```
+
+And break whenever afl execs python3/ucf:
+```
+catch exec
+```
+
+Then run afl using `r`.
+
+After the catchpoint triggers, make sure you don't follow random python or avatar threads:
+```
+set follow-fork-mode parent
+```
+and continue (`c`) until you see output like 
+```
+[d] Sleeping. Forkserver will start in 10 seconds.
+```
+Immediately hit `ctrl+c` to break.
+
+Now start setting your desired breakpoints, for example `b uc_emu_start` or `b afl_forkserver` and then continue (`c`).
+
+Using `set follow-fork-mode child` again at the right time (i.e. right before the `fork()` in `afl-unicorn-cpu-inl.h`) allows debugging the actual unicorn execution.
+
+Another, kinda tedious, way, to debug, is to keep the parent process around using (gdb non-stop mode)[https://www-zeuthen.desy.de/unix/unixguide/infohtml/gdb/Non_002dStop-Mode.html] and setting `set detach-on-fork off`, for example:
+
+```bash
+gef➤  set target-async 1
+gef➤  set pagination off 
+gef➤  set non-stop on
+gef➤  set detach-on-fork off
+gef➤  catch ex
+gef➤  catch exec 
+gef➤  r
+gef➤  c -a
+gef➤  info threads
+gef➤  thread xyz
+...
+```
+
+Happy debugging.

DEVELOPMENT.md

@@ -123,7 +123,7 @@ It's generally a good idea to nop out kprintf or kernel printing functionality i
 
 ## Troubleshooting
 
-If you got trouble running unicorefuzz, follow these rulse, worst case feel free to reach out to us, for example to @domenuk on twitter.
+If you got trouble running unicorefuzz, follow these rulse, worst case feel free to reach out to us, for example to @domenuk on twitter. For some notes on debugging and developing ucf and afl-unicorn further, read [DEVELOPMENT.md](./DEVELOPMENT.md)
 
 ### No instrumentation
 

README.md

@@ -16,6 +16,17 @@ from unicorefuzz.probe_wrapper import ProbeWrapper
 from unicorefuzz.unicorefuzz import Unicorefuzz
 
 
+def getenv_default(envname: str, default: str) -> str:
+    """
+    Returns the environment variable if set, else returns the default
+    :param envname: name of env variable to get
+    :param default: what to return if envname is not set
+    :return env variable or default if not set
+    """
+    env = os.getenv(envname)
+    return env if env is not None else default
+
+
 def load_conf(args: argparse.Namespace, silent: bool = False) -> Any:
     """
     Loads the config from args
@@ -30,6 +41,7 @@ def load_conf(args: argparse.Namespace, silent: bool = False) -> Any:
 def print_spec(args: argparse.Namespace) -> None:
     """
     Outputs expected config.py spec.
+    :param args: the arguments
     """
     print(serialize_spec(UNICOREFUZZ_SPEC))
 
@@ -109,28 +121,62 @@ def fuzz(args: argparse.Namespace) -> None:
 
     wait_for_wrapper(args, ucf)
 
-    afl = os.path.join(ucf.afl_path, "afl-fuzz")
-    ucf_main = os.path.join(ucf.config.UNICORE_PATH, "ucf")
+    config_path = ucf.config.path
 
+    # Path to AFL: Should usually(tm) point to the AFLplusplus subrepo
+    afl_path = getenv_default("AFL_PATH", ucf.afl_path)
+    # Libunicorn_path: Unicorn allows us to switch out the native lib without reinstalling its python bindings.
+    libunicorn_path = getenv_default("LIBUNICORN_PATH", ucf.libunicorn_path)
     # AFL_COMPCONV_LEVEL=2 is an awesome addition to afl-unicorn, and definitely the one you want :)
-    # See afl++ repo
-    env = "PATH={}:$PATH LIBUNICORN_PATH={} AFL_COMPCOV_LEVEL=2".format(
-        ucf.afl_path, ucf.libunicorn_path
+    # See afl++ repo for further infos
+    afl_compcov_level = getenv_default("AFL_COMPCOV_LEVEL", "2")
+
+    # TODO: forward all additional parameters to AFL directly, instead.
+    afl_timeout = getenv_default("AFL_TIMEOUT", "4000+")
+
+    emu_params = ""
+    if args.trace:
+        if not args.print_outputs:
+            raise ValueError(
+                "Won't accept debug option -t without -P. Slowdown without benefit."
+            )
+        emu_params += "-t "
+
+    afl = os.path.join(afl_path, "afl-fuzz")
+    ucf_main = os.path.join(ucf.config.UNICORE_PATH, "ucf")
+
+    if os.getenv("UCF_DEBUG_START_GDB"):
+        print("[d] UCF_DEBUG_START_GDB set. Starting GDB, raising AFL timeouts.")
+        afl_timeout = "99999999+"
+        afl = "{gdb} {afl} --args {afl}".format(gdb=ucf.config.GDB_PATH, afl=afl)
+
+    env = 'PATH="{}:$PATH" LIBUNICORN_PATH="{}" AFL_COMPCOV_LEVEL="{}"'.format(
+        afl_path, libunicorn_path, afl_compcov_level
     )
     if args.print_outputs:
         env = "{} AFL_DEBUG_CHILD_OUTPUT=1 ".format(env)
-    run = "{env} {afl} -U -m none -i {afl_in} -o {afl_out} -t 4000+ {mode} -- python3 {ucf_main} emu @@ || exit 1".format(
-        env=env,
-        afl=afl,
-        afl_in=afl_inputs,
-        afl_out=ucf.config.AFL_OUTPUTS,
-        mode=mode,
-        id=id,
-        ucf_main=ucf_main,
+    run = (
+        "{env} {afl} -U -m none -i {afl_in} -o {afl_out} -t {afl_timeout} {mode} "
+        "-- python3 {ucf_main} emu {emu_params} -c {config_path} @@ || exit 1".format(
+            env=env,
+            afl=afl,
+            afl_in=afl_inputs,
+            afl_out=ucf.config.AFL_OUTPUTS,
+            afl_timeout=afl_timeout,
+            mode=mode,
+            id=id,
+            ucf_main=ucf_main,
+            emu_params=emu_params,
+            config_path=config_path,
+        )
     )
     if args.print_outputs:
         print("[*] Starting: ", run)
-    os.system(run)
+    if os.getenv("UCF_DEBUG_PRINT_COMMAND_ONLY"):
+        print("[d] ucf: Would execute:\n")
+        print(run)
+    else:
+        os.system(run)
 
 
 def kernel_setup(args: argparse.Namespace) -> None:
@@ -238,6 +284,13 @@ if __name__ == "__main__":
         action="store_true",
         help="When fuzing, print all child output (for debug)",
     )
+    sub_fuzz.add_argument(
+        "-t",
+        "--trace",
+        default=False,
+        action="store_true",
+        help="Enables debug tracing for children. Slow. Only useful with -P.",
+    )
 
     sub_await = create_subparser(subparsers, "await", wait_for_wrapper)
     sub_afl_path = create_subparser(subparsers, "afl-path", print_afl_path)

ucf

@@ -16,7 +16,8 @@
 )  # other types are not supported, sorry...
 
 from avatar2 import Avatar, Target, X86
-from sh import which
+
+# from sh import which
 from unicorn import unicorn
 
 import unicorefuzz.unicorefuzz
@@ -112,22 +113,29 @@ def init_avatar_target(ucf: Unicorefuzz, avatar: Avatar) -> Target:
     Optional(
         "WORKDIR",
         str,
-        os.path.join(os.getcwd(), "unicore_workdir"),
+        lambda config: os.path.join(config.folder, "unicore_workdir"),
         "Path to UCF workdir to store state etc.",
     ),
-    Optional("GDB_PATH", str, which("gdb"), "The path GDB lives at"),
+    Optional(
+        "GDB_PATH", str, "gdb", "The path GDB lives at"
+    ),  # which("gdb"), "The path GDB lives at"),
     Optional(
         "UNICORE_PATH",
         str,
-        os.path.dirname(os.path.abspath(os.path.join(unicorefuzz.__file__, ".."))),
+        os.path.dirname(os.path.dirname(os.path.abspath(unicorefuzz.__file__))),
         "Custom path of Unicore installation",
     ),
-    Required("AFL_INPUTS", str, "The seed directory to use for fuzzing"),
+    Optional(
+        "AFL_INPUTS",
+        Union[str, None],
+        lambda config: os.path.join(config.folder, "afl_inputs"),
+        "The seed directory to use for fuzzing",
+    ),
     Optional(
         "AFL_OUTPUTS",
         Union[str, None],
-        lambda config: os.path.join(config.UNICORE_PATH, "afl_output"),
-        "AFL output directory to use for fuzzing (default will be inside WORKDIR)",
+        lambda config: os.path.join(config.folder, "afl_outputs"),
+        "AFL output directory to use for fuzzing (default will be at location of config.py)",
     ),
     Optional("AFL_DICT", Union[str, None], None, "AFL dictionary to use for fuzzing"),
     Optional(
@@ -367,6 +375,11 @@ def load_config(path: str, silent: bool = False) -> ModuleType:
     """
     path = os.path.abspath(path)
     config = import_py("unicoreconfig", path, silent=silent)
+    # path of the actual config file
+    config.path = os.path.abspath(path)  # type: str
+    config.filename = os.path.basename(config.path)  # type: str
+    # config.folder is the folder containing the config
+    config.folder = os.path.dirname(config.path)  # type: str
     apply_spec(config, UNICOREFUZZ_SPEC, silent=silent)
     return config
 

unicorefuzz/configspec.py

@@ -19,8 +19,8 @@
     X64,
     uc_get_pc,
     uc_reg_const,
+    uc_forkserver_init,
 )
-from unicorefuzz.x64utils import syscall_exit_hook
 
 
 def unicorn_debug_instruction(
@@ -161,24 +161,15 @@ def uc_init(
         # On error: map memory, add exits.
         uc.hook_add(UC_HOOK_MEM_UNMAPPED, unicorn_debug_mem_invalid_access, self)
 
-        if len(exits) > 1:
-            # unicorn supports a single exit only (using the length param).
-            # We'll path the binary on load if we have need to support more.
-            if self.arch == X64:
-                uc.hook_add(
-                    UC_HOOK_INSN,
-                    syscall_exit_hook,
-                    user_data=(exits, os._exit),
-                    arg1=UC_X86_INS_SYSCALL,
-                )
-            else:
-                # TODO: (Fast) solution for X86, ARM, ...
-                raise Exception(
-                    "Multiple exits not yet supported for arch {}".format(self.arch)
-                )
-
-        # starts the afl forkserver
-        self.uc_start_forkserver(uc)
+        # Last chance to hook before forkserver starts (if running as afl child)
+        debug_sleep = os.getenv("UCF_DEBUG_SLEEP_BEFORE_FORK")
+        if debug_sleep:
+            print(
+                "[d] Sleeping. Forkserver will start in {} seconds.".format(debug_sleep)
+            )
+            time.sleep(float(debug_sleep))
+        # starts the afl forkserver. Won't fork if afl is not around.
+        self.uc_start_forkserver(uc, exits)
 
         input_file = open(input_file, "rb")  # load afl's input
         input = input_file.read()
@@ -268,7 +259,7 @@ def map_known_mem(self, uc: Uc):
                 except Exception:
                     pass
 
-    def uc_start_forkserver(self, uc: Uc):
+    def uc_start_forkserver(self, uc: Uc, exits: List[int]):
         """
         Starts the forkserver by executing an instruction on some scratch register
         :param uc: The unicorn to fork
@@ -298,6 +289,8 @@ def uc_start_forkserver(self, uc: Uc):
             uc.mem_write(scratch_addr, arch.insn_nop)
             uc.emu_start(scratch_addr, until=0, count=1)
 
+        uc_forkserver_init(uc, exits)
+
     def _raise_if_reject(self, base_address: int, dump_file_name: str) -> None:
         """
         If dump_file_name + REJECTED_ENDING exists, raises exception

unicorefuzz/harness.py

@@ -78,6 +78,15 @@
     "armbe": ARMBE,
 }
 
+# emulate from @begin, and stop when reaching address @until
+def uc_forkserver_init(uc: Uc, exits: List[int]) -> None:
+    import ctypes
+    from unicorn import unicorn, UC_ERR_OK, UcError
+
+    exit_count = len(exits)
+    unicorn._uc.uc_afl_forkserver_init(
+        uc._uch, ctypes.c_size_t(exit_count), (ctypes.c_uint64 * exit_count)(*exits)
+    )
 
 def regs_from_unicorn(arch: Architecture) -> List[str]:
     """
@@ -157,7 +166,8 @@ def wait_for_probe_wrapper(self) -> None:
         Blocks until the request folder gets available
         """
         while not os.path.exists(self.requestdir):
-            print("[.] Waiting for probewrapper to be available...")
+            print("[*] Waiting for probewrapper to be available...")
+            print("    ^-> UCF workdir is {}".format(self.config.WORKDIR))
             time.sleep(PROBE_WRAPPER_WAIT_SECS)
 
     def calculate_exits(self, entry: int) -> List[int]: