BREW: Manual (s://github.com/FoelliX/BREW/wiki)

User Manual:

Open the PDF directly: View PDF .
Page Count: 18

Download
Open PDF In Browser	View PDF

BREW: Manual
(https://github.com/FoelliX/BREW/wiki)

1/18

Table of contents
Menu
BREW
Runthrough
Install & Compile
Launch parameters
Configuration
Benchmarking
Setup/Load/Execute
Evaluation
Load AQL-System results

ReproDroid

BREW 1.2.0
Improvements

FAQ

2/18

BREW
Benchmark Refinement and Execution Wizard (BREW)
The Benchmark Refinement and Execution Wizard (BREW) can be used to do what the name suggests, first refine and then execute a
benchmark.

New Tutorial
The improvements introduced along with the release of version 1.2.0 are described in the following tutorial:
Improvements

Basic Tutorials
Runthrough
Launch parameters
Configuration

Benchmarking
Setup/Load/Execute
Evaluation
Load AQL-System results

Fully load ReproDroid benchmarks

FAQ

3/18

Runthrough
Runthrough
The following instructions deal with the installation of BREW. Along with that Amandroid will be installed. Hence, BREW will be setup to use
Amandroid only. (The operating system considered is Linux.)
1. Download the latest version of BREW: here
Unzip it!
2. Download Amandroid: https://bintray.com/arguslab/maven/argus-saf/3.1.2
(direct link: https://bintray.com/arguslab/maven/download_file?file_path=com%2Fgithub%2Farguslab%2Fargussaf_2.12%2F3.1.2%2Fargus-saf_2.12-3.1.2-assembly.jar)
3. Download the

DirectLeak1

app from DroidBench 3.0: https://github.com/secure-software-

engineering/DroidBench/raw/develop/apk/AndroidSpecific/DirectLeak1.apk
4. Setup a configuration
Create file

config_amandroid.xml

located in the directory of BREW

Copy and Paste the following content:

/path/to/android/platforms/
8

/path/to/Amandroid/aqlRun.sh %APP_APK% %MEMORY%
/path/to/Amandroid/outputPath/%APP_APK_FILENAME%/result/AppData.txt
0
4

/path/to/Amandroid
IntraAppFlows
/path/to/BREW/flushMemory.sh
/path/to/BREW/killpid.sh %PID%

Adjust the path to the Android SDK’s platforms directory (
Adjust the path for Amandroid (
Use the same path in

/path/to/android/platforms/

/path/to/Amandroid

and

) (The directory should contain the previously downloaded .jar file.)

Adjust the path to flushMemory.sh and killpid.sh to the path of BREW in
Lastly adjust

and

)

and

. The latter has to be less than or equal to the first value. Both values are given in

gigabytes. (If sufficient memory is provided, a tool might be executed multiple times in parallel.)
5. Make

flushMemory.sh

and

killpid.sh

, located in BREW directory, executeable:

chmod u+x flushMemory.sh killpid.sh

6. Create launch script
cd /path/to/Amandroid
nano aqlRun.sh

7. Copy and Paste the following:
#!/bin/bash
rm -R outputPath
java -Xmx${2}g -jar argus-saf_2.12-3.1.2-assembly.jar t -o outputPath ${1}

4/18

8. Save (Ctrl+o) and exit (Ctrl+x) nano
9. Make the script executable:
chmod u+x aqlRun.sh

10. Finally, launch BREW
cd /path/to/BREW
java -jar BREW-1.2.0.jar -config config_amandroid.xml -d detailed -gui

11. Load the app
Open the File menu
Click on Load File..
Navigate to and select

DirectLeak1.apk

12. Click on Next (Green Right-Arrow in the toolbar)
13. Click on Preselect source & sinks based on SuSi

14. Click on Next again
15. Click on "Run"

16. Wait for the result and inspect it!

5/18

Install & Compile
Install
To simply install BREW you must
download the current release: here
and unzip it
done!
For a hello world like tutorial follow the runthrough tutorial.

Compile
To compile BREW by yourself follow these steps:
Clone the repository
Build the Maven project by:
cd /path/to/project/BREW
mvn

(Test might not be completely up-to-date, consider skipping:

mvn -DskipTests

)

6/18

Launch parameters
Launch Parameters
BREW can be launched with the parameters mentioned in the table below.
Parameter
-help
h

man

Meaning

Outputs a very brief manual, which contains a list of all available parameters

manpage
-config
"X"

-cfg

By default the config.xml file in the tool's directory is used as configuration. With this parameter a different configuration file

"X"

-c

can be chosen.

has to reference the path to and the configuration file itself.

"X"

By default the rule-set in rules.xml file is loaded. With this parameter a different rule file can be chosen.

-rules

has to reference

the path to and the rule file itself.

"X"
-output
"X"

-out

The answer to a query is automatically saved in the

"X"

-o

directory.

answers

directory. This parameter can be used to store it in a second

has to define this directory including its path.

"X"
-timeout
"X"s/m/h

With this parameter the maximum execution time of each tool can be set. If it expires the tool's execution is aborted.

refers

to this time in seconds (e.g. 10s), minutes or hours.

-t
"X"s/m/h

The output generated during the execution of this tool can be set to different levels.

-debug
"X"

-d

normal

-reset

detailed

(ascending precision from left to right). Additionally it can be set to

but shorter at some points. By default it is set to

normal

short

error

warning

, the output will then be

.
data/data.ser

is directly

executed.

-backup
-bak

debug

normal

may be set to:

If this parameter is added, the GUI will not be launched. Instead the currently stored benchmark in

-nogui

equal to

"X"

-b

-r

To backup previously computed results on startup add one of these parameters.

To reset BREW on startup add one of these parameters.

--from
"X"

--to

If only some benchmark cases shall be executed these parameters can be used to set the limits.

"X"

7/18

Configuration
Configuration
Configuring BREW works just as configuring the underlying AQL-System.
Therefore, we refer to the configuration tutorial of the AQL-System.

8/18

Benchmarking
Benchmarking
Setup/Load/Execute
Evaluation
Load AQL-System results

9/18

Setup/Load/Execute
1. Setup a Benchmark
Open the File menu
Click on Load File.. and choose an application
OR
Click on Load Folder.. and select a directory containing a set of apps
Deselect testcases you do not want to run.
To build an inter-app testcase activate the initial app and enter all other apps' IDs in the last column ( Combine with IDs). Deactivate the other
apps.

Click on Next (Green Right-Arrow in the toolbar)
On the next screen specify which statements are sources and sinks. There exist two options to do so:
manually by selecting the checkboxes
OR
click on Preselect Sources & Sinks based on SuSi.

Sources & Sinks can be combined by entering appropiate IDs in the Combine with IDs column. This makes sense if multiple statements may
be expectable as source for the same resource, for example.
Click on Next (Green Right-Arrow in the toolbar)
Finally, decide which of the generated benchmark cases should be found ( True Positive) and which should not be found (False Positive).
The setup is done. Feel free to save the benchmark.

2. Load & Execute a Benchmark
Open the File menu
Click Open.. and choose the benchmark you want to load. You can also add another benchmark to an already opened one by clicking
on Add...

10/18

Click on Next (Green Right-Arrow in the toolbar)
Click on Next again
Click on Run Benchmark

Refine a benchmark
To refine a benchmark just open one (see 2.) and edit it as described for a new one (see 1.).

11/18

Evaluation
Evaluation of Benchmarks
After executing a benchmark successfully, the result should look like:

Legend:
A red, green row indicates a failed, successful benchmark case, respectively.
A blue row stands for an aborted or timed-out benchmark case.
The values for Precision, Recall and F-measure can be checked in Statistics pane.
To inspect a single results:
Select one benchmark case in the table and check the information pane. It shows, for example, which AQL-Query would be executed to
evaulate this case.
Press V or click on Show in Viewer (magnifying glass in the toolbar) to review the expected and actual result.
(optional) Switch to the graphical representation on both sides in order to get a better overview.

12/18

13/18

Load AQL-System results
Load AQL-System results
1. Run a query in the AQL-System (see the query execution tutorial)
2. Save the computed AQL-Answer
3. Load results in BREW
Launch BREW
Load the same app that was considered in the query or open a benchmark that contains this app
Click twice on Next (Green Right-Arrow in the toolbar)
Open the Edit menu
Click on Mark successful (Result based - XML) and choose the saved AQL-Answer

14/18

ReproDroid
Fully load a ReproDroid benchmark
Download the latest BREW release: https://github.com/FoelliX/BREW/releases
Download a ReproDroid benchmark: https://FoelliX.github.io/ReproDroid
e.g. the refined benchmark version of DroidBench 3.0: https://uni-paderborn.sciebo.de/s/ZmlRvtzI6pVYHVP/download?
path=%2Fbenchmarks&files=DroidBench30.zip
Extract both downloaded archives: Let us assume

%BREW%

and

%benchmark%

refer to the respective extracted archives.

Choose the tool for which you want to load the benchmark (for this example we assume it is Amandroid).
Copy

%benchmark%/results/Amandroid/data

%BREW%/data

Start BREW with
config_toolset1.xml (for Amandroid, DroidSafe, FlowDroid and IccTA)
config_toolset2.xml (for DIALDroid and DidFail)
Click on Next (Green rightarrow in the toolbar)
Click on Directory (Ignore parent directory)
Select the

%benchmark%/benchmark/apks

directory

If any warnings appear, just click OK
Click on Next (Green rightarrow in the toolbar) again
Click Yes
Inspect the fully loaded benchmark result
The lower Statistics pane shows general information such as precision, recall and F-measure
Individual results can be reviewed by selecting a case and clicking on Show in Viewer (magnifying glass in toolbar) or pressing v.

15/18

BREW 1.2.0
Benchmark Refinement and Execution Wizard (BREW)
The Benchmark Refinement and Execution Wizard (BREW) can be used to do what the name suggests, first refine and then execute a
benchmark.

New Tutorial
The improvements introduced along with the release of version 1.2.0 are described in the following tutorial:
Improvements

Basic Tutorials
Runthrough
Launch parameters
Configuration

Benchmarking
Setup/Load/Execute
Evaluation
Load AQL-System results

Fully load ReproDroid benchmarks

FAQ

16/18

Improvements
Improvements
With BREW version 1.2.0 mainly two improvements are introduced. Both help to select the best tool associated with any benchmark case.
Futhermore, the new version relies on the up-to-date AQL-System (v. 1.2.0).
IMPORTANT: This makes it mandatory to upgrade existing configurations (see Configuration Upgrades)!

1. Features
BREW 1.2.0 allows to automatically determine or specify features for certain benchmark cases. This way tools can be choosen more selectively
based on a tool's priority to handle certain features.

Example: The following configuration holds two artificial tools, namely

AwesomeDroid

and

LameDroid

1
3
...

2
...

For arbitrary benchmark cases
AwesomeDroid

LameDroid

has the highest priority (

). For benchmark cases with the associated

Awesome

feature assigned

) and will be selected.

2. Rules
The same features can be used to activate (query transformation) rules for certain benchmark cases. These rules are loaded from an XML file.
The structure of such a file is defined through the rules.xsd schema. The launchparameter

-rules X

can be used to load rules from file

Inside any rule the following variables can be used:
Variable

Meaning

%QUERY%

The original query before applying the rule without question mark, if the original query ends with a question mark

%FILE_i%

File number i (i in [1, n]) from the original query

%FEATURE_i%

Feature number i (i in [1, n]) from the original query

%FEATURES%

All features from the original query

Example: Let us consider the following query

Flows IN App('AwesomeApp.apk') FEATURING 'Awesome' ?

With the rule-set below in place, it gets transformed to

FILTER [ Flows IN App('AwesomeApp.apk') FEATURING 'Awesome' ? ]

since only the rule

with the highest priority is applied.

1
UNIFY [ %QUERY% ?, Permissions IN App('%FILE_1%') ? ]

2
FILTER [ %QUERY% ? ]

The first rule included is always applied (see attribute
priority is only

always="true"

the sencond rule gets applied with a priority of

) independently of the features mentioned in the query. However, since its

for this query.

17/18

FAQ
FAQ
No questions, yet!

18/18

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Title                           : BREW: Manual (https://github.com/FoelliX/BREW/wiki)
Creator                         : wkhtmltopdf 0.12.5
Producer                        : Qt 4.8.7
Create Date                     : 2019:06:04 07:43:46+02:00
Page Count                      : 18
Page Mode                       : UseOutlines

EXIF Metadata provided by EXIF.tools

BREW: Manual (s://github.com/FoelliX/BREW/wiki)

Navigation menu

Versions of this User Manual:

Views

Navigation