Install mitmproxy

What mitmproxy is

A program that places itself between your computer and the internet and shows you every request that goes back and forth. You see which address is called, what is sent along, and what the server responds. None of that is visible otherwise.

That sounds narrow, and it is not. If you build an app or a site that talks to a payment system, a shipping company or an API you did not write yourself, the most common question is why it does not work. mitmproxy answers that question by showing what was actually sent, instead of what you thought you sent.

The name means man in the middle. That is exactly what the program does, and that is also why there are rules around it. More about them further down.

Windows

Download the installer from mitmproxy.org and run it. It is also available in the Microsoft Store if you prefer that route. Neither option costs anything.

Then open PowerShell. You do that by pressing the Windows key, typing PowerShell and pressing Enter. Type:

mitmweb

A browser window opens with the interface, and the proxy listens on port 8080 on your own computer.

Linux Mint

Download the ready-made Linux file from the same page. It comes as an archive you unpack, and inside it are three programs that run directly without installation. Open Terminal, go to the folder where you unpacked the files, and run:

./mitmweb

The package in Mint's own software catalog is also available, but it is often several versions behind. The downloaded file is newer and just as easy.

Three programs are included, and the only difference between them is how you look at the traffic. mitmweb shows it in the browser and is the one you should start with. mitmproxy shows the same thing in a terminal window. mitmdump shows nothing and instead writes to a file, which is useful when you want to save a session and look at it later.

Four things to do first

1. Set up the proxy, otherwise no traffic goes through mitmproxy and the list stays empty. On Windows, the setting is under Settings, Network and Internet and Proxy: turn on manual proxy, address 127.0.0.1, port 8080. On Linux Mint, it is under Settings and Network, in the network proxy: choose manual and enter the same address and port for both HTTP and HTTPS. If you want to capture a phone, you set the computer's IP address as the proxy in the phone's wifi settings instead.
2. Install the certificate right after. Browse to http://mitm.it with the proxy turned on and follow the instructions for your platform. Without that step, no HTTPS page works at all, and almost everything is HTTPS today.
3. Capture your own page first, not someone else's. Reload your own project with mitmweb running and click around in the list. You see right away how many requests a single page load involves, and that is more useful than it sounds.
4. Try the filter box. Type ~u api to show only requests whose address contains the word api. The list becomes impossibly long otherwise, and that is where most people give up.

The most common trap

Closing mitmproxy and leaving the proxy setting in place. The computer keeps sending all traffic to port 8080, where nothing is listening anymore, and the result is that the internet seems to be down. The browser only says it cannot connect, and nothing points to the proxy.

Get used to turning off the proxy in the same motion as you close the program. The same setting you turned on, back to off.

The other half is the certificate. When you install the mitmproxy certificate, you tell the computer to trust that certificate for all encrypted traffic. That is the whole point while you troubleshoot, and it is also a door that stands open as long as the certificate remains, because anyone who gets hold of the key can read your traffic without the browser warning.

So remove it when you are done. On Windows, open the certificate manager by pressing Windows and R, typing certmgr.msc and pressing Enter. The certificate is called mitmproxy and is under Trusted Root Certification Authorities and Certificates. Right-click and choose delete.

On Linux Mint, the original is in ~/.mitmproxy/ and the copy you added to the system is in /usr/local/share/ca-certificates/. Remove the copy and update the list:

sudo rm /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt
sudo update-ca-certificates --fresh

If you added the certificate to the browser, it should be removed there too. In Firefox it is under the settings, in the certificates section.

The other half of the same trap is legal. Looking at traffic from your own devices and your own services is no problem. Tapping into someone else's traffic is not, no matter how easy the program makes it. Stick to your own things, and this is a troubleshooting tool and nothing else.