This repository contains the sources of MutaFlow as well as additional files to run MutaFlow. Initially, the project was named DroidMutant and there still exist some naming artifacts in the repository.
MutaFlow is a lightweight mutation-based analysis that systematically mutates dynamic values returned by sensitive sources to assess whether the mutation changes the values passed to sensitive sinks. If so, a flow between source and sink is found. In contrast to existing techniques, mutation-based flow analysis does not attempt to identify the specific path of the flow and is thus resilient to obfuscation.
The paper describing MutaFlow in more detail can be found here: https://dl.acm.org/citation.cfm?id=3155598&CFID=1005478616&CFTOKEN=50031448
- Java
- Python
- Gradle
- Android ADB (make sure adb can be called from within scripts)
- Android AAPT
- android.jar (can for example be obtained from the Android installation folder, i.e. "Android/sdk/platforms/android-*/android.jar")
The tool was tested under MacOS but should also work with Linux.
In the file "DroidMutantCode/Runner/src/main/java/Runner.java" the variable "pathToAAPT" needs to be set to your Android build tools.
Run the "install.sh" script and follow the instructions.
If the build fails after "downloading soot" is shown, soot was likely not be able to download.
If the soot jar is not downloaded, find a "sootclasses-trunk-jar-with-dependencies.jar" online and replace the link to the jar in the buildscript "DroidMutantCode/Instrumenter/build.gradle".
The install folder can be used anywhere on the system. Before each usage, check that the SootOutput and AppOut folders are empty. The "cleanup.sh" script cleans the install folder if necessary.
In "SignAndAlign.sh" you need to set "ZIPALIGNHOME" to the "zipalign" of Android and "PATH_TO_DEBUG_KEY" to your Android debugkey.
After installing and configuring all paths, connect a device or start the emulator. Put one or more APK-Files in the "apk" folder. Then run the "analyze_application.sh" script. This instruments the apks, stores them in the "instrout" folder, then signs and aligns them, executes them on the devices, stores the output in the "AppOutSave" folder, then starts the "startParser" script. This script calculates the raw flows and stores them in the "AppOutSave" folder. Subsequently the "FlowExtractor.jar" is started which generates the "FoundFlows.csv", a csv file which contains the found flows.
The next chapters describe the steps to take in more detail to make adaptions of steps easier.
First the application needs to be instrumented, this is done by starting the python script "instrument_parallel.py". The "SootOutput", "instrout" and "logs" folders need to be empty when starting the script.
At the top of the script you can set :
- the path to the "android.jar" Soot will be forced to use
- the number of parallel instrumentations
- the maximal amount of RAM that can be used
- the folder where the apks lie in
If MutaFlow runs out of RAM while instrumenting, either reduce the number of parallel instrumentations or increase the amount of RAM.
The sources and sinks are defined in the respective files in the "SuSi" folder. Additional method calls can be added by just extending the respective files. A list of possible API calls can be found here.
The instrumented APKs are stored in the instrout folder, the logs of the instrumentations are stored in the logs folder.
After instrumenting, several APKs lie in the "instrout" folder. In a next step the generated APKs need to be signed and aligned. The "SignAndAlign.sh" file contains an example on how to do this. "ZIPALIGNHOME" and "PATH_TO_DEBUG_KEY" need to be set to the respective location on your system.
Now the applications can be executed on a device or emulator, the logcat output needs to be stored. This is done with the following command:
- adb logcat -s MyOwnTag > AppOut/0_Original.pap &
- adb logcat -s MyOwnTag > AppOut/0_OriginalRef.pap &
- adb logcat -s MyOwnTag > AppOut/*X*_*MutatedAPKName*.pap &
This command only stores the output of the instrumentation. For the two unmutated executions two files need to be stored, called "0_Original.pap" and "0_OriginalRef.pap".
The file "Execute_monkey.sh" gives an example on how to do this. For monkey the packagename is needed to run everything, so we additionally added java sources and a "Runner.jar" which handles the package extraction and the order of execution. The "Runner.jar" needs to be set up for your system by setting the "pathToAAPT" to the android build tools you wish to use.
The runner takes the APKs from the "instrout" folder and starts the "Execute_monkey.sh" script.
If the telnet connection to the device fails, adapt line 44 in the "Execute_monkey.sh" script.
The logs need to be stored in the AppOut folder. The "Parser.jar" uses the logs stored in this folder to extract the flows. In a second step the "FlowExtractor.jar" creates a csv file containing all found flows.
Before starting a new analysis, run the "cleanup.sh" script which deletes all collected information from the previous analysis.
Be aware that all content is deleted with this script. If you want to keep any information (including found flows), you have to save it in a different folder before starting the script