Skip to content

Home

Jump to bottom
Sebastiaan Alvarez Rodriguez edited this page Aug 19, 2019 · 1 revision

Welcome to the Meizodon wiki!

In this wiki, we will provide clear documentation/explanation on:
How to add a method to Meizodon?

First we give a summary of all requirements that must be fullfilled after adding a method. Then, we give a step by step guide on adding a method.

Requirements Summary

To add an analysis tool named HelloWorld, per example, the following must be satisfied:

  • A directory HelloWorld must exist in Meizodon/installers.
  • If HelloWorld needs dependencies and/or packages downloaded, a config file named conf.conf must exist in Meizodon/installers/HelloWorld. How to make one? see next section, named 'conf.conf'
  • A file install.py must exist in Meizodon/installers/HelloWorld, containing specified methods below, in section install.py.
  • A file run.py must exist in Meizodon/installers/HelloWorld, containing specified methods below, in section run.py
  • A file analyse.py must exist in Meizodon/installers/HelloWorld, containing specified methods below, in section analyse.py

Deps and pkgs: A dependency is a package that will reside in the Meizodon/installed/dependencies/<depdir> directory. A package is a... package that will reside in the Meizodon/installed/<tool_name>/<pkgdir> directory. Here, <depdir> and <pkgdir> are specified by you, in the config file. '' (empty string) is default when not specified in config.

conf.conf

Configs tell Meizodon to download certain packages/dependencies, and where to store the extracted result. Configs must follow convention:

