This is a repository for AntMonitor - a VPN-based packet capturing system for Android. For an overview of the project, please visit the project website.

• The core capabilities of AntMonitor to intercept and inspect outgoing packets are made available as a library - see the Using the AntMonitor Library section.
• For getting started with the AntMonitor app and library development, see Running the AntMonitor App.

AntMonitor is licensed under GPLv2.

The packet interception and inspection capabilities of AntMonitor have also been packaged as an Android library. If you wish to simply use that capability and write your own app from scratch, please refer to our other GitHub Project - AntMonitorExample.

For the rest of the document we will refer to the directory to which you have cloned the repo as CODE_ROOT.

• Download Android Studio
• Download the Android NDK
• Set the sdk.dir and the ndk.dir keys found in the CODE_ROOT/app/local.properties file to point to your Android SDK and Android NDK installation paths, respectively.
• Click the "Run App" button within Android Studio to run the app on a connected Android device or emulator.
• If you get the error "Gradle sync failed: No toolchains found in the NDK toolchains folder for ABI with prefix: mips64el-linux-android", run

cd $ANDROID_SDK_ROOT/ndk-bundle/toolchains
ln -s aarch64-linux-android-4.9 mips64el-linux-android
ln -s arm-linux-androideabi-4.9 mipsel-linux-android

We provide three sets of Javadocs that you can refer to, depending on how you want to use AntMonitor:

1. An API overview of the AntMonitor library: refer to this if you only want to use the AntMonitor library as-is.
2. Development Documentation of the AntMonitor library: refer to this if you want to change/understand the internals of the AntMonitor library.
3. Development Documentation of the AntMonitor app: refer to this if you want to change/understand the AntMonitor app.

If you need to update the documentation, refer to UPDATING_DOCS.md.

If you create a publication (including web pages, papers published by a third party, and publicly available presentations) using the AntMonitor app or the AntMonitor Library, please cite the corresponding paper as follows:

@article{shuba2016antmonitor,
  title={AntMonitor: A System for On-Device Mobile Network Monitoring and its Applications},
  author={Shuba, Anastasia and Le, Anh and Alimpertis, Emmanouil and Gjoka, Minas and Markopoulou, Athina},
  journal={arXiv preprint arXiv:1611.04268},
  year={2016}
}

We also encourage you to provide us ([email protected]) with a link to your publication. We use this information in reports to our funding agencies.

If you find a bug, please open a GitHub issue. Please provide the following information when reporting an issue:

• The Android version used
• Steps to reproduce the problem
• Stack trace, if applicable (for any crashes encountered)

There are several bugs in the TLS interception capability, and as of Android 7.0, it is no longer possible to intercept TLS connections with AntMonitor alone. However, you can use it in conjunction with any of the tricks discussed here.

Further, there have been additional changes to TLS in Android 11+ and we will push a fix for them soon.