# Ella

**Repository Path**: midori/Ella

## Basic Information

- **Project Name**: Ella
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2015-12-18
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

ELLA: A Tool for Binary Instrumentation of Android Apps
====

Ella is a tool to instrument Android APK's for various purposes. Out of the box, it instruments
apps to record which methods gets executed. It can also record time-stamped trace of executed
methods, values of arguments passed at call-sites, values of formal parameters of methods, etc.

Several tools exist that can instrument APK's to some
degree. But they usually do not work very reliably because they
translate Dalvik bytecodes to another form such as Java bytecode or
internal representations of other tools, and this translation is quite
challenging.  Thus, Ella's approach is to instrument at the Dalvik
bytecode level. It does so by builiding atop the DexLib2 library (a part
of the [Smali](https://github.com/JesusFreke/smali) project).

## Pre-requisite
1. Unix-like operating system. Minor tweaks to scripts and build files may be needed to run ella on Windows.
2. Android SDK
3. Java SDK
4. Apache Ant

## Before building ella
1. Rename `ella.settings.template` file to `ella.settings`, and if needed, set values of different environment variables of ella.
2. If the instrumented app will be executed on an emulator **and** the ella server will be run on the host machine of the emulator, then do nothing. Otherwise, set:
```
ella.use.emulator.host.loopback=false
```
If `ella.use.emulator.host.loopback` is set to `false` **and** the ella server will be running on a machine that is different from the machine on which the instrumentor is run, then set `ella.server.ip` to the IP address of the machine on which the ella server will be run. For example,
```
ella.server.ip=1.2.3.4
```
Otherwise, do nothing.

## Build ella
Execute the following command inside ella's installation directory.
```
ant 
```

## Instrument the app
Execute the following command.
```
ella.sh i <path-to-apk>
```

`<path-to-apk>` is the Apk that you want to instrument. This command would produce the instrumented apk named `instrumented.apk` inside a subdirectory inside `<ella-home>/ella-out` directory, where `<ella-home>` represents the installation directory of ella. The name of the subdirectory is derived from `<path-to-apk>`.

## Start ella server
Before executing any instrumented app, ella server must be up and running. To start the ella server, execute the following command.
```
ella.sh s
```
Whenever needed, the ella server can be shutdown by executing the following command
```
ella.sh k
```
## Execute the instrumented app 
1. Install the `instrumented.apk` on the emulator or device. You may have to uninstall it first if the app is already installed.
2. Execute the instrumented app. The instrumented app will send coverage data periodically to the ella server.
3. To end recording and uploading coverage data, either simply kill the app **or** execute the following command on computer connected to the device/emulator. `e` stands for "end" in end recording coverage data.
```
ella.sh e
```

## Coverage data

The coverage data are stored inside a subdirectory of `<ella-home>/ella-out` directory, where `<ella-home>` represents the installation directory of ella. The name of the subdirectory is derived from `<path-to-apk>`. Currently, coverage data are stored in files `coverage.dat` and `covids`. `covids` contain the list of method signatures; index of a method is its identifier. `coverage.dat` contains the list of method identifiers that were executed.