NOTE: This page is still work in progress. Static rooting analysis should probably be integrated better in our build process which should make it easier to use.

Overview

The static rooting analysis uses a GCC plugin to dump possible callstacks that can cause GC and statically (at compile time) analyses this data for rooting hazards.

The main differences to dynamic rooting analysis are:

• Covers all compiled code at once during compile time. There's no need to actually execute these codepaths in the game.
• Setup is more complicated
• Only covers stack based rooting
• There can be false positives

Requirements

• Sixgill plugin: ​hazards-sixgill.tar.xz
• GCC version compatible with sixgill plugin: ​hazards-gcc4.7.tar.xz

Download the sixgill plugin and extract it where you like. This path will be called "/path/to/sixgill". Download the custom GCC and extract it where you like. This path will be called "/path/to/customgcc".

Setup

Generating .xdb files

The first step is to generate the .xdb files that contain all the information generated at compile time. You need to combine the information from the SpiderMonkey build and the 0 A.D. build.

1. Open a terminal
2. Set environment PATH and GCCDIR environment variables:

   PATH=/path/to/sixgill/usr/bin:$PATH
   export PATH
   GCCDIR=/path/to/customgcc/bin
   export GCCDIR
   

3. Change to the SpiderMonkey source directory and call configure. In my case I had to set the system's default include paths and library search paths because the custom GCC was compiled for another system with different include paths. The rest are just the normal flags and they aren't related to the static analysis (may be different in your case).

   cd 0ad/libraries/spidermonkey
   yves@yves-desktop:~/Projekte/0ad/libraries/source/spidermonkey/mozjs-38.0.0/js/src/build-release$ CFLAGS="-B/usr/lib/x86_64-linux-gnu -I/usr/include/x86_64-linux-gnu" CXXFLAGS="-B/usr/lib/x86_64-linux-gnu -I/usr/include/x86_64-linux-gnu" ../configure --enable-shared-js --disable-tests --enable-valgrind --with-nspr-libs="-lplds4 -lplc4 -lnspr4"  --with-nspr-cflags="-I/usr/include/nspr"  --enable-optimize --without-intl-api
   

4. Build SpiderMonkey

   yves@yves-desktop:~/Projekte/0ad/libraries/source/spidermonkey/mozjs-38.0.0/js/src/build-release$ ../devtools/rootAnalysis/run_complete --build-root=/home/yves/Projekte/0ad/libraries/source/spidermonkey/mozjs38/js/src/build-release --binaries=/path/to/sixgill/usr/bin --wrap-dir=/path/to/sixgill/usr/libexec/sixgill/scripts/wrap_gcc --buildcommand='make' --foreground .
   

5. There should be 5 .xdb files in libraries/source/spidermonkey/mozjs-38.0.0/js/src/build-release. Copy them to build/workspaces/gcc.
6. Build 0 A.D.

   yves@yves-desktop:~/Projekte/0ad/build/workspaces/gcc$ perl ../../../libraries/source/spidermonkey/mozjs-38.0.0/js/src/devtools/rootAnalysis/run_complete --build-root=/home/yves/Projekte/0ad/build/workspaces/gcc --binaries=/path/to/sixgill/usr/bin --wrap-dir=/path/to/sixgill/usr/libexec/sixgill/scripts/wrap_gcc --buildcommand='CXXFLAGS="-I/usr/include/x86_64-linux-gnu" make pyrogenesis' --foreground .
   

7. After the build is completed, the .xdb files in 0ad/build/workspaces/gcc should contain the information from the SpiderMonkey build and the 0 A.D. build.

Troubleshooting

The following logfiles are generated when running run_complete with the correct GCC and an active sixgill plugin. You can also pass --no-logs to run_complete, which will print the logs in the console directly (except basecc.log).

File	Path	Description
basecc.log	/tmp
build_xgill.log	the path specified by --build-root
build.log	the path specified by --build-root
build_err.log	the path specified by --build-root
build_manager.log	the path specified by --build-root
complete.log	the path specified by --build-root

Analyzing .xdb files

The second step is to run a series of scripts on the .xdb files generated in the previous step.

1. Create a directory that will contain the output files of the analysis. This directory will be called "/path/to/analyzedir".
2. Copy the .xdb files from 0ad/build/workspaces/gcc to /path/to/analyzedir.
3. WORKAROUND: Change line 123 in mozjs-38.0.0/js/src/devtools/rootAnalysis/analyzeRoots.js from "assert(false);" to "return false;".
4. Run the analyze script.

   @yves-desktop:~/Projekte/analyze_hazards$ python /home/yves/Projekte/0ad/libraries/source/spidermonkey/mozjs-38.0.0/js/src/devtools/rootAnalysis/analyze.py callgraph
   

You can restart analyze.py at any point. Pass --list to show the different stages, and use one of those in place of 'callgraph'. By default, it'll go from the stage you request all the way to the end.

Troubleshooting

.xdb files are key value pairs. You can use the tools in /path/to/sixgill/usr/bin to inspect the data they contain.

Command	Description	Example
xdbfind	Search and print value by key	xdbfind -plain-text something.xdb keyname
xdbkeys	List all keys	xdbkeys something.xdb

Reading the output

AnalyzeRoots.js will generate the following files. Examples are attached to this wiki page.

hazards.txt This file contains callstacks that are quite likely to be rooting hazards. It might contain false positives too.

refs.txt This file lists places where you take the address of an unrooted value. The analysis can't tell for sure if that's a hazard or not, so this file has a much higher false positive rate than hazards.txt.