mitmproxy – an interactive HTTPS proxy
mitmproxy is your swiss-army knife for debugging, testing,
privacy measurements, and penetration testing.
It can be used to intercept, inspect, modify and replay web traffic such
HTTP/1, HTTP/2, WebSockets, or any other SSL/TLS-protected protocols.
You can prettify and decode a variety of message types ranging from HTML
intercept specific messages on-the-fly,
modify them before they reach their destination, and replay them
to a client or server later on.
Use mitmproxy’s main features in a graphical interface with
mitmweb. Do you like Chrome’s DevTools? mitmweb
you a similar experience for any other application or device,
plus additional features such as request interception and replay.
from mitmproxy import
def request(flow: TPFlow):
if etty_host == “”:
sponse = (
418, b”I’m a teapot”, )
Write powerful addons and script mitmproxy with mitmdump.
The scripting API offers full control over mitmproxy and makes it
to automatically modify messages, redirect traffic, visualize messages,
implement custom commands.
Mitmproxy powers a number of notable open-source projects:
pathod, mitmproxy’s sister project
malformed HTTP/1, HTTP/2 and WebSocket requests.
privacy analysis and measurement service.
tamper, a Chrome extension that
edit remote files locally.
bdfproxy, a BackDoorFactory
patch binaries with shell
code on the fly.
a project from ustwo that offers an
way to mock an API or a website
Mitmproxy is free and open source. Be part of the mitmproxy community
help improve your favorite HTTPS proxy.
SSL MITM Proxy
SSL MITM Proxy
mitm-proxy is an Java-based SSL proxy that acts as a “man in the middle”.
In other words, proxied HTTPS requests are terminated by the proxy and resent to the remote webserver.
The server certificates presented to the client (i. e. a web browser) are dynamically generated/signed
by the proxy and contain most of the same fields as the original webserver certificate. The subject DN,
serial number, validity dates, and extensions are preserved. However, the issuer DN is now set to the
name of the proxy’s self-signed certificate and the public/private keys of the proxy are used in creating
the forged certificate. These forged certificates are cached (in memory) by the proxy, for better performance.
The basis for this code was The Grinder
NOTE: this tool can NOT be used for any commercial purposes, as is, because it makes use of an educational/research version of the IAIK JCE library.
Version 1. 0 (April 12th, 2007)
The mitm-proxy requires a Java runtime (1. 5 or later) and has been
tested on various windows and linux platforms. For the impatient, the included README
file contains quick start instructions.
The proxy server is started from the command line in the following way:
java MProxyServer [options]
Where options can include:
[-v] Verbose proxy output
[-h] Print this message
Notes on the options:
keyStore is a Java KeyStore file containing a self-signed proxy certificate
A new self-signed proxy certificate can be created by invoking:
keytool -genkey -keystore
outputFile will contain the plaintext HTTP requests that are being proxied
Verbose proxy output includes:
Details about the proxied data connection’s endpoints
The remote webserver certificate’s common name field
The newly forged certificates
Once the proxy server is started, your web browser will need to be configured to make use of an SSL proxy,
with the same host/port as above. Note that unless the proxy’s certificate is imported into your browser
CA certificate store, you will see warnings about untrusted server certificates.
Originally developed for use in a class project for CS255:
Introduction to Cryptography, taught by
Prof. Boneh in Winter 2007.
Stanford Security Lab
How to Man in the Middle HTTPS Using mitmproxy – Earthly Blog
12 minute read
Updated: February 11, 2021
Have you ever wanted to see what kinds of requests a service or application on your machine is making and what kind of responses it is getting back? Have you ever tried and failed to capture this traffic or modify it to investigate how something works (or doesn’t work). If you have, then mitmproxy might be what you need. Being able to scan through and observe HTTP protocol traffic easily is a great debugging aid.
This guide will walk you through installing and using mitmproxy to capture HTTPS requests. We will start with macOS traffic capture, then touch on Linux and Windows and then finally show how to capture docker daemon traffic and docker container traffic.
What Is mitmproxy?
mitmproxy is a command-line tool that acts as a HTTP and HTTPS proxy and records all the traffic. You can easily see what requests are being made and even replay them. It’s great for diagnosing problems.
On Mac, mitmproxy is easy to install with brew:
brew install mitmproxy
On Windows and Linux, download the binary release and place it somewhere in your path.
#1 Start It Up
To start up mitmproxy, type mitmproxy, and it will start up bound to port 8080.
The command-line interface (CLI) has VIM-like keybindings. q will quit, and arrow keys or h, j, k, l will move you up and down through the request list.? will load the help, and <
Help Menu for mitmproxy
mitmproxy also has a web interface if you prefer the mouse over VIM keybindings. The advanced functionality is a bit more discoverable in the web interface, but the CLI version is convenient for quick capture sessions.
We will use both throughout the tutorial. Whichever you choose, start it up and leave it running.
#2 Proxy Our Connection
Let’s set up our internet connection to use this proxy. On macOS, Under Setting -> Network, choose your connection and select advanced.
Setting -> Network on macOS
Under proxies, enable both HTTP and HTTPS proxies and choose port 8080:
Setup Proxy under Setting -> Network-> Advanced on macOS
On Windows, follow these steps to set up a proxy.
On Linux, MITM supports a transparent proxying at the network layer.
Adding mitmproxy as A Certificate Authority
We now have our connection proxied to go through our instance of mitmproxy. However, if we attempt to make a HTTPS-based request in a web browser (loading for example), something interesting happens.
Chrome does not recognize the certificate
Chrome is warning us that we might be subject to a man in the middle attack.
What Is a Man in the Middle?
A man in middle attack (MITM) is a security threat where an attacker can get between incoming and outgoing requests. You think you are talking to, but you are talking to the man in the middle, who is talking to Twitter for you. This MITM can view everything you send and even change what you receive.
The HTTPS protocol prevents MITM attacks. The HTTPS protocol is pretty complex, but all we need to know is that HTTPS uses a trusted Certificate Authority (CA) to sign a certificate. Our browsers assume that if a trusted CA signs the certificate, we are talking directly to who we think we are.
You can view what CA signed the certificate of the website you are viewing in your browser.
Viewing a certificate in your browser
This is great for protecting online communication but problematic for our debugging purposes. We are trying to man in the middle our own requests. To help overcome this, mitmproxy has generated a certificate. All we need is to get our machine to trust it.
Getting a Certificate signed by an unknown certificate authority
How to add a Trusted Certificate Authority Certificate
mitmproxy generated a certificate and private key the first time you ran it. The certificate generated is specific to your machine and is located in ~/. mitmproxy/
> cat ~/. mitmproxy/
—–BEGIN PRIVATE KEY—–
—–END PRIVATE KEY—–
Note: Once we instruct our machine to trust this certificate, someone with the private key who controlled your internet connection, like your ISP, could use it to MITM your connection. For this reason, don’t share your MITM private key, or any private key, with others.
Add the Cert on MacOS
On macOS, the easiest way to add a new CA is to copy it to the desktop and then double-click it.
cp ~/. mitmproxy/ ~/Desktop
You will be prompted for your credentials, and the certificate will be added as untrusted.
Double-click on the certificate in the Keychain list and set the ‘Secure Sockets Layer’ drop down to ‘Always Trust’
You will then be prompted for your password again, and then your certificate will be trusted.
Installing the Trusted Root Certificate On Windows
If you are on Windows, follow this guide to add the MITM root certificate as a trusted root certificate authority.
Installing The Cert on Debian Based Linux Distributions
On Debian-based Linux distributions, follow these steps:
> mkdir /usr/local/share/ca-certificates/extra
> cp ~/. mitmproxy/ /usr/local/share/ca-certificates/extra/
We will be using these steps later when we work with docker containers on macOS and Windows.
At this point, assuming you still have mitmproxy running and you still have your network interface setup to proxy through localhost:8080, you should be able to view all the HTTP and HTTPS network requests your machine is making in the mitmproxy (or mitmweb) window.
Here is Slack making requests:
mitmweb has captured a request from the slack application
All HTTPS connections now have certificates signed by mitmproxy, which your machine trusts.
now shows a mitmproxy signed certificate
MITM the Docker Linux Container Host on macOS & Windows
Docker containers run differently on macOS and Windows
At this point, we can successfully capture traffic on our host operating system. Unfortunately, this is insufficient for capturing docker container traffic on macOS and Windows. So let’s move on to proxying traffic on the Linux Container Host.
On macOS and Windows, Linux containers do not run on the host OS. They can’t because they need a Linux host to run. Instead, they run on the Linux Container Host, a VM that Docker Desktop manages.
To see the docker daemon’s incoming and outgoing requests, we need to get our proxy settings and our certificate authority into that VM.
Before we proceed, we need to clear the proxy settings on the host network connection. We can leave mitmproxy (or mitmweb running).
On Windows and macOS, the easiest way to configure a proxy is via Docker Desktop. Configure the proxy settings under Preferences -> Resources -> Proxies.
Configure the proxy settings under Preferences -> Resources -> Proxies.
With that done, the network interface will be proxied. All that is left to do is get our certificate trusted by the Linux container host. Thankfully, Docker Desktop takes care of this for us. On startup, Docker Desktop loads the trusted root certificates from the host machine into the Docker VM, so all we need to do is restart docker. (Restart Docker in Docker Desktop).
Docker MITM on Linux
On Linux, we can add a proxy by editing the docker client config and then restarting.
> cat ~/
> sudo service docker restart
After restarting, we can test the proxying by performing a docker pull for a random image
➜ ~ docker pull couchbase:7. 0. 0-beta
7. 0-beta: Pulling from library/couchbase
83ee3a23efb7: Pull complete
db98fc6f11f0: Pull complete
f611acd52c6c: Pull complete
3aa2029a80db: Pull complete
abe30feace46: Pull complete
9b70018fbd54: Pull complete
d9b67d157052: Pull complete
212afe5e3a9c: Pull complete
ff5e5d4b4f9c: Pull complete
4df60b92878a: Pull complete
eee5137af1d8: Pull complete
c4ef83141448: Pull complete
6a04071b6d8c: Pull complete
f52d17d818b3: Pull complete
Status: Downloaded newer image for couchbase:7. 0-beta
We can then see the requests and responses in our proxy:
We can even see the binary payload of the layer requests and the fact that docker uses Cloudflare as a CDN.
mitmweb request for
If docker pull fails with a certificate error or the requests don’t get proxied, make sure you have restarted docker at least once and that the proxy settings are in place.
Capturing Docker Container Traffic
We now know how to capture traffic on our host machine and the Linux container host. But what happens when we make requests from inside a running container?
> docker run -it ubuntu
[email protected]:/# apt upgrade & apt update & apt install curl…
[email protected]:/# curl
The document has moved
Any requests by anything running inside the container will be transparently proxied. If you are trying to debug what a service you depend on is doing this will come in handy.
Extending an Ubuntu Image to Add a Certificate Authority
A similar process will work with Ubuntu-based images:
RUN apt update -y && apt upgrade -y && apt install ca-certificates curl -y
> docker build –tag ubuntu:mitm.
[+] Building 36. 4s (10/10) FINISHED
=> => transferring dockerfile: 234B 0. 0s
=> => transferring context: 35B 0. 0s
=> [2/5] RUN apt update -y && apt upgrade -y && apt in 35. 0s
=> [5/5] RUN update-ca-certificates 0. 9s
=> exporting to image 0. 4s
=> => exporting layers 0. 3s
=> => writing image sha256:06fbbeea728364e3bacef503f7c2 0. 0s
> docker run -it ubuntu:mitm
But Wait, There’s More
There we go. We can now capture HTTPS traffic made by any containers we run. Combined with the previous steps, we can now intercept and inspect HTTP and HTTPS protocol traffic on our host machine, on a Linux virtual machine running in a hypervisor, and in the actual running containers.
If you can get something running on your local machine, you can now capture and inspect its network requests. This can be very handy for debugging problems and building up an understanding of how something works without digging into the source code. The setup can be a bit complicated, but I hope you can see why mitmproxy is a great tool to keep in your toolkit.
The fun doesn’t stop here, though. mitmproxy can modify and replay requests and has an active ecosystem, including mastermind which lets you build mock services based on captured requests and BDFProxy, which uses mitmproxy to modify common security updates for nefarious reasons security research projects, and much more.
While you’re here:
Earthly is a syntax for defining your build. It works with your existing build system. Get repeatable and understandable builds today.
Frequently Asked Questions about ssl mitm proxy
What is MITM proxy server?
mitm-proxy is an Java-based SSL proxy that acts as a “man in the middle”. In other words, proxied HTTPS requests are terminated by the proxy and resent to the remote webserver.
How do I setup a MITM proxy?
We can leave mitmproxy (or mitmweb running). On Windows and macOS, the easiest way to configure a proxy is via Docker Desktop. Configure the proxy settings under Preferences -> Resources -> Proxies. Configure the proxy settings under Preferences -> Resources -> Proxies.Feb 11, 2021
What is SSL in proxy?
Secure Sockets Layer (SSL) is an application-level protocol that provides encryption technology for the Internet. … SSL relies on certificates and private-public key exchange pairs for this level of security. SSL proxy is transparent proxy that performs SSL encryption and decryption between the client and the server.