ProbeDroid is a dynamic Java code instrumentation kit for Android application. It provides APIs for developers to craft their own instrumentation tools. Thus they can trace, profile, or alter the runtime behavior of an interested application. Essentially, Java method is the basic instrumentation unit. To manipulate the interested methods, developers should override the template instrumentation gadgets and register them to hook interested methods. During runtime, when those methods are invoked, the control flow is diverted to the gadgets. And it is the timing to manipulate the boxed method input arguments and return value. In the current stage, ProbeDroid targets on Android 5.0 and above. To build ProbeDroid kit, developers just pull the package from GitHub and follow the build commands. Android source tree is not required.

• Dynamic Java method instrumentation kit for Android app
  • Java library as integration interface for developers
  • Customizable instrumentation gadgets to fit different applications
  • Modifiable method input and output to alter app behavior
• Direct build procedure without Android source dependency
  • Pulling the GitHub source and following the document
• Succinct deployment without customized ROM or system apps
  • Only ProbeDroid engine and developers' instrumentation package are required

• Cannot instrument abstract and native methods
• Currently only supporting Android 5.0 and the devices based on Intel x86 ISA
• Not recommended to deploy on real device

<img src="https://github.com/ZSShen/ProbeDroid/blob/master/res/ProbeDroidOverview.png"/width="750px">

• Android SDK
• Android NDK
• Apache Ant

We need Android NDK and Apache Ant to build ProbeDroid Runtime.

The ProbeDroid Runtime is composed of the Launcher and the Engine:

• Launcher - Used to inject the engine and the custom instrumentation package into the target process.
• Engine - Used to marshal the control flow between Android Runtime and the instrumentation package.

The frequently used path name identifiers:

• PATH_IN_HOST - The absolute path storing ProbeDroid Runtime source in your host machine.

1. Switch to PATH_IN_HOST/launcher/jni, and type:

   $ ndk-build
   

   The launcher executable should reside in PATH_IN_HOST/launcher/libs/x86/launcher.

1. Switch to PATH_IN_HOST/engine/jni, and type:

   $ ndk-build
   

   The native library should reside in PATH_IN_HOST/engine/libs/x86/libProbeDroid.so.

2. Switch to PATH_IN_HOST/engine, and type:

   $ ant compile
   $ ant build-jar
   

   The java library jar should reside in PATH_IN_HOST/engine/ProbeDroid.jar.

We recommend you to apply Android Studio for development.

1. Create an Android Studio project. The API level should be 21.

2. Import the library jar ProbeDroid.jar into the project.

3. Develop your own instrumentation tool with the following resource:

   1. Refer to JavaDoc for the usage of ProbeDroid API.
   2. Some Sample Tools are provided.

4. Compile the project as android APK.

For the detailed development information, please refer to the wiki page How to Develop Instrumentation Package.

We need Android SDK to create the virtual device.

The frequently used path name identifiers:

• PATH_IN_HOST - The absolute path storing ProbeDroid Runtime source in your host machine.
• PATH_IN_DEVICE - The working directory in your experiment device. /data/local/tmp is recommended.
• PATH_YOUR_PACKAGE - The path storing your instrumentation package.

1. Create a virtual device with Intel x86 ISA and API level 21.

2. Boot up the virtual device.

3. Turn off the SEAndroid mandatory access control:

   $ su 0 setenforce 0
   

1. Move the ProbeDroid launcher to the experiment device:

   $ adb push PATH_IN_HOST/launcher/libs/x86/launcher PATH_IN_DEVICE/
   $ chmod a+x PATH_IN_DEVICE/launcher
   

2. Move the ProbeDroid engine to the experiment device:

   $ adb push PATH_IN_HOST/engine/libs/x86/libProbeDroid.so PATH_IN_DEVICE/
   $ chmod a+x PATH_IN_DEVICE/libProbeDroid.so
   

1. Move your instrumentation package to the experiment device:

   $ adb push PATH_YOUR_PACKAGE PATH_IN_DEVICE
   

1. Run the ProbeDroid launcher.

    Usage: ./launcher
    --app [-a] APPNAME (The package name (or keyword) of the target app)
    --lib [-l] LIBPATH (The *absolute path name* of libProbeDroid.so)
    --module [-m] MODULEPATH (The *absolute path name* of your instrumentation package)
    --class [-c] CLASSNAME (The *fully qualified main class name* of your instrumentation package)
   

2. Monitor the message spewed by logcat daemon.

For the detailed deployment information, please refer to the wiki page How to Start Instrumentation.

Click the picture to view the demo vedio

Click the picture to view the demo vedio

Except for the following source code:

• android/art/runtime/, common/log.*, common/stringprintf.*, common/utf.*, and common/macros.h subtrees belong to AOSP, which are licensed under Apache v2.0.
• common/libffi/ subtree belongs to libffi, which is licensed under MIT.

All the source code are licensed under MIT. See COPYING for details.

Please contact me via the mail andy.zsshen@gmail.com .
Note that the kit is still under construction. Contribution and bug report is desired.