DroidBot Documentation

To install DroidBot, clone the repository and install it in editable mode using pip.

Prerequisites

Before installing, ensure you have the following configured:

1. Python (versions 2 and 3 are supported).
2. Java.
3. Android SDK.
4. The platform_tools directory from the Android SDK must be added to your system PATH.
5. (Optional) OpenCV-Python if you intend to use the -cv mode.

After installation, verify it works by running droidbot -h.

git clone https://github.com/honeynet/droidbot.git
cd droidbot/
pip install -e .

DroidBot generates test input events for Android apps and produces a UI transition graph (UTG).

Basic Usage

To start testing an app, provide the path to the .apk file and an output directory:

droidbot -a <path_to_apk> -o output_dir

Requirements

• An .apk file path.
• A device or emulator connected via adb.
• Accessibility Service: On some devices, you must manually enable the Accessibility Service to allow DroidBot to retrieve the current view hierarchy.

DroidBot supports a distributed architecture consisting of a master and worker nodes.

• Master Mode: Start a node as a master using -distributed master. This node uses DroidMaster to coordinate tasks.
• Worker Mode: Start a node as a worker using -distributed worker. This node uses DroidBot and connects to the master via the address provided in the -master flag.

When running in master mode, you can also specify QEMU parameters like -qemu_hda (the HDA image) and -qemu_no_graphic (to run without graphics).

DroidBot supports a distributed architecture consisting of a master and worker nodes.

• Master Mode: Use -distributed master and provide the RPC address via -master. The master uses DroidMaster to coordinate.
• Worker Mode: Use -distributed worker. Workers use DroidBot to execute tests and connect to the master.

# Start as a master
python start.py -a app.apk -distributed master -master 127.0.0.1:5000

# Start as a worker
python start.py -a app.apk -distributed worker -master 127.0.0.1:5000

DroidBot can be started from the command line using the start.py script. It is used to test Android applications by automating user interactions based on a specified input policy.

Basic usage requires providing the path to the target APK using the -a flag. You can optionally specify a target device serial with -d, an output directory with -o, and an input policy with -policy.

python start.py -a /path/to/your/app.apk -o ./output_dir -d emulator-5554

Use the following CLI flags to customize DroidBot's behavior:

The App class is used to represent an Android application and extract its metadata (package name, activities, permissions, etc.) from an APK file. You can initialize it by providing the local path to the APK and an optional output directory for results.

from droidbot.app import App

# Initialize with the path to your APK
app = App(app_path='/path/to/your/app.apk', output_dir='/path/to/output')

print(f"Package: {app.get_package_name()}")
print(f"Main Activity: {app.get_main_activity()}")

The -policy flag determines how DroidBot generates test inputs. The available policies are:

• input_policy.POLICY_NONE: No events will be sent; requires manual interaction.
• input_policy.POLICY_MONKEY: Uses adb shell monkey to send events.
• input_policy.POLICY_NAIVE_DFS: Explores UI using a naive depth-first strategy.
• input_policy.POLICY_GREEDY_DFS: Explores UI using a greedy depth-first strategy.
• input_policy.POLICY_NAIVE_BFS: Explores UI using a naive breadth-first strategy.
• input_policy.POLICY_GREEDY_BFS: Explores UI using a greedy breadth-first strategy.

Use get_start_intent() to retrieve an Intent object configured to launch the application's main activity. This is useful for automated testing lifecycles.

start_intent = app.get_start_intent()

The get_hashes(block_size=256) method calculates the MD5, SHA-1, and SHA-256 hashes of the input APK file. This is useful for verifying file integrity or identifying specific versions of an app.

hashes = app.get_hashes()
# Returns a list: [md5, sha1, sha256]
print(f"MD5: {hashes[0]}")

Use get_start_with_profiling_intent(trace_file, sampling=None) to retrieve an Intent object that starts the application while simultaneously enabling a profiler.

• trace_file: The path where the profiling trace should be saved.
• sampling: (Optional) An integer representing the sampling rate.

trace_path = "/tmp/trace.txt"
# Start with default sampling
intent = app.get_start_with_profiling_intent(trace_path)

# Start with specific sampling rate
intent_with_sampling = app.get_start_with_profiling_intent(trace_path, sampling=100)