TaintDroid Runner


TaintDroid Runner is an extension of the TaintDroid project to automatically analyze the behaviour of Android applications in an emulated environment by parsing TaintDroid logs indicating that an application leaks privacy sensitive information or generates cost for the user.

The TaintDroid Runner project was created as part of my (Daniel Baeumges) Master's Thesis at the Ruhr-Universität Bochum. Questions and feedback regarding the TaintDroid Runner project can be sent to me directly (<first-initial><lastname> -at- gmail.com"), or to the TaintDroid users Google Groups, which I try to monitor regular.


The excerpt of my Master's thesis can be viewed and downloaded here.
The appropriate part of a short presentation can be found here.


Version 0.5

  • Make TaintDroid Runner more error resistant
    • New methods for killing processes
    • Do not ignore crashes
    • Remove possible deadlocks in pprocess usage and logging
  • Change logcat behavior
    • Use log redirection instead of direct read of logcat
New features
  • Log GSM call activites
  • New JSON mode which generates JSON main files
  • New MS mode for storing data in database

Version 0.4

  • Change multi-threading behaviour:
    Do not assign apps to threads in advance but start a thread per app (but not more than defined threads)
  • Possibility to define a maximum thread runtime after which thread is killed
New features
  • Report mode which generates a very basic HTML report containing the results
  • Calculated MD5 and Sha256 Hash for APK file
  • Allow to set properties for TaintDroid logging
  • rename utils.py to common.py
  • report_generator.py: Generate a basic HTML report 
Todos and ideas
  • Store results in database

Version 0.3

New features
  • Allow to skip simulations
  • New interactive mode
  • Prepare multi-threading
  • Logging of all network activities
  • Sent SMS are logged
  • Logging of crypto activities
Todos and ideas
  • Store results in database
  • Run multiple TaintDroid Runners in parallel

Version 0.2

New features
  • Analyze app without activity
  • Run all apps in one folder
  • Use clean environment for every run
  • Extract package out of APK
  • Better error handling and tracing
New files
  • apk_wrapper.py: Wrapper class for the .apk file extracing information out of the AndroidManifest.xml
  • utils.py: Helper class providing util methods as well as a common logger
Todos and ideas
  • Store results in database
  • Run multiple TaintDroid Runners in parallel

Version 0.1

  • Analyze one Android app and print out results
  • emulator_client.py: Wrapper file which provides access methods for running an Android emulator.
  • emulator_telnet_client.py: Wrapper file which provides access to the emulator telnet interface.
  • taintdroid_runner.py: Main class running the TaintDroid Runner.
  • taintlog_analyzer.py: Main class for parsing and analyzing the logcat outputs of the modified TaintDroid 2.3 system.
  • taintlog_json.py: Helper class defining the required log objects which are created in the modified TaintDroid 2.3 system.
Todos and ideas
  • Run all apps in one folder
  • For every application use new image files (initial environment)
  • Extract package out of APK

Use TaintDroid Runner

Usage of the TaintDroid Runner


Usage: taintdroid_runner.py [options] mode

  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -a <app>, --app=<app>
                        Set path to Android app to run in TaintDroid
  -d <directory>, --appDir=<directory>
                        Set directory in which all Android apps should be run
                        in TaintDroid
  -i <path>, --imageDirPath=<path>
                        Set path to the TaintDroid 2.3 image files zImage,
                        system.img, ramdisk.img, and sdcard.img
  -t #, --numThreads=#  Number of threads to be used
                        Maximum seconds for thread
                        First emulator port (has to be an even number)
                        Report directory in which all files are stored (date
                        is appended)
  -l <path>, --logPathSuffix=<path>
                        Set path to directory in which log and logcat files
                        should be stored
  --storeLogInFile      Set to true (1) if outputs should be logged in
                        separate file.
                        Define the maximum logcat size in kBytes (logcat is
                        ringbuffer), default is 4096kByes
  --sdkPath=<path>      Set path to Android SDK
  --avdName=<name>      Set the name of the AVD to be used
  --runHeadless         Run emulator without window.
  --numMonkeyEvents=#   Define number of monkey events to be executed (split
                        into up to 5 separate runs).
  --cleanUpImageDir     Set to false (0) if image dir should not be removed
                        after run.
  --sleepTime=<secs>    Set time to sleep during simulation.
  -v, --verbose         
  -q, --quiet     

The mode might be:
  • default
  • interactive
  • report
  • json

Without Sources

When you do not have or do not want do build the sources you need to follow these steps:
  1. Download the Android SDK
  2. Start the Android SDK Manager (from the unpacked Android SDK files start tools/android)
  3. Download the Android 2.3.3 (API 10) SDK Platform Files
  4. Create a new AVD configuration with Android 2.3.3 as base
  5. Start taintdroid_runner.py and provide the path to the Android SDK as well as the name of the AVD configuration created in step 4.
Example start command of the TaintDroid Runner:

python taintdroid_runner.py -a ~/com.test.apk \
                            -i taintdroid_images_clean \
                            --sdkPath ~/bin/android-sdk-linux_x86/ \
                            --avdName MyAndroid2.3

With Sources

