> For the complete documentation index, see [llms.txt](https://pcastagnaro.gitbook.io/pentest-bug-bounty-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pcastagnaro.gitbook.io/pentest-bug-bounty-resources/pentest-bounty-resources/mobile/android/dast-1/non-rooted-devices/bypass-ssl-pinning-non-rooted-devices/bypass-ssl-pinning-method-1-apk-mitm.md).
# Method 1: apk-mitm
[apk-mitm](https://github.com/shroudedcode/apk-mitm) is a CLI application that prepares Android APK files for HTTPS inspection that automates the entire process. In the [How it Works](https://app.gitbook.com/@pcastagnaro/s/pentest-cheat-sheet/~/drafts/-MOZ7UMFaPaMrZ2BqOp6/pentest-book/mobile/android/dast-1/bypass-ssl-pinning/bypass-ssl-pinning-method-1-apk-mitm#how-it-works) section you will find more details, but as a summary all you have to do is give it an APK file and `apk-mitm` will:
* decode the APK file using [Apktool](https://ibotpeaches.github.io/Apktool/)
* modify the app's `AndroidManifest.xml` to make it [`debuggable`](https://developer.android.com/guide/topics/manifest/application-element#debug)
* modify the app's [Network Security Configuration](https://developer.android.com/training/articles/security-config) to allow user-added certificates ([see more details](https://app.gitbook.com/@pcastagnaro/s/pentest-cheat-sheet/~/drafts/-MOZ7UMFaPaMrZ2BqOp6/pentest-book/mobile/android/dast-1/bypass-ssl-pinning/bypass-ssl-pinning-method-1-apk-mitm#how-it-works))
* [insert `return-void` opcodes](https://mobile-security.gitbook.io/mobile-security-testing-guide/android-testing-guide/0x05c-reverse-engineering-and-tampering#patching-example-disabling-certificate-pinning) to disable [certificate pinning](https://owasp.org/www-community/controls/Certificate_and_Public_Key_Pinning#what-is-pinning) logic
* encode the patched APK file using [Apktool](https://ibotpeaches.github.io/Apktool/)
* sign the patched APK file using [uber-apk-signer](https://github.com/patrickfav/uber-apk-signer)
You can also use `apk-mitm` to [patch apps using Android App Bundle](https://github.com/shroudedcode/apk-mitm#patching-app-bundles) and rooting your phone is **not** required.
## Requirements
1. [Node JS](https://app.gitbook.com/@pcastagnaro/s/pentest-cheat-sheet/~/drafts/-Lu-mPVCPQo8hOjAP7fk/mobile/android/dast-1/dast#install-node-js)
2. [apk-mitm](https://app.gitbook.com/@pcastagnaro/s/pentest-cheat-sheet/~/drafts/-Lu-mPVCPQo8hOjAP7fk/mobile/android/dast-1/dast#install-apk-mitm)
3. Apktool
`apk-mitm` automates the entire process. All you have to do is give it an APK file and `apk-mitm` will:
* decode the APK file using [Apktool](https://ibotpeaches.github.io/Apktool/)
* modify the app's `AndroidManifest.xml` to make it [`debuggable`](https://developer.android.com/guide/topics/manifest/application-element#debug)
* modify the app's [Network Security Configuration](https://developer.android.com/training/articles/security-config) to allow user-added certificates
* [insert return-void opcodes](https://github.com/OWASP/owasp-mstg/blob/master/Document/0x05c-Reverse-Engineering-and-Tampering.md#patching-example-disabling-certificate-pinning) to disable [certificate pinning](https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning#What_Is_Pinning.3F) logic
* encode the patched APK file using [Apktool](https://ibotpeaches.github.io/Apktool/)
* sign the patched APK file using [uber-apk-signer](https://github.com/patrickfav/uber-apk-signer)
## Install Node JS
{% tabs %}
{% tab title="Mac OS" %}
```bash
brew install nodejs
```
{% endtab %}
{% tab title="Linux" %}
```bash
sudo apt install nodejs
```
{% endtab %}
{% endtabs %}
## Install/update apk-mitm
{% tabs %}
{% tab title="Install" %}
```bash
npm install -g apk-mitm
```
{% endtab %}
{% tab title="Update" %}
```bash
npm update -g apk-mitm
```
{% endtab %}
{% endtabs %}
## Patch APK
```
apk-mitm example.apk
```
{% hint style="warning" %}
If the app uses Google Maps and the map is broken after patching, then the app's API key is probably [restricted to the developer's certificate](https://cloud.google.com/docs/authentication/api-keys#api_key_restrictions). You'll have to [create your own API key](https://console.cloud.google.com/google/maps-apis/apis/maps-android-backend.googleapis.com) without restrictions and replace it in the app's `AndroidManifest.xml` file.
If `apk-mitm` crashes while decoding or encoding the issue is probably related to [Apktool](https://ibotpeaches.github.io/Apktool/). Check [their issues on GitHub](https://github.com/iBotPeaches/Apktool/issues) to find possible workarounds. If you happen to find an Apktool version that's not affected by the issue, you can instruct `apk-mitm` to use it by specifying the path of its JAR file through the `--apktool` option.
{% endhint %}
You can now install the `example-patched.apk` file on your Android device and use a proxy like [Charles](https://www.charlesproxy.com/), [mitmproxy](https://www.charlesproxy.com/), [Burp Suite](https://portswigger.net/burp), etc, to look at the app's traffic.
## Install APK (from adb)
{% tabs %}
{% tab title="Bash" %}
```bash
adb <-s DEVICE_ID> install example-patched.apk
```
{% endtab %}
{% endtabs %}
## How it Works
### Decode the APK file
Using [Apktool](https://ibotpeaches.github.io/Apktool/)
### Modify the app's `AndroidManifest.xml`
To make it [`debuggable`](https://developer.android.com/guide/topics/manifest/application-element#debug)
### Modify the app's [Network Security Configuration](https://developer.android.com/training/articles/security-config)
To allow user-added certificates. The Network Security Configuration feature lets apps customize their network security settings in a safe, declarative configuration file without modifying app code. These settings can be configured for specific domains and for a specific app. So you can **customize which Certificate Authorities (CA) are trusted for an app's secure connections**. For example, trusting particular self-signed certificates or restricting the set of public CAs that the app trusts.
Once your target APK is properly disassembled, look for `AndroidManifest.xml` at the root folder and add the following attribute to the `application` element:
```
...
```
That attribute points to the file `res/xml/network_security_config.xml` inside your project. If it doesn't, create it now and change its contents to be like this:
```
```
**This rule tells the Android system to accept any system or user certificates, overriding default behavior.** See [this page](https://android-developers.googleblog.com/2016/07/changes-to-trusted-certificate.html) for other overriding options.
### [insert `return-void` opcodes](https://mobile-security.gitbook.io/mobile-security-testing-guide/android-testing-guide/0x05c-reverse-engineering-and-tampering#patching-example-disabling-certificate-pinning)
To disable [certificate pinning](https://owasp.org/www-community/controls/Certificate_and_Public_Key_Pinning#what-is-pinning) logic
### Encode the patched APK file
Using [Apktool](https://ibotpeaches.github.io/Apktool/)
### Sign the patched APK file
Using [uber-apk-signer](https://github.com/patrickfav/uber-apk-signer)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://pcastagnaro.gitbook.io/pentest-bug-bounty-resources/pentest-bounty-resources/mobile/android/dast-1/non-rooted-devices/bypass-ssl-pinning-non-rooted-devices/bypass-ssl-pinning-method-1-apk-mitm.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.