Excavator Demo2

Description

This is a first demo of a tool, named excavator, to dig DWARF debugging information in ELF executable binaries. The source code tarball of the tool is provided along with this document. The demo applies the tool on an ARM Linux kernel, and try to reverse engineer the compilation unit corresponding to AT91SAM9 Watchdog timer (WDT) Linux driver. A testbench skeleton intended for testing the processed compilation units is also generated. The reverse engineering is limited to general code construction such as function protypes and types. No source code is not required: only an ELF executable binary file with DWARF debugging information is involved in the process. To obtain such a file for the sake of the Demo, the Linux kernel (version 4.9.207) source code was patched using File linux-4.9.207-armv7.patch, Linux building process was configured using File linux-4.9.207.config, and then Kernel was compiled using a GCC cross-compiler for ARM Cortex-A5 built using crosstool-NG. The tool configuration File used for the Demo is config.json.

The general workflow

The General workflow is presented in images/workflow.png.

.

Configure Linux building process to build a Linux kernel with debugging information

1. In Linux source tree, enter the Linux kernel configuration menu,
   $ make menuconfig
2. Enter Kernel Hacking,
   
3. Enable Kernel debugging,
   
4. Enter Compile time checks and compiler options,
   
5. Enable Compile the kernel with debug info and Generate dwarf4 debuginfo.
   

Steps of the Demo

Build the provided Linux kernel by yourself (optional step, can be skipped)

$ wget http://cdn.kernel.org/pub/linux/kernel/v4.x/linux-4.9.207.tar.xz

$ tar -xf linux-4.9.207.tar.xz

$ cd linux-4.9.207

$ patch -p1 < ../linux-4.9.207-armv7.patch

$ cp ../linux-4.9.207.config .config

$ KCFLAGS='-gstrict-dwarf' make ARCH=arm CROSS_COMPILE=arm-cortex_a5-linux-gnueabihf- vmlinux

$ cd ..

Building the tool

$ tar -xf unisim-excavator-0.2.0.tar.xz

$ cd unisim-excavator-0.2.0

$ ./configure --prefix=$(pwd)/tool

$ make

$ make install

$ cd ..

Configuring the tool (optional step, can be skipped)

The tool has a configuration file (JSON format).

Below is the configuration used for the Demo, see also File config.json:

{
    "binary" : "vmlinux",
    "sources" :
    [
        "drivers/watchdog/at91sam9_wdt.c"
    ],
    "suppress-types" :
    [
        "__builtin_*"
    ],
    "suppress-functions" :
    [
        "__compiletime_assert_*",
        "__builtin_*",
        "snprintf",
        "sprintf",
        "sscanf",
        "strcspn",
        "strncasecmp",
        "strncat",
        "vsnprintf",
        "strspn",
        "bcmp",
        "fabs",
        "strlen",
        "strncmp",
        "strncpy",
        "memcmp",
        "memmove",
        "strchr",
        "memset",
        "strrchr",
        "memchr",
        "abort"
    ],
    "output-dir" : "out",
    "verbose" : 2,
    "dwarf-html-output-dir" : "dwarf"
}

The options are:

• binary is the input ELF executable binary (with strict DWARF4 debug information, e.g. compiled with gcc -gdwarf-4 -gstrict-dwarf) to analyze (mandatory option).
• sources is the list of compilation units to process; if not specified or empty, it means all compilation units.
• suppress-types is the list of types to suppress while analysis, e.g. types to be considered as compiler builtins.
• suppress-functions is the list of functions to suppress while analysis, e.g. functions to be considered as compiler builtins.
• output-dir is the output directory of the analysis (mandatory option); the result of the analysis is a reversed engineered C source codes.
• verbose is the level of verbosity (level 2 is the default) during analysis (0:errors, 1:warnings, 2:info, 3:debug tool, 4:debug DWARF parser).
• dwarf-html-output-dir is the directory where to dump DWARF debugging information as HTML; if not specified or empty, it means no dump.

Run the tool

$ ./unisim-excavator-0.2.0/tool/bin/unisim-excavator-0.2.0 config.json

Results:

1. in Sub-directory dwarf: an HTML dump of DWARF debugging informations from File vmlinux.
2. File out/574.c: A reverse engineered C source code of Compilation Unit drivers/watchdog/at91sam9_wdt.c from File vmlinux.
3. File out/testbench.c: The source code of a generated testbench skeleton for the Compilation Unit drivers/watchdog/at91sam9_wdt.c from File vmlinux