Installation and Usage

This page provides the instructions on installing and running GoalExplorer.

Table of contents

1. Getting started
   1. Prerequisites
   2. Setup
2. Usage
   1. Generating GUI model of the app
      1. Available Options
   2. Dynamic exploration

Getting started

Prerequisites

Java Runtime Environment version 8 or later is required.

The static analyzer depends on Soot and FlowDroid (for modeling Android lifecycle) and IC3 (for decoding Intents):

• Soot : Soot - A Java optimization framework

• IC3 : Inter-Component Communication Analysis for Android

• FlowDroid : FlowDroid Static Data Flow Tracker

The dynamic explorer is built on top of Stoat, and it depends on Python, Ruby, Nokogiri, and UiAutomator:

• Ruby : 2.1

• Python : 2.7

• Nokogiri : HTML, XML, SAX, and Reader parser

• uiautomator : Python wrapper of Android uiautomator test tool

Setup

GoalExplorer is built using Maven. Use

mvn install

The FlowDroid module contains DroidBench tests, so you may want to build the tool without the tests (over 400 tests in total), try

mvn -DskipTests install

Maven should take care of all dependencies that are required for the build, and the built JAR files can be found in the “target” folder of the respective modules.

Please make sure that ic3-android.jar, AndroidCallbacks.txt and icc.cmodel are in the same directory as the JAR file, so that the inter-component communication model generated from IC3 can be used for better ICC modeling.

To setup the dynamic explorer, you need to install Android SDK and create emulators if you plan to run on emulator. See this link on how to create avd using avdmanager.

The current version only supports running on emulators.

Please export ANDROID_HOME (for android sdk), PYTHON_PATH (for uiautomator), CLASSPATH (for soot)

Example:

export ANDROID_HOME="/home/XX/Android/Sdk"
export PYTHONPATH="/home/XX/uiautomator"
export CLASSPATH="/home/XX/fsmdroid/soot-github/lib/soot-develop.jar
export PATH=$PATH:${ANDROID_HOME}/build-tools/25.0.0:${ANDROID_HOME}/emulator:${ANDROID_HOME}/tools:${ANDROID_HOME}/tools/bin:${ANDROID_HOME}/platform-tools:

You may also need to modify “Stoat/CONF.txt” to set the Stoat path.

Usage

Generating GUI model of the app

First generates the static UI model of the app (STG) using the command:

java -jar {JAR_PATH} ge [OPTIONS] [-cb <arg>] [-d] [-h] -i <arg> 
          [-l <arg>] [-o <arg>] [-s <arg>] [-t <arg>] [-v]

Available Options

  usage: ge [OPTIONS] [-cb <arg>] [-cg <arg>] [-d] [-h] -i <arg> 
            [-l <arg>] [-o <arg>] [-s <arg>] [-t <arg>] [-v]
   -cb <arg>           the maximum number of callbacks modeled for each
                       component (default to 20)
   -d,--debug          debug mode (default disabled)
   -h,--help           print the help message
   -i,--input <arg>    input apk path (required)
   -l,--api <arg>      api level (default to 23)
   -o,--output <arg>   output directory (default to "sootOutput")
   -s,--sdk <arg>      path to android sdk (default value can be set in
                       config file)
   -t <arg>            maximum timeout during callback analysis in seconds
                       (default: 60)
   -v,--version        print version info

Dynamic exploration

Run the dynamic explorer with the generated STG as the input:

ruby run_stoat_testing.rb --app_dir /home/XX/Bites.apk --avd_name testAVD_1 
--avd_port 5554 --stoat_port 2000 --model /path/to/model