deps {
    somedep {
        dir=somedir
        url=https://somesite.com/get/Downloads/file.tar.xz
    }
    somedep.jar {
        dir=anotherdir/subdir
        url=https://download.site.com/repository/cool.jar
    }
}
pkgs {
    apackage {
        url=https://github.com/someuser/project/archive/master.zip
    }
    ...

Here, a directory named 'somedep' will be created in Meizodon/installed/dependencies/. somedep will contain all contents of the extracted file.tar.xz. In the same directory, also a file named somedep.jar will be created.

Packages are in this case placed in Meizodon/installed/HelloWorld/. The contents of master.zip will be created there.

Do not specify dir=... (as in example config for apackage) if you wish to locate your dependency/package in the main dependency/package directory. Also, specifying dir= with only a newline following achieves this (but is less nice). Furthermore: No deps? Skip the deps {...} part.
No pkgs? Skip the pkgs {...} part.
Neither? Then don't make a conf.conf file

A dep needs to be installed in Meizodon/installed/dependencies/ and not in Meizodon/installed/dependencies/? For this dep, do not specify dir= attribute.
The above is also implemented for pkgs.

install.py

A file install.py has to be inside every installer directory. This file must implement the following methods:

    # Handles anything that needs to happen before installation (and before downloading)
    def pre_install(installerloc, installloc, deploc, support):
        return

    # Handles installation of component (after downloading and extracting has completed)
    def install(installerloc, installloc, deploc, support):
        return

    # Handles any loose ends after installing (e.g. deleting leftover files)
    def post_install(installerloc, installloc, deploc, support):
        return

    # Reconfigure component (e.g.: Drops database tables and rebuilds them)
    def reconfigure(installerloc, installloc, deploc, support):
        return

In this file, installer authors define what should be done at what time in installation processes and run processes. The following is very important: You should (!)only(!) ask for user input in preinstall() method, and you should put your unattended 'install' tasks in the install() method. This way, every installer asks user for input at the start of installation. The user supplies requested info, and then e.g. 42 minutes worth of unattended tasks start after that, allowing the user to leave his/her/its terminal unattended for these 42 minutes while the rest of installation commences. Requesting user input somewhere within these 42 minutes would mean the user has to look to his terminal for all that time, which is very annoying.

Function parameter explanation

  • installerloc
    Location of installer. In our example of HelloWorld, it will be <absolute path to Meizodon>/installer/HelloWorld/
  • installloc Location to install to. In our example, <absolute path to Meizodon>/installed/HelloWorld/
  • deploc Location of dependencies. Always <absolute path to Meizodon>/installed/dependencies/
  • support Object with helper functions and a state registrar. Please take a quick look at lib/supporter/support.py for functions, and at lib/stateholder/stateregistrar.py for the registrar.

run.py

A file run.py has to be inside every installer directory. This file must implement the following methods:

# Prepare for apk analysis launch. e.g. boot up a database
def prepare_run(installloc, deploc, apkpaths, resultpaths, support):
    return

# Run apk analysis
# Returns three booleans: warnings, success, timeout
def run(installloc, deploc, apkpath, resultpath, ramamount, timeout, support):
    return

# Clean up after apk analysis. e.g. shutdown a database
def post_run(installloc, deploc, apkpaths, resultpaths, support):
    return

Here, authors define what should be done before running apk analysis, while running apk analysis, and after running apk analysis. The run() function is to return whether warnings occured during apk analysis, whether fatal errors occured during apk analysis, and whether timeout has occured.

ramamount and timeout are variables which specify bounds to the apk analysis, on a voluntary basis. It is up to you, as author, to make sure the tool you develop remains within bounds as specified by ramamount, as well as timeout.

Also, important:

  • Specify user input only at prepare_run(), and perform only runtasks at run(). This way, a user is prompted with your questions at the beginning of running methods, together with all other methods he wants to use, and then he/she/it can leave his/her/its terminal unattended for some time, while not having to fear that some annoying method asks for additional user input after 20 minutes of running
  • Please do not print anything, and do not allow the called tool to print anything to standard output. This will look very chaotic when running multiple apk analysis instances at the same time. Instead, write everything from standard output to a file <absolute path to Meizodon>/results/<date and time>/HelloWorld/<apkname>/<outputlog name> and additional ../<errorlog name>. Both of these names can be retrieved by calling support.get_error_log() and support.get_out_log(), to remain consistent with other tools' logs.

Function parameter explanation

  • installloc Location to install to. In our example, <absolute path to Meizodon>/installed/HelloWorld/
  • deploc Location of dependencies. Always <absolute path to Meizodon>/installed/dependencies/
  • apkpath Absolute path to current apk file
  • apkpaths List of locations for all apk's. Note: They might be in any directory on the user's system, and should not be removed, nor should their parent directories be cluttered with temporary files and such
  • resultpath Absolute path to current designated result dir. Looks like <absolute path to Meizodon>/results/<date and time>/HelloWorld/<apkname>/
  • resultpaths List of locations where results of analysis are to be stored.
  • ramamount Amount of RAM (in GB's, integer) available to this apk analysis run.
  • timeout Amount of total time (in seconds, integer) available to the apk analysis run.
  • support Object with helper functions and a state registrar. Please take a quick look at lib/supporter/support.py for functions, and at lib/stateholder/stateregistrar.py for the registrar.

analyse.py

A file analyse.py has to be inside every installer directory. This file must implement the following methods:

# Prepare for analysis
# runresultpath is path where results of run are, which should be analysed
# analysisresultpath is path where result of analysis should be stored.
# support is a support-object
def prepare_analyse(runresultpath, analysisresultpath, support):
    return

# Analyse given results. 
# Return whether apk analysis suggests apk is malware
# analysepath is path where results of run are, which should be analysed
# resultpath is path where result of analysis should be stored.
def analyse(runresultpath, analysisresultpath, ramamount, support):
    return

In this file, authors define what should be done before running an analysis. During result analysis, one has total freedom to open files to write any results to. A call to the analyse() function, however, must return a boolean, which must be True if apk analysis result suggests apk is malware, otherwise False. Also, important: Specify user input only at prepare_analyse(), and perform only runtasks at run(). This way, a user is prompted with your questions at the beginning of running methods, together with all other methods he wants to use, and then he/she/it can leave his/her/its terminal unattended for some time, while not having to fear that some annoying method asks for additional user input after 20 minutes of running

Function parameter explanation

  • installloc Location to install to. In our example, <absolute path to Meizodon>/installed/HelloWorld/
  • deploc Location of dependencies. Always <absolute path to Meizodon>/installed/dependencies/
  • apkpath Absolute path to current apk file
  • apkpaths List of locations for all apk's. Note: They might be in any directory on the user's system, and should not be removed, nor should their parent directories be cluttered with temporary files and such
  • runresultpath Absolute path to current designated result dir. Looks like <absolute path to Meizodon>/results/<date and time>/HelloWorld/<apkname>/
  • analysisresultpath Absolute path to current designated analysis dir. Looks like <absolute path to Meizodon>/analysed/<date and time>/HelloWorld/<apkname>/
  • support Object with helper functions and a state registrar. Please take a quick look at lib/supporter/support.py for functions, and at lib/stateholder/stateregistrar.py for the registrar.

Sharing

Did everything work out? test whether your installer code, execution code and analysis code works, and then please make a branch named add_<method_name_here>, containing your added installer. Make a merge request. After that, we will handle addition of your code to the project. Sharing is caring! Someone on this planet will be very grateful to you for not having to program everything you created!

Clone this wiki locally