mitmproxy

mitmproxy is a proxy that sits between your browser or app and a web server and shows each HTTP exchange one by one. Once a client trusts mitmproxy’s certificate, you can read HTTPS traffic too. The safest way to start is to leave your system settings alone and send a single curl request through mitmproxy.

This review is for developers who want to check what their own web or mobile app sends, and for people starting to learn how the web works. After reading it, you can do the following:

• Run mitmproxy so that it listens only inside your own computer, and watch traffic in its web interface
• Read a single HTTPS request without changing the certificate store of your OS or browser
• Understand what happens if the certificate’s private key leaks, and clean up when you are done

##What mitmproxy does

mitmproxy ships three tools with different interfaces.

• Records and inspects traffic: Open each request and response and read its headers and body. It supports HTTP/1, HTTP/2, and WebSockets.
• Modifies and replays: Edit a recorded request and send it again. It can also replay a saved conversation as a whole.
• Replaces and blocks: map_local answers requests for a URL with a local file, and block_list stops requests to specific sites.
• Automates with Python: Load a Python script called an addon with -s to run code on every request.
• Switches how it captures: For apps that ignore proxy settings, local mode captures traffic from apps on the same computer, and WireGuard mode connects other devices such as phones.

##Network traffic

• According to the official installation guide, mitmproxy does not “phone home” and does not check for updates.
• Requests you send through it reach their real destination servers. Modified and replayed requests also reach those servers. That is why this review rates its impact as “medium.”
• The listen address is empty by default, so mitmproxy listens on every network interface of your computer. It blocks connections from public IP addresses by default (block_global), but devices on the same LAN can connect.
• The web interface (mitmweb) opens on 127.0.0.1:8081 by default and is protected by a random token generated at each startup.

##Try it safely with a single curl request

If you install the certificate in your OS or browser, mitmproxy can read every HTTPS connection from that computer. Skip that at first and pass the certificate straight to curl instead. Step 4 assumes a macOS or Linux terminal.

1. Download the installer or binaries for your OS from the official site. On macOS you can also use Homebrew: brew install --cask mitmproxy.

2. Start it in a terminal as shown below. This limits the listener to your own computer, so devices on the same LAN cannot connect.

   mitmweb --set listen_host=127.0.0.1

   A browser opens with the mitmweb interface. On first start, mitmproxy creates its certificate and key in the .mitmproxy folder in your home directory.

3. In another terminal, send one unencrypted HTTP request through mitmproxy.

   curl --proxy 127.0.0.1:8080 http://example.com/

   A new row appears in mitmweb. Select it to read the request and the response.

4. Now try HTTPS. Pass mitmproxy’s certificate to this one curl command only.

   curl --proxy 127.0.0.1:8080 --cacert ~/.mitmproxy/mitmproxy-ca-cert.pem https://example.com/

   The HTTPS request also appears in the list, decrypted. Your OS certificate store has not changed.

5. When you are done, press Ctrl+C in the terminal running mitmweb to stop it.

To watch all of a browser’s traffic, set the browser’s proxy to 127.0.0.1:8080 and open http://mitm.it. mitmproxy serves a page there that installs its certificate. Use a separate browser or profile from the one you use every day, and install the certificate only there to limit the impact.

##Common uses

Local mode works on Windows, macOS, and Linux. According to the official docs, on Linux it starts a privileged process with sudo and targets Linux 6.8 and later. It does not work under WSL.

An addon can be a single function. The official example adds one header to every request:

def request(flow):
    flow.request.headers["myheader"] = "value"

Save it as add_header.py and load it with mitmdump -s add_header.py.

##How it differs from ZAP and Wireshark

If you only want to check what your own app sends, mitmproxy is the better fit. To look below HTTP, for example at DNS or TCP, use Wireshark.

##Cautions

##Read next

• ZAPalso works as a proxy, and can scan for vulnerabilities automaticallycd ../zap
• Wiresharklooks at traffic packet by packetcd ../wireshark
• MobSFchecks your own mobile appscd ../mobsf
• How to set up a safe test labcat ~/guides/lab-setup.md