Tested on Ubuntu >= 14.04.5 LTS1. Setup The implementation is based on LLVM, specifically LLVM 3.8. We also need tools like c2xml to parse headers. First, make sure that you have libxml (required for c2xml):

sudo apt-get install libxml2-dev

Next, We have created a single script, which downloads and builds all the required tools.

optional arguments: -h, --help show this help message and exit -b TARGET_BRANCH Branch (i.e. version) of the LLVM to setup. Default: release_38 e.g., release_38 -o OUTPUT_FOLDER Folder where everything needs to be setup.

Example:

python setup_drchecker.py -o drchecker_deps

To complete the setup you also need modifications to your local PATH environment variable. The setup script will give you exact changes you need to do.

2. Building This depends on the successful completion of Setup. We have a single script that builds everything, you are welcome.

cd llvm_analysis ./build.sh

3. Running This depends on the successful completion of Build. To run DR.CHECKER on kernel drivers, we need to first convert them into llvm bitcode.

3.1 Building kernel First, we need to have a buildable kernel. Which means you should be able to compile the kernel using regular build setup. i.e., make. We first capture the output of make command, from this output we extract the exact compilation command.

3.1.1 Generating output of make (or makeout.txt) Just pass V=1 and redirect the output to the file. Example:

make V=1 O=out ARCH=arm64 > makeout.txt 2>&1

NOTE: DO NOT USE MULTIPLE PROCESSES i.e., -j. Running in multi-processing mode will mess up the output file as multiple process try to write to the output file. That's it. DR.CHECKER will take care from here.

3.2 Running DR.CHECKER analysis There are several steps to run DR.CHECKER analysis, all these steps are wrapped in a single script helper_scripts/runner_scripts/run_all.py How to run:

optional arguments: -h, --help show this help message and exit -l LLVM_BC_OUT Destination directory where all the generated bitcode files should be stored. -a CHIPSET_NUM Chipset number. Valid chipset numbers are: 1(mediatek)|2(qualcomm)|3(huawei)|4(samsung) -m MAKEOUT Path to the makeout.txt file. -g COMPILER_NAME Name of the compiler used in the makeout.txt, This is needed to filter out compilation commands. Ex: aarch64-linux-android-gcc -n ARCH_NUM Destination architecture, 32 bit (1) or 64 bit (2). -o OUT Path to the out folder. This is the folder, which could be used as output directory during compiling some kernels. (Note: Not all kernels needs a separate out folder) -k KERNEL_SRC_DIR Base directory of the kernel sources. -skb Skip LLVM Build (default: not skipped). -skl Skip Dr Linker (default: not skipped). -skp Skip Parsing Headers (default: not skipped). -ske Skip Entry point identification (default: not skipped). -ski Skip Soundy Analysis (default: not skipped). -f SOUNDY_ANALYSIS_OUT Path to the output folder where the soundy analysis output should be stored.

The script builds, links and runs DR.CHECKER on all the drivers, as such might take considerable time(45 min-90 min). If you want to run DR.CHECKER manually on individual drivers, refer standalone The above script performs following tasks in a multiprocessor mode to make use of all CPU cores:

3.2.1. LLVM Build

Enabled by default.

All the bitcode files generated will be placed in the folder provided to the argument -l. This step takes considerable time, depending on the number of cores you have. So, if you had already done this step, You can skip this step by passing -skb.

This performs linking, it goes through all the bitcode files and identifies the related bitcode files that need to be linked and links them (using llvm-link) in to a consolidated bitcode file (which will be stored along side corresponding bitcode file). Similar to the above step, you can skip this step by passing -skl.

3.2.3.Parsing headers to identify entry function fields.

Enabled by default.

This step looks for the entry point declarations in the header files and stores their configuration in the file: hdr_file_config.txt under LLVM build directory. To skip: -skp

3.2.4.Identify entry points in all the consolidated bitcode files.

Enabled by default

This step identifies all the entry points across all the driver consolidated bitcode files. The output will be stored in file: entry_point_out.txt under LLVM build directory. Example of contents in the file entry_point_out.txt:

This step will run DR.CHECKER on all the entry points in the file entry_point_out.txt. The output for each entry point will be stored in the folder provided for option -f. To skip: -ski

3.2.6 Example: Now, we will show an example from the point where you have kernel sources to the point of getting vulnerability warnings. We have uploaded a mediatek kernel 33.2.A.3.123.tar.bz2. First download and extract the above file. Lets say you extracted the above file in a folder called: ~/mediatek_kernel

3.2.6.1 Building

cd ~/mediatek_kernel source ./env.sh cd kernel-3.18 # the following step may not be needed depending on the kernel mkdir out make O=out ARCH=arm64 tubads_defconfig # this following command copies all the compilation commands to makeout.txt make V=1 -j8 O=out ARCH=arm64 > makeout.txt 2>&1

3.2.6.3 Understanding the output First, all the analysis results will be in the folder: ~/mediatek_kernel/dr_checker_out (argument given to the option -f), for each entry point a .json file will be created which contains all the warnings in JSON format. These json files contain warnings organized by contexts. Second, The folder ~/mediatek_kernel/dr_checker_out/instr_warnings (w.r.t argument given to the option -f) contains warnings organized by instruction location. These warnings could be analyzed using our Visualizer. Finally, a summary of all the warnings for each entry point organized by the type will be written to the output CSV file: ~/mediatek_kernel/dr_checker_out/warnings_stats.csv (w.r.t argument given to the option -f).

3.2.7 Things to note:

3.2.7.1 Value for option -g To provide value for option -g you need to know the name of the *-gcc binary used to compile the kernel. An easy way to know this would be to grep for gcc in makeout.txt and you will see compiler commands from which you can know the *-gcc binary name. For our example above, if you do grep gcc makeout.txt for the example build, you will see lot of lines like below:

So, the value for -g should be aarch64-linux-android-gcc. If the kernel to be built is 32-bit then the binary most likely will be arm-eabi-gcc

3.2.7.2 Value for option -a Depeding on the chipset type, you need to provide corresponding number.

3.2.7.3 Value for option -o This is the path of the folder provided to the option O= for make command during kernel build. Not all kernels need a separate out path. You may build kernel by not providing an option O, in which case you SHOULD NOT provide value for that option while running run_all.py.