Inspecting TLS-encrypted traffic with mitmproxy

Mitmproxy is a free, open-source tool whose killer feature is the ability to inspect Transport Layer Security (TLS)-encrypted mobile phone app traffic. The tool is superior to Wireshark when it comes to examining TLS-encrypted network traffic, and its zero-dollar price point beats out the not-cheap Burp Suite. The only downside (upside for some) is that mitmproxy is primarily a command line tool, unlike the swish Burp Suite GUI.

What is that app doing? Who is it talking to? What information is it collecting on your phone or tablet? What about websites on your laptop? Maybe you’re building your own app and want to double-check the network traffic is suitably encrypted to comply with GDPR, CCPA and other regulatory obligations. Maybe you’re a pen tester breaking apps and websites for a living or examining IoT device traffic.

For all these use cases, mitmproxy is a fine choice. Written in Python, mitmproxy is distributed under an open-source license, and so is easily extensible and scalable in ways that would be impossible with a proprietary tool like Burp Suite.

Here’s what you need to know to get started.

Mitmproxy for apps

Mitmproxy’s sweet spot is inspecting TLS-encrypted app traffic. The tool makes it easy to install a self-signed root certificate on your phone to decrypt network traffic. (This doesn’t work if the app uses certificate pinning, which remains uncommon, but even then there are workarounds, an advanced topic not covered here.)

You have many reasons why you might want to man-in-the-middle (MITM) app network traffic. More and more apps are replacing web traffic as the primary way for users to interact with service providers. Apps tend to be far less transparent than websites in the information they collect, and many have access to far more information than a website viewed on a laptop — things like the phone’s microphone, camera, accelerometer, contact list and so on.

As researcher Blake Netzeband put it, “Like prior gold rushes, online privacy has become a very political and nuanced issue; ergo, only a select few are fully aware of the scope and influence of today’s 49ers.” Inspecting app network traffic empowers you to “pan the gold flowing down the data streams of your computer, phone, thermostat, etc. using mitmproxy.”

There’s gold in them thar hills, or private data in that thar phone, at any rate, and there are lots of legitimate reasons to want to uncover who’s extracting data-gold from your phone.

Beyond examining mobile app traffic for both security and privacy issues, MITMing app network traffic using mitmproxy makes it easy to map out an app’s public mobile API. This makes it possible to directly interact with the API in perfectly legal ways that the app’s engineers may not have intended.

For instance, researcher Petr Pátek used mitmproxy to reverse engineer the Swiggy food order and delivery app, which is popular in India, to query the API for complete lists of restaurants.

Mitmproxy for IoT devices

You can also deploy mitmproxy on a Raspberry Pi to MITM all traffic on a Wi-Fi access point to inspect traffic on your home network — for example, to see what your IoT devices are up to. Pop the Pi in front of your router and pipe all network traffic through mitmproxy.  

Numerous walk-throughs on the intertoobs show how to do this, including this excellent 2019 blog post by Dino Fizzoti. (A web search for “mitmproxy raspberry pi” turns up many others. Which one works for you depends on the Pi you’re using, the version of mitmproxy, the devices on your network, etc.)

The relatively recent addition of on-board Wi-Fi to Raspberry Pis makes MITMing Wi-Fi traffic even easier than before, as an additional external Wi-Fi dongle is no longer required.

Automating mitmproxy

Since mitmproxy is distributed under an open-source license, developers can harness it to inspect traffic at scale, as video streaming service Hulu did in 2019. “Observing network calls in real time is helpful in debugging, but being able to intercept and modify any request or response allows developers to test a variety of network scenarios,” Hulu engineer Chandler Underwood wrote. “mitmproxy’s Python add-ons expose a Python API that allows developers to programmatically modify any network request/response that passes through the proxy.”

“Removing some of the barriers to thorough testing such as these allow our developers and QA engineers to focus on quality and deliver better features sooner,” Underwood wrote. Hulu has, in turn, open-sourced its test harness, which is available on GitHub.

Mitmproxy is currently the gold standard for inspecting TLS-encrypted app, web, and IoT device network traffic.