Skip to content

Configuration

FoelliX edited this page Jul 11, 2018 · 7 revisions

Configuration

Any AQL-System has to be configured via an .xml file. Its structure is described by this XML Schema Definition file. Such a configuration defines a few environmental properties and most importantly which analysis tools, preprocessors, (external) operators and (external) converters are available. Any of these is represented by a <tool> element inside the configuration file. There exists two possibilities to create or edit a configuration:

  • Edit the .xml file directly
  • Use the Configuration Wizard

Option 1: Edit the .xml file directly

The following code shows a basic, shortened version of a configuration:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config>
	<!-- Environment -->
	<androidPlatforms>path/to/android/platforms</androidPlatforms>
	<maxMemory>6</maxMemory>

	<!-- Tools -->
	<tools>...</tools>
	<preprocessors>...</preprocessors>
	<operators>...</operators>
	<converters>...</converters>
</config>
  • Inside the <androidPlatforms> tag the path to the android platform files has to be specified.
  • The memory element tells the AQL-System how much memory shall be used at most.
  • <tools>, <preprocessors>, <operators> and <converters> each contain a list of <tool> elements. Each <tool> element describes one analysis tool, preprocessor, (external) operator or (external) converter, respectively. In the following the differences and commonalities of these four are described along with one example for each type.

Analysis tools

<tool name="AwesomeDroid" version="1.3.3.7">
	<priority>0</priority>
	<priority feature="TEST">2</priority>

	<path>/path/to/AwesomeDroid</path>
	<run>/path/to/AwesomeDroid/run.sh %MEMORY% %ANDROID_PLATFORMS% %APP_APK%</run>
	<result>/path/to/AwesomeDroid/results/%APP_APK_FILENAME%_result.txt</result>

	<questions>IntraAppFlow</questions>
	<instances>0</instances>
	<memoryPerInstance>4</memoryPerInstance>

	<runOnExit>/path/to/AQL-System/flushMemory.sh</runOnExit>
	<runOnSuccess>/path/to/AwesomeDroid/success.sh</runOnSuccess>
	<runOnFail>/path/to/AwesomeDroid/fail.sh</runOnFail>
	<runOnAbort>/path/to/AQL-System/killpid.sh %PID%</runOnAbort>
