Startup

---

Startup

This part is a quick start guide for setting up and running DECAF, the binary analysis platform based on QEMU. It assumes that you have some familiarity with Linux. The instructions are based on the release of DECAF shown in the github code page, running on a Ubuntu 12.04 or 18.04 distribution of Linux. We intermix instructions with explanations about utilities to give an overview of how things work.

1. Compile

1. DECAF is based on QEMU. It's useful to have a vanilla QEMU for testing and image development. Also, you need to install some stuff to compile qemu/decaf. sudo apt-get install qemu sudo apt-get build-dep qemu

2. Before compile, you need to install the following libraries. ```

   For the BFD library:

   sudo apt-get install binutils-dev

   For the boost library:

   sudo apt-get install libboost-all-dev ```

3. Configure&Make

   DECAF has three basic settings-TCG tainting, VMI, TCG IR logging. You can enable/disable at the configuration step. By default, VMI is enabled and TCG tainting and TCG IR logging is disabled. ```

   go to the root directory of DECAF's source folder.

   ./configure make ```

   Enable TCG tainting ```

   go to the root directory of DECAF's source folder.

   ./configure --enable-tcg-taint make ```

   Enable TCG IR logging ```

   go to the root directory of DECAF's source folder

   ./configure --enable-tcg-ir-log make ```

   Disable VMI. VMI is enabled by default. If you disable it, DECAF cannot retrieve os-level semantics although you have guest driver installed because we have removed the support for guest driver(TEMU does VMI this way). ```

   go to the root directory of DECAF's source folder.

   ./configure --disable-vmi make ```

   2. Create a new VM

While QEMU itself is compatible with almost any guest OS that runs on x86 hardware, DECAF requires more knowledge about the OS to bridge the semantic gap and provide information about OS abstractions like processes. DECAF currently supports Windows XP, Windows 7 and Linux, in order to use our tool, user has to have a working qemu image of the operating system. As how to make a qemu image,please see QCOW2 image Format.

It's very slow to install an image using QEMU. You can try VirtualBox to create a QCOW format virtual disk and install OS image. QEMU/DECAF can directly load that QCOW image without any modifications.

1. If you have a vmdk image(used by vmware),you can convert it to qcow2 format by: qemu-img convert win2kpro.vmdk -O qcow win2kpro.img
2. if you have a vdi image(used by virtualBox),yo can convert it to qcow2 format by: VBoxManage clonehd --format RAW img.vdi img.raw qemu-img convert -f raw ubuntu.img -O qcow2 ubuntu.qcow
3. With the new VMI support, guest driver is no longer needed by DECAF.Image created from vmware/virtualbox may not work for the new VMI. SO it's better to create an image from install file or have vmware/virtualbox drivers uninstalled before converted to qemu image. If the VMI doesn't work, please see discussion.

3. VMI configuration for Linux

The configuration is for Linux only. There is no extra configuration for Windows. 1. Compile and insert kernel module

Copy procinfo.c and Makefile under [decaf_path]/shared/kernelinfo/procinfo_generic/ into some directory in the guest OS. # in guest OS cd [path of procinfo.c and Makefile] make sudo insmod ./procinfo.ko # It's OK if you see "Operation not permitted" since this module only print some message. dmesg 1. Update procinfo.ini You will see something like this. [20451.579763] strName = 3.2.0-37-generic [20451.579764] init_task_addr = 3246178336 [20451.579765] init_task_size = 3236 ... [20451.579787] ti_task = 0 Remove the leading time and brackets. Copy the rest content into [decaf_path]/shared/kernelinfo/procinfo_generic/procinfo.ini. Add a new section for it. Increment info.total at the beginning of procinfo.ini.

e.g.

  [info]
  total = 7
  ...
  [7]
  strName = 3.2.0-37-generic
  init_task_addr  = 3246178336
  init_task_size  = 3236
  ...
  ti_task         = 0

  ;DON'T FORGET TO UPDATE info.total

1. Possible errors

   • UTS_RELEASE is not defined or utsrelease.h cannot be found. Define UTS_RELEASE as a unique string by yourself.

2. Configuration for shared library (optional)

   To hook library functions, you need to configure the offsets. For each guest OS, there is a library configuration file for it in [decaf_path]/shared/kernelinfo/procinfo_generic/lib_conf/]. The file name of the configuration file is [strName].ini. In a library configuration file, there is a section for each shared library file. In each section, there is a decaf_conf_libpath field for the shared library file name. decaf_conf_libpath is the file name, don't include any path.

   decaf_conf_libpath = libc-2.13.so
   decaf_conf_libpath = /usr/lib/libc-2.13.so

   For each function, there is also a filed. The field name is the name of the function. The field value is the offset. The field name and value can be obtainted using the following command in guest OS. You may need to adjust the command according to your environment.

     objdump -T [path_of_shared_library_in_guest_OS] | awk '/\.text/ && $6 !~ /\(.*\)/ {printf("%-30s= %d\n",$7,"0x"$1)}'
   

4. Startup the Virtual Machine

Now you have get everything ready, the next step is to start the emulator and run the virtual machine.

1. Go to DECAF/trunk/i386-­softmmu

2. Run the following command

     ./qemu-­system­-i386 -­monitor stdio ­-m 512 ­-netdev user,id=mynet ­-device rtl8139,netdev=mynet “YOUR_IMAGE”
   

3. If you want to use snapshot function, you can use ­snapshot option

5. compile and load plugins

DECAF provides many interfaces to trace internal events of the guest operating system. You can write your analysis plugins using these interfaces. To learn how to write plugins, plugin samples is the best place to start with. Download plugin samples. Take callbacktests plugin as an example.

1. compile plugins

     cd ./callbacktests
     #set decaf location
     ./configure --decaf-path=root directory of decaf
     make
   

2. load plugins

     #start virtual machine, change directory to (root directory of decaf)/i386-softmmu/
      ./qemu-­system­-i386 -­monitor stdio -­m 512 ­-netdev user,id=mynet -­device rtl8139,netdev=mynet “YOUR_IMAGE”
     #check available cmds
     help
     #load plugins
     load_plugin XXX/callbacktests/callbacktests.so
   

3. trace program

     #trace a specific program
     do_callbacktests calc.exe
     #now you can start calc.exe in the guest operating system to see the results. 
   

6. Troubleshooting

This section describes some problems users have experienced when using DECAF, along with the most common causes of these problems.If you have any other questions,please post them on Forum

1. After start Decaf, the terminal says " vnc server running on 127.0.0.1 7 5900" and there is no running guest os shown up.

   • This is because SDL library is not properly installed. You just need to reinstall SDL.

2. When compile plugin, it can not find lcrypto.

   • you need to make a link to lcrypto.xxx.so to lcrypto.so. If you can not find lcrypto.xxx.so library,just install ssh.