/stigma

Stigma instruments the Smali assembly code of commodity Android applications in order to implement dynamic information flow tracking.

Primary LanguageSmaliGNU General Public License v3.0GPL-3.0

Stigma

Stigma is a framework for modifying / instrumenting commodity Android applications. It instruments the Smali assembly code of a given .APK file in and runs any provided plugins which specify the exact changes (if any) that will be made. Currently, there are two (first party) plugins. One implements dynamic information flow tracking to track the use of sensitive information such as IMEI number, GPS location information, and the device phone number. The other carries out Object Extraction on the APK in question, allowing for a more general-purpose use for Stigma. Stigma is intended to be used as a toolkit to modify android apps for future research projects.

Table of Contents

  1. Installing Dependencies
  2. Optional Dependencies
  3. Usage
  4. Limitations
  5. Utilities and Auxiliary Programs

Installing Dependencies

  1. Have one of the following Operating Systems: Linux, MacOS or Windows environment
  2. Have python3 installed
  3. Install apktool (available in Ubuntu repository apt install apktool and here: https://ibotpeaches.github.io/Apktool/)
  4. Install openjdk-11-jdk or newer (latest version available at https://docs.microsoft.com/en-us/java/openjdk/download)
    • keytool (provided by above Ubuntu package and install)
    • jarsigner (provided by above Ubuntu package and install)
  5. Install adb (available in Ubuntu repository apt install adb and in the homebrew repository brew install android-platform-tools As well as https://www.lifewire.com/android-debug-bridge-adb-4149410)
  6. Install aapt (available in Ubuntu repository apt install aapt and at https://developer.android.com/studio/command-line/aapt2#download_aapt2)
  7. Install networkx version 2.5.1 (we recommend installing via pip3; see below). Available in Ubuntu repository apt install python3-networkx Networkx source code is available here: https://github.com/networkx/networkx
  8. Install matplotlib version 3.1.2 (we recommend installing via pip3; see below). Available in Ubuntu repository apt install python3-matplotlib Matplotlib source code is available here: https://matplotlib.org/
  9. Android Build Tools (build-tools) version 32.0.0 (ref). Android does not distribute Build Tools individually so the one have to install the Android SDK in which Build Tools are included. The Android SDK is available via the Android Studio SDK Manager. After installing the SDK from the SDK Manager in Android Studio, you also need to put the path including apksigner into your PATH environment variable. To do this,
    1. Find your Android SDK root directory.
      • On macOS, this is typically at ~/Library/Android/sdk.
      • On Windows, this is typically at C:\Users\YOUR_USERNAME\AppData\Local\Android\Sdk.
      • On Linux, this is typically at ~/Android/Sdk.
      • Check Android Studio's SDK Manager settings to confirm.
    2. Find the build-tools directory under your Android SDK root directory.
      • On macOS, this is typically at ~/Library/Android/sdk/build-tools/32.0.0.
      • On Windows, this is typically at C:\Users\YOUR_USERNAME\AppData\Local\Android\Sdk\build-tools\32.0.0.
      • On Linux, this is typically at ~/Android/Sdk/build-tools/32.0.0.
    3. Add the build-tools directory to your PATH environment variable.
      • On macOS, you can add export PATH=$PATH:~/Library/Android/sdk/build-tools/32.0.0 to your ~/.bash_profile or your shell's equivalent configuration file.
      • On Windows, add C:\Users\YOUR_USERNAME\AppData\Local\Android\Sdk\build-tools\32.0.0 to your PATH environment variable.
      • On Linux, add export PATH=$PATH:~/Android/Sdk/build-tools/32.0.0 to your ~/.bashrc, ~/.profile, ~/.bash_profile, or your shell's equivalent configuration file.

Recommended installation method for networkx and matplotlib is to use pip3. Enter the following on the command line: pip3 install networkx pip3 install matplotlib

Optional Dependencies

  • Android Studio - to view logcat easily (available at https://developer.android.com/studio)
  • pydot version 1.2.3 python3 module - to see control flow graphs ( ControlFlowGraph.show() ) (available in Ubuntu repository under python3-pydot)
  • pip3 - to install other dependencies easily (available in Ubuntu repository under python-pip3). If you're running python 3.4+, you automatically have pip3 and hence, do not need to install it.

Usage

Obtaining a modified APK file

Download an APK file to be run through Stigma. We recommend downloading from https://www.apkmirror.com or https://f-droid.org.

Change the working directory to the folder containing Stigma.py by entering the following on the command line:
cd path/to/folder/containing/stigma

Next, to run Stigma, do:
python3 Stigma.py /path/to/application.apk

A new APK file should be generated (and signed): Tracked_application.apk

Running modified APK file on your Android Phone

Ensure that developer options are turned on (run-through below). Additionally, ensure adb is downloaded and on PATH (run-through below).

Provide wired connection of Android Phone with computer containing Stigma. Ensure adb recognizes Android Phone by entering the following on the command line:

adb devices

Install / run the modified APK:

adb install -r Tracked_application.apk

The "tracked" version of the application will monitor the use of sensitive information (e.g., GPS coordinates) using the aforementioned first party plugin. In the tracked version, if that sensitive information is transmitted over a network connection such as WiFi (i.e., "leaked") by the app, there will be an entry made in the Android logging system: logcat. That entry will have the tag STIGMA and a short message indicating the nature of the event, e.g.,

STIGMA, LEAK via WRITE() OCCURING!

The user can then check the logcat for such STIGMA messages using Android Studio or adb logcat on computer connected to the device running the app.

To stress-test the modified APK file and obtain potential logcat entries, run the Monkey program (sample script present in monkey-basic.sh). Replace "edu.fandm.novak" with package name of the app in question. Search for the app on Google Play Store, obtain the package name from the url (present after "?id=")

Enabling Developer Options on Android Phone

The following tutorial is on an OPPO A96. Options will be similar across the board for other Android phones.

In Settings, open "About Phone":

Open Version:

Tap on Build number 7 times. You will eventually receive a confirmation for Developer mode, similar to the one shown below:

Setting the PATH environment variables (Windows only)

Set up both adb and the openjdk tools (keytool and jarsigner) as PATH environment variables, with the following tutorial showing a specific example for the openjdk tools.

In the taskbar, search for and select "Edit the system environment variables":

Select "Environmental Variables...":

In the User variables, choose to "Edit" your "Path" variable:

"Browse" and locate the folder containing your install of openjdk, and hence its "bin" folder, which contains both "keytool" and "jarsigner":

Limitations

Stigma has many limitations. It can only track very limited sources of sensitive information (GPS, IMEI, Device Phone Number) and it can lose track of that sensitive information as the target application operates. Additionally, the detection of network connections / transmission is very primitive and may not catch many instances. Extensive future research and improvments are ongoing.

Stigma is currently "beta" software. Numerous bugs and limitations exist, which limit broad compatibility with many Android apps. It is intended to be a tool for computer science researchers working in (a) smali byte-code instrumentation or (b) dynamic information flow tracking.

Utilities and Auxiliary Programs

  • stigma/count_pools.sh - Bash command line utility for counting the references to strings, types, fields, and methods. Requires the installation of the smali command line tool.

  • stigma/valid_smali_instructions.txt and stigma/ValidSmaliInstrunctions.py comprehensive collection of all valid smali opcode names.

  • stigma/app_check_eval.py utility that searches for small collection of likely source function calls. Takes a path to a folder (containing APKs) as input.