❗ DEPRECATION NOTICE ❗

This repository is no longer maintained as of December 2016. For current development on DroidMate, please visit uds-se/DroidMate-2 repository.

DroidMate

DroidMate, an automated execution generator for Android apps.
Copyright (C) 2012-2016 Konrad Jamrozik

This program is free software.

Contact: [email protected]

• www.droidmate.org
• DroidMate publication
• "Mining Sandboxes" publication
• GitHub repository with "Mining Sandbox" publication data
• "Guarantees from Testing" talk by Andreas Zeller

Date of last full review of this document: 13 Jun 2016

Introduction

DroidMate is an automated execution generator / GUI fuzzer / dynamic analysis engine for Android apps.

This file pertains to DroidMate source. You should have found it at DroidMate repository root dir, denoted in this file as repo.

This file explains:

• What DroidMate is and overview of how it works.
• With which operating systems and Android devices DroidMate is compatible.

Furthermore:

• repo/BUILDING.md explains how to build and test DroidMate.
• repo/RUNNING.md explains how to:
  • use DroidMate API from your Java project, with examples;
  • run DroidMate directly from built sources (this method is not recommended, use API instead);
  • obtain input apks;
  • prepare (inline) input apks to be compatible with DroidMate method call monitoring;
  • configure the emulator.
• repo/DEVELOPING.md explains how to:
  • setup an IDE for DroidMate development;
  • navigate DroidMate sources and technical documentation;
  • edit the list of monitored APIs;
  • provide your own hooks to the monitored APIs.
• repo/TROUBLESHOOTING.md explains how to work around known bugs & problems.

How DroidMate works

DroidMate fully automatically explores behavior of an Android app by interacting with its GUI. DroidMate repeatedly reads the device state, makes a decision and interacts with the GUI, until some termination criterion is satisfied. This process is called an exploration of the Application Under Exploration (AUE).

DroidMate is fully automatic: after it has been set up and started, the exploration itself does not require human presence.

DroidMate can be run from command line or through its Java API. As input, it reads a directory containing Android apps (.apk files). It outputs a serialized Java object representing the exploration output. It also outputs .txt files having various human-readable information extracted from the serialized exploration output.

DroidMate can click and long-click the AUE’s GUI, restart the AUE, press ‘home’ button and it can terminate the exploration. Any of this is called an exploration action. DroidMate’s exploration strategy decides which exploration action to execute based on the XML representation of the currently visible device GUI, i.e. a GUI snapshot, and on the set of Android framework methods that have been called after last exploration action, i.e. a set of API calls.

For more information, please see the papers available on the website linked above.

Compatibility

OS compatibility

DroidMate works on Ubuntu, Windows 10 and Mac OS X.

Primary development of DroidMate is done on Windows 10. Ubuntu is used in the CI server. Mac OS X is actively being used by DroidMate users.

Android devices and emulators compatibility

DroidMate works on Android 6.0 (API 23), on physical devices. It also works on Android 4.4.2 (API 19), both physical devices and emulators.

DroidMate works on API 23 emulators, but with limitations. It works fully on the slow, ARM-based emulators. In the fast x86 emulators, DroidMate cannot work with inlined (see repo/RUNNING.md) apks and thus, cannot monitor calls to Android framework. This is due to the fact ArtHook, the library used in DroidMate for monitoring when running on API 23, is compatible only with ARM architecture, not x86.

DroidMate works on following devices:

API 23:

• Nexus 7 2013
• Nexus 5X

API 19:

• Nexus 7 2012
• Nexus 10
• Samsung Galaxy S3

If DroidMate doesn't recognize a device it defaults to Nexus 7. You can change the default by editing DeviceModel. In your device model you just have to ensure the package name of the home screen is correct. You can check the package name by doing the following:

• launch Android Device Monitor, e.g. with android-sdk/tools/monitor.bat;
• select running device. If device is running, adb devices will show it;
• click on Dump View Hierarchy for UI Automator;
• click on the top level FrameLayout and look at package.

Contributions

Nataniel Borges Jr., @natanieljr:

• Added support for multiple Android devices models.
• Added support for uiautomator 2.0.
• Added support for handling runtime permission request dialog boxes present on Android 6 and higher.