Use Guide

This document provides procedures to run Sentinel tool on an application and provides instructions to reproduce the results shown in the paper.

Use Sentinel on an Android application

Before running Sentinel tool on an apk file, there are two environment variables need to be defined:

• ADK should be the path of Android sdk
• GatorRoot should be the path that contains runSentinel.py file

Please define them manually:

export ADK=/path/to/android/sdk
export GatorRoot=/path/to/Sentinel

To run Sentinel tool on an Android app’s apk file:

python3 runSentinel.py /path/to/apkfile

The analysis results will be printed to stdout. For example, for app mTpms, the last a few lines from Sentinel is:

[DEBUG]: Pattern 1 defects output to /Sentinel/sensorEnergyOutput/org.thecongers.mtpms_2.apkC1.log
[DEBUG]: Pattern 2 defects output to /Sentinel/sensorEnergyOutput/org.thecongers.mtpms_2.apkC2.log
[Dev]: template path: /Sentinel/SootAndroid/testcases/gatorTestGenBase.py
[Dev]: Number of test cases: 2
[TestGen]: UIAutomator testgen finished
[TestGen]: Testcases file location: /Sentinel/sensorEnergyOutput/org.thecongers.mtpms_2.apkTests.py
[STAT]: AppName & Classes & Jimples & Node & Edge && LP1 & LP2 &&LRP1 & LRP2 && TestsL1 & TestsL2 && Time
[STAT]: org.thecongers.mtpms_2.apk & 37 & 3148 & 20 &38 && 7 & 8 && 6 & 6 && 1 & 1 && 0.088000

The org.thecongers.mtpms_2.apkC1.log and org.thecongers.mtpms_2.apkC2.log indicated in the output contains the detected sensor defects information. The org.thecongers.mtpms_2.apkTests.py indicated in the output is the test cases generated for app under test. Two lines with [STAT] tags are statistic data for app under test, using the same format as Table 1 in AST’18 paper.

To run the test cases generated from Sentinel on an Android device or emulator, the app’s apk file requires a preprocessing step to allow debugger to attach on this app. Assuming the Android device or the Android emulator has USB debugging enabled and it is connected to the computer, the preprocessing and installation of the app can be done using following commands:

python3 exportActivities.py APK_FILE_NAME -o PATCHEDAPK_FILE_NAME
$ADK/platform-tools/adb install PATCHEDAPK_FILE_NAME 

The generated test cases can be run using following command:

python3 $GatorRoot/sensorEnergyOutput/TEST_FILE.py

If a test is leaking sensor resource, the information leaked sensor resource will be output to stdout. For app mTpms, the output will look like:

Device:marlin
test0 verified to leak following sensor resources:
Sensor: TMD4903 Light Sensor 0x00000007, Listener: org.thecongers.mtpms.MainActivity.
test0 ends
test1 verified to leak following sensor resources:
Sensor: TMD4903 Light Sensor 0x00000007, Listener: org.thecongers.mtpms.MainActivity.
test1 ends

Please note some apps require the user to finish some initialization steps, such as a first run wizard, these steps needs to be done manually before running the test cases. For a few apps, the sensors will only be enabled when certain features are enabled in app’s preference or requiring specific input in the EditText boxes. These steps can only be performed manually. For application using ActionBars, the Android OptionsMenu is no longer exist and Android no longer associate menu IDs with action bar UI menu items. This will cause an issue to the test cases generated by Sentinel as the clicks on UI widgets are performed by using their IDs. In this case, please modify the test case file to click on UI texts instead of UI IDs.

Reproduce the results in the Paper.

We evaluated our tool on both open-source apps from F-Droid and commercial apps from Google Play Store. The open-source apps that contains defects reported by Sentinel are included in Apps/ directory. Due to licensing issues, we cannot include commercial apps here. Here is the list of apps we used in the evaluation but not included under Apps/ directory.

These apps can be easily downloaded from Internet using their version number and hashes.

The steps to run Sentinel on evaluation apps and to run generated test cases are the same as the ones mentioned in the previous section. Please note the results from current Sentinel will differ slightly from the Table 1 in the AST’18 submission. Some differences are due to minor changes in the underlying GATOR tool (e.g., revised handling of tags in XML files), and one difference is due to an inaccuracy in our manual investigation of run-time leaks. The updated results can be found in Table 3.1 in Haowei Wu's Ph.D. dissertation. Due to a known issue of Gator that the current implementation of WTG (Window Transition Graph) is nondeterministic. The number of SG (Sensor effect Graph) nodes and edges may be slightly different when Gator is running on different environments. We observed this behavior on two of the evaluation apps. The output of detected sensor leaks and generated tests are not affected.

For false positives and non-executable test cases, please refer to the Section 3.4 and 3.5 of Haowei Wu’s PhD dissertation.

Necessary manual steps

There are a few apps in the evaluation requires additional manual steps to allow generated tests to be run successfully on testing device.

App com.voxofon and com.csipsimple

These two apps are SIP service applications. Therefore, a SIP service account is required to use these two apps. For either of these two apps, the defective activity will only show up when there is an ongoing SIP phone call. In our evaluation, we use the generated test cases as guidance to test this application manually, since there is no way to mock a SIP phone call in an automated test.

App com.calculator.vault

This application requires user to go through a wizard when it is started for the first time. Please finish the wizard and set up a PIN. The field “TO_DO_SET_YOUR_OWN_TEXT” in the generated test cases should be replaced with the PIN. In our evaluation, we use “1234” as the PIN, but it should work with any PIN as long as the one in the test cases is the same as the one in the initial wizard.

2 out of 4 test cases generated for this app (the ones open “CalculatorActivity”) require option “Shake to Unlock” in the app’s preference to be enabled. Please enable this option before running these 2 test cases.

App com.mobeezio.android.dogwhistler

The test cases generated for this app require the “Mode” in the menu is set to “Timer”. Please perform this step before running the generated test cases.

App com.hideitpro

This application requires user to go through a wizard when it is started for the first time as well. To enable sensor usage, option “Shake Phone to logout” in the app’s preference needs to be enabled. Please finish these two steps before running the generated test cases.