When you need to inspect HTTP(S) traffic for development, debugging, or security testing on systems you own or have explicit permission to test, mitmproxy is a practical tool. This guide walks through configuring mitmproxy in a controlled environment: installing the software, making clients trust the proxy for https, capturing and analyzing traffic, and returning systems to a safe state when you’re done. Read and follow the legal and ethical notes before proceeding.
Important legal and safety notes
Intercepting network traffic without informed consent is illegal and unethical. Use mitmproxy only on devices and networks you control or where you have written permission. Never use these techniques to access someone else’s data, bypass protections, or interfere with production systems. Keep your test data isolated, and remove certificates and proxy settings after testing.
Prerequisites
Before you begin, ensure you have a machine with a recent operating system and internet access to download packages. You’ll need administrative privileges to install software and (for some advanced modes) to change firewall rules or network settings. Have the target device on the same local network, or configure routing so the device can reach the host running mitmproxy.
Step 1 , Install mitmproxy
mitmproxy runs on linux, macOS, and Windows. Choose the installation method that suits your platform. On macOS, Homebrew is convenient; on many Linux distributions you can use pip or your package manager; on Windows, download the official installer or use pip in a virtual environment. For example, a common cross-platform command is:
- pip install mitmproxy
After installation you should have access to the main binaries: mitmproxy (console UI), mitmweb (web UI), and mitmdump (non-interactive tool for scripts and recording).
Step 2 , Start mitmproxy and basic configuration
Launch mitmproxy in the simplest setup to verify everything works. On the host machine run one of these, depending on preference:
- mitmproxy –listen-port 8080 (interactive console)
- mitmweb –listen-port 8080 (access via browser at
- mitmdump -w saved.flows (capture to a file for later analysis)
By default mitmproxy listens on all interfaces; you can restrict this with –listen-host or bind to a specific address. Note the port (commonly 8080) because the client device will be configured to use the host’s IP and that port as its HTTP/HTTPS proxy.
Step 3 , Install and trust the mitmproxy root certificate on clients
Inspecting HTTPS requires the client to trust mitmproxy’s certificate authority so the proxy can perform tls termination and re-encryption. mitmproxy generates its CA certificate automatically on first run and serves a convenience page at when visited through the proxy. On a client you control, point the browser to that address after configuring the proxy and download the certificate.
For different platforms the steps vary slightly:
- Windows/macOS: Download the certificate from mitm.it or copy ~/.mitmproxy/mitmproxy-ca-cert.pem to the client and import it into the system keychain/certificate store, marking it as trusted for TLS.
- Android: Newer Android versions treat user certificates differently; you can install the CA in Settings → Security → Install from storage, but note system apps may ignore user CAs unless the app or device is configured to allow them. On emulators or rooted devices you have more options.
- iOS: Visit mitm.it from Safari after configuring the proxy, download and install the profile, then explicitly trust the installed certificate in Settings → About → Certificate Trust Settings.
Always follow platform guidance for removing or disabling the CA after testing. Leaving a test CA trusted on production devices is a security risk.
Step 4 , Configure the client to use the proxy
You can configure a client device to use mitmproxy as an explicit HTTP/HTTPS proxy by setting the proxy host to the ip address of the machine running mitmproxy and the port you started it on (for example 192.168.1.100:8080). On desktops this is usually in network settings or the browser’s proxy configuration. On mobile devices, configure the Wi‑Fi network’s proxy settings. For automated environments or transparent interception, mitmproxy supports transparent proxy mode, but that requires routing or firewall rules, and administrative access on the host and gateway.
Step 5 , Capture and analyze traffic
Once the client is using the proxy and trusts the CA, traffic will appear in mitmproxy. Use the console interface to inspect requests and responses, modify live traffic, or replay requests. mitmweb provides a browser-based interface that is often easier for visual inspection. Common features to use:
- Filter flows by host, path, or status code to narrow your view.
- View full request and response bodies and headers, and follow redirects.
- Use mitmdump with scripts to automate transformations or extract specific data.
- Save sessions with -w to record flows and load them later with -r for offline analysis.
Keep the capture scoped to the test systems you control. If you run automated tests, incorporate flow recording into the test pipeline and scrub sensitive production data before storing logs.
Step 6 , Advanced options and scripting
mitmproxy supports scripting in Python for automated manipulation, filtering, or custom logging. Launch mitmdump with –script myscript.py to apply logic to each flow. You can also configure upstream proxies, upstream authentication, and certificate behavior through options and a configuration file. For intercepting traffic transparently at a network edge, use the transparent mode and configure the host’s firewall (for example iptables on Linux) to redirect port 80/443 to the mitmproxy listening port; these changes should be made only in a lab and require careful cleanup.
Step 7 , Clean up
When testing is complete, stop mitmproxy and remove any CA certificates you installed on client devices. Reset proxy settings on clients to their original configuration. If you modified firewall or routing rules for transparent proxying, revert them immediately. Document your changes and ensure no test certificates remain trusted in production environments.
Troubleshooting tips
If HTTPS traffic is not visible, confirm the client is pointing to the correct host and port and that mitmproxy is listening on an interface reachable from the client. Verify the CA certificate is installed and trusted by the client; check browser or OS warnings for certificate errors which often indicate trust issues. For mobile apps that implement certificate pinning, you may need to use a debug build that disables pinning or test on a device configured to allow user CAs. Consult mitmproxy’s logs and the verbose output option for clues when things don’t behave as expected.
Summary
mitmproxy is a flexible tool for inspecting and modifying HTTP(S) traffic in controlled environments. To use it responsibly: install the tool, start it on a reachable host, make the client trust the mitmproxy CA, configure the client’s proxy settings, capture and analyze flows, and then clean up by removing certificates and restoring network settings. Always obtain permission, limit testing to systems you control, and remove any test certificates once work is complete.
FAQs
Is it legal to use mitmproxy on my network?
Using mitmproxy on networks and devices you own or where you have explicit permission is legal. Intercepting traffic without authorization is typically illegal and may violate privacy laws and terms of service. Always obtain clear consent and operate within applicable laws and policies.
Why does an app still fail to connect after installing the CA?
Many apps implement certificate pinning or use platform APIs that ignore user-installed CAs, especially on modern mobile operating systems. In such cases you need a debug build that disables pinning, use a rooted or emulated device configured to accept the test CA, or instrument the app in a manner consistent with its license and your testing authorization.
How can I save captured traffic for later analysis?
Use mitmdump -w filename to write flows to a file. You can later load that capture with mitmproxy -r filename or mitmweb -r filename to review the recorded requests and responses offline.
What should I do if I accidentally leave the test CA trusted on a device?
Remove the CA from the device’s certificate store as soon as possible and revoke any test credentials you used. For corporate devices, follow your organization’s incident or device remediation process to ensure no lingering risks remain.