If you are having your own build you also can start the TaintDroid Runner without providing an SDK path or the AVD name. As prerequisites you should have
  • put the files zImage and sdcard.img into your output build directory (e.g. ~/tdroid-2.3out/target/product/generic),
  • initialized your build environment by calling
    • . ~/tdroid-2.3/build/envsetup.sh
    • lunch 1
python taintdroid_runner.py -a ~/com.test.apk

Log files

Dependent on the provided options several log and logcat files are created.
  • without options:
    • log: no file
    • logcat: yyyyMMdd-HHmm_<apkname>_logcat.log
  • with logPathSuffix:
    • log: no file
    • logcat: <logPathSuffix>_yyyyMMdd-HHmm/<apkname>_logcat.log
  • with storeLogInFile:
    • log (main): yyyyMMdd-HHmm_taintdroid_runner_main_log.log
    • log (app): yyyyMMdd-HHmm_<apkname>_log.log
    • logcat: yyyyMMdd-HHmm_<apkname>_logcat.log
  • with storeLogInFile and logPathSuffix
    • log (main): <logPathSuffix>_yyyyMMdd-HHmm/taintdroid_runner_main_log.log
    • log (app): <logPathSuffix>_yyyyMMdd-HHmm/<apkname>_log.log
    • logcat: <logPathSuffix>_yyyyMMdd-HHmm/<apkname>_logcat.log
  • report mode
    • log (main): <reportPathSuffix>_yyyyMMdd-HHmm/taintdroid_runner_main_log.log
    • log (app): <reportPathSuffix>_yyyyMMdd-HHmm/<apkname>_log.log
    • logcat: <reportPathSuffix>_yyyyMMdd-HHmm/<apkname>_logcat.log
    • html (main): <reportPathSuffix>_yyyyMMdd-HHmm/report.html
    • html (app): <reportPathSuffix>_yyyyMMdd-HHmm/report_app_<id>.html
  • json mode
    • log (main): <reportPathSuffix>_yyyyMMdd-HHmm/taintdroid_runner_main_log.log 
    • log (app): <reportPathSuffix>_yyyyMMdd-HHmm/<apkname>_log.log
    • logcat: <reportPathSuffix>_yyyyMMdd-HHmm/<apkname>_logcat.log
    • json (main): <reportPathSuffix>_yyyyMMdd-HHmm/report.json
    • html (main): <reportPathSuffix>_yyyyMMdd-HHmm/report.html
    • html (app): <reportPathSuffix>_yyyyMMdd-HHmm/report_app_<id>.html

Get TaintDroid Runner

The TaintDroid Runner files can be downloaded in the files section or via this direct link. The archive consist of the Python files only.

In addition you need the following files coming from a modified TaintDroid 2.3 (refer to Sources):

  • ramdisk.img: Ramdisk image
  • system.img: System image
  • userdata.img: User-data disk image
  • sdcard.img: SD card image file
  • zImage: Modified kernel with ext2 support
The most recent versions of these files can be downloaded WITHOUT ANY WARRANTY here.


The sources consist of two major parts:
  1. TaintDroid Runner Python files:
    The Python files are located in a GIT repository on github named dbaeumges/taintdroid_runner.

  2. Modified TaintDroid 2.3 sources:
    To use the TaintDroid Runner modified TaintDroid 2.3 are required in order to get the correct log format. To get these sources follow the steps described in TaintDroid 2.3 Build and replace the local_manifest.xml in step 2 with the following:

      <remote name="github" fetch="git://github.com" />
      <remove-project name="platform/dalvik"/>
      <project path="dalvik" remote="github" name="dbaeumges/android_platform_dalvik" revision="taintdroid-2.3_runner" />
      <remove-project name="platform/libcore"/>
      <project path="libcore" remote="github" name="dbaeumges/android_platform_libcore" revision="taintdroid-2.3_runner" />
      <remove-project name="platform/frameworks/base"/>
      <project path="frameworks/base" remote="github" name="dbaeumges/android_platform_frameworks_base" revision="taintdroid-2.3_runner" />
      <remove-project name="platform/system/vold"/>
      <project path="system/vold" remote="github" name="TaintDroid/android_platform_system_vold" revision="taintdroid-2.3.4_r1" />

    Afterwards pull the source code:

    % cd ~/tdroid-2.3
    % repo sync
    % cd dalvik
    % git branch --track tdroid-2.3_runner github/taintdroid-2.3_runner
    % git checkout tdroid-2.3_runner
    % git pull # (just to be safe)
    % cd ..
    % cd libcore
    % git branch --track tdroid-2.3_runner github/taintdroid-2.3_runner
    % git checkout tdroid-2.3_runner
    % git pull # (just to be safe)
    % cd ..
    % cd frameworks/base
    % git branch --track tdroid-2.3_runner github/taintdroid-2.3_runner
    % git checkout tdroid-2.3_runner
    % git pull # (just to be safe)
    % cd ../..
    % cd system/vold
    % git branch --track tdroid-2.3_runner github/taintdroid-2.3.4_r1
    % git checkout tdroid-2.3_runner
    % git pull # (just to be safe)