mitmproxy – an interactive HTTPS proxy

Command Line
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
as
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
to
Protobuf,
intercept specific messages on-the-fly,
modify them before they reach their destination, and replay them
to a client or server later on.
Web Interface
Use mitmproxy’s main features in a graphical interface with
mitmweb. Do you like Chrome’s DevTools? mitmweb
gives
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 == “”:
= “”
elif (“/brew”):
sponse = (
418, b”I’m a teapot”, )
Python API
Write powerful addons and script mitmproxy with mitmdump.
The scripting API offers full control over mitmproxy and makes it
possible
to automatically modify messages, redirect traffic, visualize messages,
or
implement custom commands.
Powerful Ecosystem
Mitmproxy powers a number of notable open-source projects:
pathod, mitmproxy’s sister project
craft
malformed HTTP/1, HTTP/2 and WebSocket requests.
netograph,
a
privacy analysis and measurement service.
tamper, a Chrome extension that
lets
you
edit remote files locally.
bdfproxy, a BackDoorFactory
integration
patch binaries with shell
code on the fly.
mastermind,
a project from ustwo that offers an
easy
way to mock an API or a website
Open Source
Mitmproxy is free and open source. Be part of the mitmproxy community
and
help improve your favorite HTTPS proxy.

SSL MITM Proxy

SSL MITM Proxy
Description
Documents
Download
Usage
Credits
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.
PowerPoint presentation
The basis for this code was The Grinder
tcpsniffer project.
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:
[-localHost ] Default is localhost
[-localPort ] Default is 8001
[-keyStore ] Key store details for
[-keyStorePassword ] certificates. Equivalent to
[-keyStoreType ] properties
[-keyStoreAlias ] Default is keytool default of ‘mykey’
[-outputFile ] Default is stdout
[-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 -storepass -keyalg rsa
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.
Staff:
Dan Boneh
Srinivas Inguva
Ian Baker
Background:
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
Introduction
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.
Installing It
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.
>mitmproxy
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 <> will drill in on a specific request.
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 CERTIFICATE—–
MIIC1TCCAb2gAwIBAgIJAOY7y/7Qrqr3MA0GCSqGSIb3DQEBBQUAMBoxGDAWBgNV
BAMTD3d3dy5leGFtcGxlLmNvbTAeFw0yMTAxMjYxNTQyMjhaFw0zMTAxMjQxNTQy
MjhaMBoxGDAWBgNVBAMTD3d3dy5leGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEB
BQADggEPADCCAQoCggEBAMLImmAMUg1zz6GnpoOA7Ln9p53o7v1M4+1O6lYmGtAK
4zetlcMF3mjtNr+AszBFYBpkhd1ef7rDSOc5YxCQ52SZlJc2l2vVtkn5bL1Xa2/W
AdzQcNq2meX6Pdm+YBC7KsmM8+uo8pXy3+gj7avWLXQ3BG+WaWRnRtgVoke53a0s
H+KFwR077XkrIYpOccsrX6+bMrjcnKkEbxb6Q8wdk664c+yf9F+WBC4zcnU43va/
Vl9ETGVOofab6YMk7CICFWEYj/1OJFIMNcEwWpm1eBDXvzt13d1xkiRTDYq+aRKb
utuFiYo7pngGjSEttQKl1nVUcDgkFhPE7Kz3mTBn2T8CAwEAAaMeMBwwGgYDVR0R
BBMwEYIPd3d3LmV4YW1wbGUuY29tMA0GCSqGSIb3DQEBBQUAA4IBAQAxT8EIJUAN
i842v+CoAOnRTO2jDtjIsxgg6WYlpHu1VL+Mh/ye4hfPz6DyyemM4Df64tEc7Mw8
KlhNqXfomY2trZHuxfeyMjg9GItmYaoeV+xg5SDYjGmgE2n8nc5FH5TlhimE9gd1
48NNMFRPXm2cYRz3T4i0HqesBrAmdpWBOQmCqzqF5SR08xqlS8X9ELzkRGTRDiJ5
4j5m1uI0rHyzSVlBK1DKy1LdkGNtes/OuTSZsnQ6PqZBzIZDhbzS0pz7GP9IqHkK
K2k43zCas8fHIU5o+0XoFQ7JoA+1AV3S9LYVD2rHfeOMMY/VzTP+b67/KY7H/Wl+
QyVJfmCmjt2i
—–END CERTIFICATE—–
cat
—–BEGIN PRIVATE KEY—–
QyVJfmCmjt2i=
—–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/
> update-ca-certificates
We will be using these steps later when we work with docker containers on macOS and Windows.
Great Success
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 ~/
{
“proxies”:
“default”:
“Proxy”: “,
“Proxy”: “}}}
> sudo service docker restart
Test It
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
Digest: sha256:290a7a0623b62e02438e6f0cd03adf116ac465f70fc4254a4059bcf51e8fa040
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
Troubleshooting
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
root@ca43de1bb8b1:/# apt upgrade & apt update & apt install curl…
root@167f5742c295:/# curl

301 Moved