mitmdump

Start a proxy and save all output to a file

$ mitmdump [[-w|--wfile]] [path/to/file]

$ mitmdump [[-nr|--no-server --read-flows]] [input_filename] [[-w|--wfile]] [output_filename] "[~m post]"

$ mitmdump [[-nc|--no-server --client-replay]] [path/to/file]

$ sudo mitmdump [[-m|--mode]] dns

mitmdump [options] [filters]
Examples:
mitmdump -p 8080 -s my_script.py
mitmdump --mode transparent "~h example.com"

-p , --port
    The port on which the proxy will listen for incoming connections. Default is 8080.

-q, --quiet
    Suppress most output to stdout, showing only essential errors or script prints.

-s , --scripts
    Load a Python script at startup. Multiple scripts can be loaded by specifying the option multiple times or using a comma-separated list.

-r , --read-file
    Read flows from a specified file instead of capturing live traffic. Useful for analysis or replaying past sessions.

-w , --write-file
    Write all captured flows to the specified file. This allows for later inspection or replay using mitmproxy, mitmweb, or mitmdump.

--set =
    Set a configuration option directly. E.g., --set connection_timeout=60.

--mode
    Specify the proxy mode: regular (default), transparent, reverse:, or socks5.

--ssl-insecure
    Do not verify upstream SSL/TLS certificates. Use with caution as it bypasses security checks.

--listen-host
    The host interface for the proxy to listen on. Default is 127.0.0.1 (localhost).

--confdir
    Specify a directory where mitmproxy stores certificates and other configuration files.


    Positional arguments can be used as filters to only display or process flows matching specific criteria (e.g., ~h example.com for host matching).

mitmdump is the command-line interface of the mitmproxy suite, a powerful open-source tool for interactive
inspection, modification, and replay of HTTP/S traffic. Unlike its interactive console counterpart
mitmproxy or the web-based
mitmweb,
mitmdump is designed for non-interactive use, making it ideal for scripting, automation, and continuous integration environments. It allows developers and security professionals to intercept and analyze network requests and responses, injecting custom Python scripts to modify headers, bodies, or even inject new flows. This functionality is crucial for security testing, API debugging, performance analysis, and bypassing specific network restrictions.
mitmdump supports SSL/TLS interception by dynamically generating certificates, providing deep visibility into encrypted traffic, provided its CA certificate is trusted by the client.

SSL/TLS Interception Requires Trust: For mitmdump to successfully intercept HTTPS traffic, its generated CA certificate must be trusted by the client's operating system or application. Failure to do so will result in certificate errors.
Performance Overhead: Intercepting and processing all network traffic can introduce a performance overhead, especially for high-volume environments or large data transfers.
Ethical Use: As a man-in-the-middle tool, mitmdump can be used for malicious purposes. Always ensure you have appropriate authorization before intercepting network traffic.

One of mitmdump's most powerful features is its extensive Python API, allowing users to write custom scripts
that interact with the intercepted traffic. Scripts can modify requests, responses, add
or remove headers, inject content, or even trigger external actions based on traffic
patterns. This enables highly flexible and automated testing, data extraction, and
security analysis workflows.

To intercept HTTPS traffic, mitmdump acts as an SSL/TLS man-in-the-middle. It generates dynamic
certificates for each intercepted domain. For clients to trust these certificates, the
mitmproxy CA certificate must be installed and trusted on the client machine. This is a
critical step for successful HTTPS interception and debugging.

mitmdump is an integral part of the broader mitmproxy project, which originated as an open-source initiative
developed in Python. Initially conceived as a command-line utility for debugging and testing, it has
steadily evolved, gaining advanced features like HTTP/2 support, WebSockets, and a robust
scripting API. Its design emphasizes automation and integration, making it a cornerstone for
developers and security researchers needing non-interactive traffic manipulation capabilities
within scripts or automated workflows. The project continues to be actively maintained and
developed by a community of contributors.

mitmproxy(8), mitmweb(8), curl(1), wget(1), tcpdump(8), wireshark(1)