Home

Awesome

ACVTool 2.3.2 Multidex

Software license Python version versions DOI

acvtool.py instruments an Android app and produces its code coverage without original source code. Code coverage is based on Smali representation of the bytecode.

Demonstration video of ACVTool.

Prerequisites

  1. Windows/OSX/Ubuntu.
  2. Java version 1.8.
  3. Android SDK.
  4. Python 3.

Installation

  1. Run the pip command to install dependencies:

    $ cd acvtool
    $ pip install -e .
    $ acv -h
    

    When successfully installed, you will be able to execute acv -h. This command will create the working directory "~/acvtool" and the configuration file "~/acvtool/config.json".

  2. Download the ACVPatcher binary for your system. ACVPatcher replaces usage of Apktool, zipalign, apksigner. ACVPatcher is a separated binary since it was implemented with .NET Core.

    ACVPatcher needs to be trusted to work:

    • (OSX/Linux) chmod +x acvpatcher
    • Call the Context Menu, Tap Open, Open the App From Not Trusted Developer
  3. Specify absolute paths to the Android tools at "~/acvtool/config.json" (%userprofile%\acvtool\config.json in Windows) for the following variables.

    • AAPT
    • ZIPALIGN
    • ADB
    • APKSIGNER
    • ACVPATCHER

    3.1. Windows configuration example

    {
        "AAPT": "C:/users/ME/appdata/local/android/sdk/build-tools/25.0.1/aapt2.exe",
        "ZIPALIGN": "C:/users/ME/appdata/local/android/sdk/build-tools/25.0.1/zipalign.exe",
        "ADB": "C:/users/ME/appdata/local/android/sdk/platform-tools/adb.exe",
        "APKSIGNER": "C:/users/ME/appdata/local/android/sdk/build-tools/24.0.3/apksigner.bat",
        "ACVPATCHER": "D:/distr/acvpatcher.exe"
    }
    

    3.2. OSX, Linux configuration example

    {
        "AAPT": "[$HOME]/Library/Android/sdk/build-tools/25.0.3/aapt2",
        "ZIPALIGN": "[$HOME]/Library/Android/sdk/build-tools/25.0.3/zipalign",
        "ADB": "[$HOME]/Library/Android/sdk/platform-tools/adb",
        "APKSIGNER": "[$HOME]/Library/Android/sdk/build-tools/24.0.3/apksigner",
        "ACVPATCHER": "~/distr/ACVPatcher-osx/acvpatcher"
    }
    

Workflow

Steps:

  1. Instrument the original APK with ACVTool [instrument <path> --wd <working_dir>]
  2. Install the instrumented APK in the Android emulator or device. [install <path>]
  3. Activate the app for coverage measurement [activate <package_name>] (alternatively, [start <package_name>])
  4. Test the application (launch it!)
  5. Make a snap [snap <package_name>]
  6. Apply the extracted coverage data onto the smali code tree [cover-pickles <package_name> --wd <working_dir>]
  7. Generate the code coverage report [report <package_name> --wd <working_dir>]

Example: instruction coverage measurement

  1. Instrument the original APK with ACVTool, and run the emulator:

    $ acv instrument test_apks/snake.apk --wd wd
    
    $ ANDROID_HOME/tools/emulator -avd [device-name] 
    
  2. Install the instrumented APK in the Android emulator or device:

    $ acv install ./wd/instr_snake.apk
    
  3. Activate the app:

    $ acv activate com.gnsdm.snake
    
  4. Test the application.

    Interact with the application.

  5. Do the first coverage snapshot:

    $ acv snap com.gnsdm.snake --wd wd
    
  6. Apply coverage data to the Smali code tree:

    $ acv cover-pickles com.gnsdm.snake --wd wd
    
  7. Generate the code coverage report.

    $ acv report com.gnsdm.snake --wd wd
    

The code coverage report is available at "./wd/report/main_index.html"

Example: App Shrinking

The shrunk version is here ./wd/shrunk.apk.

Full list of commands

$ acv <command> <path> [-/--options]

positional arguments:

commandargumentdescriptionoptions
instrumentpath_to_apkInstruments an apk--wd, --dbgstart, --dbgend, --r, --i
installpath_to_apkInstalls an apk.
uninstallpath_to_apkUninstalls an apk.
activatepackage_namePrepared the app for measurements.
startpackage_nameStarts runtime coverage data collection.
stop-Stops runtime coverage data collection.
snappackage_nameSaves coverage data.--wd
flushpackage_nameFlushes runtime coverage information.
calculatepackage_nameLogs current coverage into logcat.
reportpackage_nameProduces a report.--wd, --shrink
signapk_pathSigns and alignes an apk.
shrinkpkg, apk_pthGenerates shrunk code.--wd

optional arguments:

optionargumentdescription
-h, --help-Shows this help message and exit.
--version-Shows program's version number and exits.
--wd<result_directory>Path to the directory where the working data is stored. Default: .\smiler\acvtool_working_dir.
--dbgstart<methods_number>For troubleshooting purposes. The number of the first method to be instrumented. Only methods from DBGSTART to DBGEND will be instrumented.
-r, --r-Working directory (--wd) will be overwritten without asking.
-i, --i-Installs the application immidiately after instrumenting.

References

Please cite our paper:

@article{pilgun2020acvtool,
  title={Fine-grained code coverage measurement in automated black-box Android testing},
  author={Pilgun, Aleksandr and Gadyatskaya, Olga and Zhauniarovich, Yury and Dashevskyi, Stanislav and Kushniarou, Artsiom and Mauw, Sjouke},
  journal={ACM Transactions on Software Engineering and Methodology (TOSEM)},
  volume={29},
  number={4},
  pages={1--35},
  year={2020},
  publisher={ACM New York, NY, USA}
}
@inproceedings{pilgun2020acvcut,
  title={Don't Trust Me, Test Me: 100\% Code Coverage for a 3rd-party Android App},
  author={Pilgun, Aleksandr},
  booktitle={2020 27th Asia-Pacific Software Engineering Conference (APSEC)},
  pages={375--384},
  year={2020},
  organization={IEEE}
}

Contributions

Contributions to ACVTool is a subject to Contributer License Agreement (to be defined).

License

Copyright (c) 2024 Aleksandr Pilgun

Licensed under the Apache License, Version 2.0 (the "License"); you may not use ACVTool files from this repository except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

By sharing this code, the author of ACVTool does not grant or waive any patent rights beyond the scope of this ACVTool repository.

Aknowledgement

The initial development of ACVTool took place at the University of Luxembourg as part of the FNR DroidMod 2016-2020 research project. This project would not have been possible without the invaluable support of my coauthors: Dr. Olga Gadyatskaya, Dr. Yury Zhauniarovich, and Prof. Dr. Sjouke Mauw.