ACVTool is a novel tool for measuring black-box code coverage of Android applications.
Switch branches/tags
Nothing to show
Clone or download
Latest commit f485546 Dec 9, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
smiler mem stats, publications Dec 9, 2018
.gitignore mem stats, publications Dec 9, 2018
LICENSE release Oct 2, 2018
acvtool.py mem stats, publications Dec 9, 2018
readme.md mem stats, publications Dec 9, 2018
requirements.txt release Oct 2, 2018
setup.py release Oct 2, 2018

readme.md

ACVTool

acvtool.py instruments Android apk 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 version 2.7.

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. 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

    2.1. Windows configuration example

    {
        "AAPT": "[%userprofile%]\\appdata\\local\\android\\sdk\\build-tools\\25.0.1\\aapt.exe",
        "ZIPALIGN": "[%userprofile%]\\appdata\\local\\android\\sdk\\build-tools\\25.0.1\\zipalign.exe",
        "ADB": "[%userprofile%]\\appdata\\local\\android\\sdk\\platform-tools\\adb.exe",
        "APKSIGNER": "[%userprofile%]\\appdata\\local\\android\\sdk\\build-tools\\24.0.3\\apksigner.bat",
    }

    2.2. OSX, Linux configuration example

    {
        "AAPT": "[$HOME]/Library/Android/sdk/build-tools/25.0.3/aapt",
        "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",
    }

Workflow

Steps:

  1. Instrument the original APK with ACVTool. [instrument ]
  2. Install the instrumented APK in the Android emulator or device. [install ]
  3. Initiate instrumentation process in the emulator. [start ]
  4. Test the application. (just click the installed app)
  5. Finish instrumention process in the emulator. [Press Ctrl+C]
  6. Generate the code coverage report. [report -p <pickle_path>]

Details:

  1. Instrument an apk:

    $ acv instrument <path>

    An APK file and <package_name>.pickle file will be created.

  2. Install/uninstall the app in emulator/device:

    $ acv install <path>
    $ acv uninstall <path>
  3. Initiate instrumentation process of the APK:

    $ acv start <package.name>
  4. Now test the application manually or automatically.

    Note: Acvtool itself does not generate tests.

  5. Finalize testing by pressing Ctrl+C. Code coverage file will be produced at the emulator/device side.

  6. Generate the code coverage report after tesing an app:

    $ acv report <package.name> -p <path>

Example

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

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

    $ acv install ~/acvtool/acvtool_working_dir/instr_snake.apk
  3. Initiate instrumentation process in the emulator:

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

    Interact with the application a little bit.

  5. Finish instrumention process in the emulator.

    Press "Ctrl+c" in the console where the acvtool has been launched with "acv start".

  6. Generate the code coverage report.

    $ acv report com.gnsdm.snake -p  ~/acvtool/acvtool_working_dir/metadata/com.gnsdm.snake.pickle

The code coverage report will be located at "~/acvtool/acvtool_working_dir/report/com.gnsdm.snake/report"

Full list of commands

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

positional arguments:

command argument description options
instrument path_to_apk Instruments an apk --wd, --dbgstart, --dbgend, --r, --i
install path_to_apk Installs an apk.
uninstall path_to_apk Uninstalls an apk.
start package.name Starts runtime coverage data collection.
stop - Stops runtime coverage data collection.
report package_name Produces a report. -p(required), -o, -ec
sign apk_path Signs and alignes an apk.

optional arguments:

option argument description
-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.
-p <pickle_file> Path to the Pickle file, that was generated during the instrumentation process (required).
-o <output_dir> Output directory.
-ec <ec_dir> The directory with the code coverage binary files pre-loaded from the emulator.

Dependencies

References

ACVTool was demonstrated at ACM SIGSAC Conference on Computer and Communications Security 2018, Toronto, October 15-19.

Please use the following bibtex references to cite our papers:

@inproceedings{pilgun2018acvtool,
  title={An Effective Android Code Coverage Tool},
  author={Pilgun, Aleksandr and Gadyatskaya, Olga and Dashevskyi, Stanislav and Zhauniarovich, Yury and Kushniarou, Artsiom},
  booktitle={Proceedings of the 2018 ACM SIGSAC Conference on Computer and Communications Security},
  pages={2189--2191},
  year={2018},
  organization={ACM}
}
@inproceedings{DGPZ2018cc_influence,
  title={The Influence of Code Coverage Metrics on Automated Testing Efficiency in Android},
  author={Dashevskyi, Stanislav and Gadyatskaya, Olga and Pilgun, Aleksandr and Zhauniarovich, Yury},
  booktitle={Proceedings of the 2018 ACM SIGSAC Conference on Computer and Communications Security},
  pages={2216--2218},
  year={2018},
  organization={ACM}
}

License

Copyright © 2018 SnT, University of Luxembourg

Licensed under the Apache License, Version 2.0 (the "License"); you may not use the files under 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.