Table of Contents
A man-in-the-middle (MitM) proxy is a program designed to intercept network requests between a client and server. The basic idea is to pretend to be the server to the client, and pretend to be the client to the server, while the proxy sits in the middle decoding traffic from both sides.
Note that man-in-the-middle proxy is descriptive phrasing for a common traffic interception technique employed by a plethora of different programs, often under different labels (debugging proxy, web security suite, etc), while mitmproxy is a specific application which employs this technique.
See How mitmproxy works if you're interested in a more detailed explanation of the concepts and technologies being used.
Intercepting HTTP(S) requests from mobile apps allows you to inspect and modify individual network requests made by the app. This can be beneficial for debugging your own applications, emulating requests on other devices, reverse engineering undocumented APIs, and more.
In a simple, real world example: You purchase a book from a mobile app and you would like to back it up locally in case the service eventually closes. Unfortunately, this app prevents you from easily accessing your purchased content outside of their walled garden. You may be able to inspect and emulate the requests made by the app in order to access the file(s) on another device.
There are many different programs which will allow you to intercept HTTP(S) traffic. Your specific choice is not super important here, as they should all provide similar functionality for basic use. UI, ease-of-setup, scriptability, and adjacent tool offerings may differ.
To keep things simple, this guide will focus on two popular, multiplatform, open source applications which I consider to be standout in some area. Feel free to search elsewhere, test various applications for different platforms, and use whatever you prefer.
- HTTP Toolkit - Open source, freemium, simple GUI, 1-click setup for many common uses, great for getting started
- mitmproxy - Open source, free, console or web UI, scriptable with Python, extremely flexible
- Burp Suite - Proprietary, freemium
- Charles - Proprietary, paid
- Fiddler - Proprietary, freemium
- and more...
Broadly, we are going to:
- Install our preferred MitM Proxy application
- Set our client device to connect through this proxy
- Add our MitM certificate to our client device's certificate store
Exact execution of these steps will vary slightly by program and platform, but the basic process should remain similar. The official documentation for your chosen MitM proxy will likely have more specific and detailed instructions.
- A client device (Android/iOS device or emulator)
- MitM proxy application of your choice
Since Android 7, apps ignore user provided certificates by default. As most apps do not opt in to trusting user certificates, you will need to place your MitM certificate in the system certificate store. This requires a rooted device or emulator.
If you do not have access to a rooted device or emulator, you will need to patch any applications you would like to monitor. See Certificate Pinning for some related information (note that this itself is not certificate pinning, but circumvention of both techniques require similar tool and skill sets).
Setup for intercepting Android traffic using HTTP Toolkit is automated. Ensure your device or emulator is connected to ADB (most emulators should be by default), launch HTTP Toolkit, and select Android Device via ADB. This will complete the entire setup and allow you to begin intercepting HTTP and, on a rooted device, HTTPS traffic right away.
If you'd rather not or don't know how to connect your device to ADB, you can instead opt to use Android Device via QR Code, which is slightly more manual and will not automatically place your certificate in the system store. This means you will face the same trust issues mentioned above for almost all apps, making it largely useless without additional setup.
See HTTP Toolkit's docs for more detail
Setup for intercepting Android traffic using mitmproxy is manual.
- Start mitmproxy
- Find the local IP of your computer (or whatever device is running mitmproxy)
- Go to your Android device's WiFi settings and configure your WiFi proxy settings to use mitmproxy (your computer's IP and port 8080 by default)
- You are now set up to intercept HTTP traffic from your Android device, but this is not particularly useful in most cases, so we continue
- Open your browser on your Android device.
- Navigate to http://mitm.it (note http, NOT https)
- Tap to download the certificate for Android
- Open Settings -> Security -> Encryption & Credentials -> Install a certificate -> CA certificate (exact setting locations/titles may vary)
- Choose the certificate you just downloaded
- You are now set up to intercept HTTPS traffic from your Android device, but the certificate has not been placed in the system store, leading to the trust issues mentioned above
- Follow one of the methods detailed in mitmproxy's docs for installing a system CA on Android emulator
- The topic is a bit too in-depth to detail succinctly here, but several options are explained well in their docs
- Due to mitmproxy's scripting support, it's entirely possible to automate adding the system CA like HTTP Toolkit does. I have poorly done so in a previous gist, but would still recommend using HTTP Toolkit if you're wanting things to "just work".
iOS does not require jailbreaking to fully trust a custom certificate. You may still encounter Certificate Pinning in some apps.
Setup for intercepting iOS traffic using HTTP Toolkit is manual.
- Launch HTTP Toolkit
- Find the local IP of your computer (or whatever device is running HTTP Toolkit)
- Go to your iOS device's WiFi settings and configure your WiFi proxy settings to use HTTP Toolkit (your computer's IP and port 8000 by default)
- You are now set up to intercept HTTP traffic from your iOS device, but this is not particularly useful in most cases, so we continue
- Open your browser on your iOS device
- Navigate to http://amiusing.httptoolkit.tech/certificate (note http, NOT https)
- A configuration profile should download
- Navigate to Settings -> Profile Downloaded and tap Install in the top right
- Navigate to Settings -> General -> About -> Certificate Trust and enable "Full trust" for the HTTP Toolkit certificate
See HTTP Toolkit's docs for more detail
Setup for intercepting iOS traffic using mitmproxy is manual.
- Start mitmproxy
- Find the local IP of your computer (or whatever device is running mitmproxy)
- Go to your iOS device's WiFi settings and configure your WiFi proxy settings to use mitmproxy (your computer's IP and port 8080 by default)
- You are now set up to intercept HTTP traffic from your iOS device, but this is not particularly useful in most cases, so we continue
- Open your browser on your iOS device
- Navigate to http://mitm.it (note http, NOT https)
- Tap to download a configuration profile for iOS
- Navigate to Settings -> Profile Downloaded and tap Install in the top right
- Navigate to Settings -> General -> About -> Certificate Trust and enable "Full trust" for the mitmproxy certificate
Some apps may refuse to connect through your proxy despite a proper setup and trusted certificate. This is often due to a technique called certificate pinning, in which apps use a baked-in list of certificates they consider trustworthy, rather than using the device's own list.
Circumventing this requires reverse engineering the app in some way and is largely out of scope for this guide. If you're on Android (and lucky enough), this may be extremely simple using something like apk-mitm.
There are many technical articles online covering this and other RE-related topics if you would like to research further.
- mitmproxy docs - much of the info in this gist
- HTTP Toolkit docs - much of the info in this gist
- Best-README-Template - base markdown for this gist