</tool>
  • Any tool is identified by the values assigned to the two attributes name and version (In this example the tool's name is AwesomeDroid and its version is 1.3.3.7).
  • <priority>: If there are two or more tools available which are capable of answering the same AQL-Questions the priority decides which tool is executed.
    • There may be multiple <priority> elements, however, only one without a feature attribute. In the example AwesomeDroid has a priority of 0, which becomes 2 if the associated AQL-Question assigns the feature TEST.

How to run any tool is specified through the following elements:

  • <path>: This describes a path to the directory where the tool shall be executed
  • <run>: The run tag describes how to call a certain tool by defining the location of a bash script, for example
  • <result>: This describes where the result can be found once a tool finishes successfully. (A *-symbol can be used inside this tag to reference an arbitrary substring.)

Variables, which can be used in the three previously described elements are:

Variable Meaning
%APP_APK% The .apk file referenced in an AQL-Question
%APP_APK_FILENAME% The filename of the .apk file without path and ending
%APP_NAME% The app’s name specified in its manifest
%APP_PACKAGE% The app’s package specified in its manifest
%ANDROID_PLATFORMS% The Android platforms folder (Specified through )
%MEMORY% The memory available to an instance of a tool (Specified through )
%PID% The tools process ID during execution
  • <questions>: The content of this tag describes which AQL-Questions can be answered with the associated tool. The following options are available (Exemplary associated AQL-Questions can be found in the brackets behind each option):
    • Permissions (Permissions IN App('A.apk') ?)
    • Intents (Intents IN App('A.apk') ?)
    • IntentFilters (IntentFilters IN App('A.apk') ?)
    • IntentSources (IntentSources IN App('A.apk') ?)
    • IntentSinks (IntentSinks IN App('A.apk') ?)
    • IntraAppFlows (Flows IN App('A.apk') ?)
    • InterAppFlows (Flows FROM App('A.apk') TO App('B.apk') ?)
  • <instances>: This element defines how often the associated tool can be executed at the same time.
  • <memoryPerInstance>: This tag defines how much memory is required and provided to each instance of the associated tool.

There are four more elements which optionally can be specified, namely <runOnExit>, <runOnSuccess>, <runOnFail> and <runOnAbort>. Each refers to a command or a script which will be executed on certain tool events.

  • <runOnExit> is always run after tool execution or abortion.
  • <runOnSuccess> and <runOnFail> get executed depending on whether the tool has finished successfully or not.
  • <runOnAbort> is run if the tool is aborted.

Variables, which can be used in these four previously described elements in turn are:

Variable Meaning
%MEMORY% The memory available to an instance of a tool (Specified through )
%PID% The tools process ID during execution

Preprocessors

<tool name="AwesomePreprocessor" version="1.3.3.8">
	<priority>0</priority>

	<path>/path/to/AwesomePreprocessor</path>
	<run>/path/to/AwesomePreprocessor/run.sh %APP_APK%</run>
	<result>/path/to/AwesomePreprocessor/results/%APP_APK_FILENAME%_preprocessed.apk</result>

	<questions>TEST</questions>
	<instances>0</instances>
	<memoryPerInstance>4</memoryPerInstance>

	<runOnExit>/path/to/AQL-System/flushMemory.sh</runOnExit>
	<runOnAbort>/path/to/AQL-System/killpid.sh %PID%</runOnAbort>
</tool>

Preprocessors are specified the same way as analysis tools with one exceptions: The <questions> element now holds a list of keywords, separated by ,, assigned to the associated preprocessor. In the above example only one keyword is assigned (TEST).

Operators

<tool name="AwesomeOperator" version="1.3.3.9">
	<priority>0</priority>

	<path>/path/to/AwesomeOperator</path>
	<run>/path/to/AwesomeOperator/run.sh %ANSWERS%</run>
	<result>/path/to/AwesomeOperator/results/%ANSWERSHASH%.xml</result>

	<questions>CONNECT(*)</questions>
	<instances>1</instances>
	<memoryPerInstance>4</memoryPerInstance>

	<runOnExit>/path/to/AQL-System/flushMemory.sh</runOnExit>
	<runOnAbort>/path/to/AQL-System/killpid.sh %PID%</runOnAbort>
</tool>

Operators are specified the same way as analysis tools with a few exceptions:

  • The variables which can be used in <path>, <run> and <result> are:
Variable Meaning
%ANSWERS% Input AQL-Answer files separated by " "
%ANSWERSHASH% SHA-256-hash of the %ANSWERS%-String
%ANDROID_PLATFORMS% The Android platforms folder (Specified through )
%MEMORY% The memory available to an instance of a tool (Specified through )
%PID% The tools process ID during execution
  • The <questions> element refers to the operators name and specifies its number of parameters
    In the example CONNECT(*) tells us that the default CONNECT operator gets overwritten by an external operator which takes arbitrary many (*) AQL-Answers as input.

Converters

<tool name="AwesomeDroidConverter" version="1.3.3.7">
	<path>/path/to/AwesomeDroidConverter</path>
	<run>/path/to/AwesomeDroidConverter/run.sh %RESULT_FILE% results/%APP_APK_FILENAME%.xml</run>
	<result>/path/to/AwesomeDroidConverter/results/%APP_APK_FILENAME%.xml</result>

	<questions>AwesomeDroid</questions>
	<instances>0</instances>
	<memoryPerInstance>4</memoryPerInstance>
</tool>

Converters again are specified the same way as analysis tools with some exceptions:

  • One additional variable can be used in <path> and <run>:
Variable Meaning
%RESULT_FILE% Result file of the associated analysis tool
  • The <questions> element in this case refers to the analysis tools (separated by ,) associated with this converter. (In the example only AwesomeDroid is associated.)
  • The elements <runOnExit>, <runOnSuccess>, <runOnFail> and <runOnAbort> are not supported for converters, yet.

Complete Example

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<config>
    <androidPlatforms>path/to/android/platforms</androidPlatforms>
    <maxMemory>8</maxMemory>
    <tools>
        <tool name="AwesomeDroid" version="1.3.3.7">
            <priority>0</priority>
            <priority feature="TEST">2</priority>
            <path>/path/to/AwesomeDroid</path>
            <run>/path/to/AwesomeDroid/run.sh %MEMORY% %ANDROID_PLATFORMS% %APP_APK%</run>
            <runOnExit>/path/to/AQL-System/flushMemory.sh</runOnExit>
            <runOnSuccess>/path/to/AwesomeDroid/success.sh</runOnSuccess>
            <runOnFail>/path/to/AwesomeDroid/fail.sh</runOnFail>
            <runOnAbort>/path/to/AQL-System/killpid.sh %PID%</runOnAbort>
            <result>/path/to/AwesomeDroid/results/%APP_APK_FILENAME%_result.txt</result>
            <questions>IntraApp</questions>
            <instances>0</instances>
            <memoryPerInstance>4</memoryPerInstance>
        </tool>
    </tools>
    <preprocessors>
        <tool name="AwesomePreprocessor" version="1.3.3.8">
            <priority>0</priority>
            <path>/path/to/AwesomePreprocessor</path>
            <run>/path/to/AwesomePreprocessor/run.sh %APP_APK%</run>
            <runOnExit>/path/to/AQL-System/flushMemory.sh</runOnExit>
            <runOnAbort>/path/to/AQL-System/killpid.sh %PID%</runOnAbort>
            <result>/path/to/AwesomePreprocessor/results/%APP_APK_FILENAME%_preprocessed.apk</result>
            <questions>TEST</questions>
            <instances>0</instances>
            <memoryPerInstance>4</memoryPerInstance>
        </tool>
    </preprocessors>
    <operators>
        <tool name="AwesomeOperator" version="1.3.3.9">
            <priority>0</priority>
            <path>/path/to/AwesomeOperator</path>
            <run>/path/to/AwesomeOperator/run.sh %ANSWERS%</run>
            <runOnExit>/path/to/AQL-System/flushMemory.sh</runOnExit>
            <runOnAbort>/path/to/AQL-System/killpid.sh %PID%</runOnAbort>
            <result>/path/to/AwesomeOperator/results/%ANSWERSHASH%.xml</result>
            <questions>CONNECT(*)</questions>
            <instances>1</instances>
            <memoryPerInstance>4</memoryPerInstance>
        </tool>
    </operators>
    <converters>
        <tool name="AwesomeDroidConverter" version="1.3.3.7">
            <path>/path/to/AwesomeDroidConverter</path>
            <run>/path/to/AwesomeDroidConverter/run.sh %RESULT_FILE% results/%APP_APK_FILENAME%.xml</run>
            <result>/path/to/AwesomeDroidConverter/results/%APP_APK_FILENAME%.xml</result>
            <questions>AwesomeDroid</questions>
            <instances>0</instances>
            <memoryPerInstance>4</memoryPerInstance>
        </tool>
    </converters>
</config>

Option 2: Use the Config Wizard

You find the ConfigWizard in the Help menu.
Alternatively you can launch it as follows:

java -jar AQL-System-1.1.1 -cw

The screenshot below shows the Config Wizard. All elements explained before can easily be edited here as well.

Screenshot of the Configuration Wizard

  • The environmental properties can be defined at 1.
  • New tools of any kind can be added at 2.
  • To edit a tool:
    • Select it, for example by clicking on 3.
    • Edit its properties on the right hand side
    • Apply the changed by clicking at 4.
  • To continue with the configuration you have set up click on 5.
You can’t perform that action at this time.