Commit 8acfca85 authored by Stefan Schott's avatar Stefan Schott
Browse files

Added readme

parent 7ad61567
# GenBenchDroid
*GenBenchDroid* is a tool that is able to automatically generate Android applications that can be used as benchmark cases for the evaluation of Android taint analysis tools.
Alongside the application, GenBenchDroid also generates a corresponding ground-truth that contains the expected analysis results for the application.
## Configuration
GenBenchDroid has to be confiugred before its usage.
This configuration has to be performed inside the **.env** file.
The directories containing the templates, modules and outputs have to be specified.
Additionally, the desired project name, as well as the Android SDK directroy and the JDK directory have to be specified.
Example Configuration:
```
TEMPLATE_DIR=templates
MODULE_DIR=modules
OUTPUT_DIR=output
PROJECT_NAME=com.generated.app
ANDROID_SDK_DIR=path/to/Android/Sdk
JDK_DIR=path/to/Java/jdk
```
## Usage
To install all required dependencies, at first the following command has to be executed inside the directory containing GenBenchDroid:
```
npm install
```
### Usage Modes
GenBenchDroid offers two different usage modes: (1) the manual mode and (2) the fuzzing mode.
### Manual Mode
The manual mode can be used to generate a fully specified benchmark case.
The following command can be used to generate a benchmark case:
```
node app --config <TMC>
```
\<TMC> is just a placeholder that has to be replaced by the desired template and module configuration.
Example configuration 1:
```
node app --config "BasicTemplate ImeiSource ArrayBridge SmsSink"
```
The desired configuration has be to surrounded by quotation marks and each module has to be separated by spaces.
Templates and modules are specified by providing their individual file names without the file extension.
The template that is desired has to be the first token inside the provided configuration.
Example configuration 2:
```
node app --config "BasicTemplate RandomIfElseBridge ( ArrayBridge ) ( SmsSink )"
```
This example contains a branch inside the generated benchmark case.
**RandomIfElseBridge** represents a branching module that requires two follow-up modules.
Each branch is indicated by a parenthesis pair.
The modules specified inside the first parenthesis pair are inserted into the first branch.
The moduels specified inisde the second one are inserted into the second branch.
Each branch may contain arbitrarily many nested branches.
Generated benchmark cases and their corresponding ground-truths can be found in the directory that has been specified inside the configuration.
### Fuzzing Mode
GenBenchDroid's fuzzing mode can be used to generate random applications.
The fuzzing mode can be executed with the following command:
```
node app --fuzz
```
In order to specify desired properties for the randomly generated applications, the following parameters can additionally be used:
|Parameter|Functionality|
| ------- | ----------- |
| --depth,<br/> -d | Specifies the maximum derivation depth and limits the maximum configuration length |
| --minLenght,<br/> -m | Specifies the minimum length of the configuration |
| --taintflow,<br/> -t | Guarantees a taint flow inside the generated benchmark case |
| --contains | Specifies (sub)strings that have to be part of the configuration |
| --ignore | Specifies (sub)strings that cannot to be part of the configuration |
Each of these parameters can also be combined with another.
Parameter Usage Example:
```
node app -f -m 10 -t --contains ArrayBridge Sink
```
This command generates a random benchmark case with a minimum configuration length of ten (at least one template and nine modules) that definitely contains a taint flow and also contains an **ArrayBridge** and another module with **Sink** in its name.
## Extension
GenBenchDroid can easily be extended by creating new templates and modules.
In order to easily create a new template or module, the [GenBenchDroid-Editor](https://git.cs.uni-paderborn.de/sschott/genbenchdroid-editor) can be used.
Once the new template/module has been created, its file name has to be appended to the grammar in the file **grammar.</span>ne** at the right location.
A new template has to be appended to the **template** symbol, while a new module has to be appended to the **module** symbol.
If the new module does not branch the program flow, a **linear** symbol has to be appended.
If it is a branching module with two branches a **2Branches** module has to be appended.
This continues on with other amounts of branches.
Appending example:
```
...
template −> "BasicTemplate" | ... | "CreatedTemplate"
module −> "ImeiSource" linear | ... | "CreatedLinearModule" linear |
```
After the grammar has been extended, the following command has to be executed to generate a new parser from the modified grammar:
```
node app --compile
```
Afterwards the newly created templates and modules can be used by GenBenchDroid.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment