diff --git a/README.md b/README.md index 6181280..628ee74 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,12 @@ The provided source code enables to rebuild Docker and Singularity images for se - Docker images: https://hub.docker.com/u/histausse (or see full list at the end of this README) - Singularity images: https://zenodo.org/records/10980349 -The Docker image provides an interative container to the user for analyzing an APK file. The Singularity image helps to run batch analysis for a dataset of applications on a Singularity cluster. Additionally, the source code contains scripts for extracting the status of each APK analysis (failed/finished) and some characteristics (time, memory) and pushing these values in a database for further statistics. +The Docker image provides an interactive container to the user for analyzing an APK file. The Singularity image helps to run batch analysis for a dataset of applications on a Singularity cluster. Additionally, the source code contains scripts for extracting the status of each APK analysis (failed/finished) and some characteristics (time, memory) and pushing these values in a database for further statistics. The input data and pre-computed output data are provided from [outside this repository](https://zenodo.org/records/10144014). +If someone wants to reuse a specific analyzing tool, without installing it and by using our Docker images, have a look at [the end of the readme](#reusing-a-specific-tool). + ## Data Some data are needed to reproduce the experiment (at least, the androzoo indexes we used to sample our dataset). Those data are too heavy to be stored in a git repository, so they need to be downloaded from zenodo to the root of this repository: @@ -74,8 +76,6 @@ cd rasta_exp cd .. ``` -(To avoid to rebuild these containers, we will upload them to the Docker hub repository when the paper is published.) - The container and binary of Perfchecker is not provided as the Perfchecker binary is only available on demand. ## Running experiments @@ -89,9 +89,9 @@ for archive in $(ls data/results/archives/status_set*.tgz); do tar -xzf ${archiv tar -xzf data/results/archives/status_drebin.tgz --directory data/results/reports/drebin ``` -They can also be regenerated by recomputing our experiments. +They can also be regenerated by recomputing all our experiments. You will need some weeks or months... -To run the experiment using a Singularity image hosted on your own computer, you must simplify the `settings.ini` file that is intended to run on Singularity cluster. This file is located in the `rasta_exp` diretory. The following 3 lines is sufficient to configure the experiment for running on your local computer: +To run the experiment using a Singularity image hosted on your own computer, you must simplify the `settings.ini` file that is intended to run on Singularity cluster. This file is located in the `rasta_exp` directory. The following 3 lines is sufficient to configure the experiment for running on your local computer: ``` [AndroZoo] @@ -131,11 +131,11 @@ To re-generate the database from the JSON reports of the previous experiments: ./rasta_data_manipulation/make_db.sh ./data ``` -Generating the database require an androzoo API key and a lot of times because we download the apks to get there total dex size (the value indicated in latest.csv only take into account the size of `classes.dex` and not the sum of the size of all dex file when they are more than one). +Generating the database requires an androzoo API key and a lot of times because we download the apks to get there total dex size (the value indicated in latest.csv only take into account the size of `classes.dex` and not the sum of the size of all dex file when they are more than one). ## Database Usage -Most of the results presented in the paper can be extracted with: +Most of the results presented in the paper can be regenerated from the database using the following script: ``` ./rasta_data_manipulation/extract_result.sh ./data @@ -272,6 +272,8 @@ root@e3c39c14e382:/# ls /mnt/ E29CCE76464767F97DAE039DBA0A0AAE798DF1763AD02C6B4A45DE81762C23DA.apk report stderr stdout ``` +The report directory contains the result of the time command. The stdout and stderr contains the trace of execution of the tool on the APK. If extra files are generated by the tool, you should find them in the this directory. + The `run.sh` script can be customized to modify the run parameters used for this tool. The script that is copied into the Docker image is located at `rasta_exp/docker//home_build/run.sh`.