mitmproxy

https://docs.mitmproxy.org/stable
Admin
mitmproxy is an interactive, SSL/TLS-capable intercepting proxy for HTTP/1, HTTP/2, and WebSockets...
Tokens:194,990
Snippets:1,562
Trust Score:9.6
Update:11 hours ago
Show doc for...
Tokens:
Raw
### Install mitmproxy from PyPI using uv

Source: https://docs.mitmproxy.org/stable/overview/installation/

Recommended method to install mitmproxy from PyPI. Requires uv to be installed first.

```bash
uv tool install mitmproxy
```

--------------------------------

### Start AVD with -writable-system

Source: https://docs.mitmproxy.org/stable/howto/install-system-trusted-ca-android/

Starts the desired AVD with the -writable-system option to allow system partition modifications. Add -show-kernel for kernel logs.

```bash
emulator -avd <avd_name_here> -writable-system
```

--------------------------------

### Custom key bindings example

Source: https://docs.mitmproxy.org/stable/concepts/commands/

Example keys.yaml file with two bindings: a global binding for ctrl a and a flowlist-specific binding for key '1'.

```yaml
-
  # Simple global binding
  key: ctrl a
  cmd: replay.client @marked
-
  # Bind key only in the flowlist
  # Note that 1 is quoted, or YAML interprets it as a digit
  key: "1"
  ctx: ["flowlist"]
  cmd: console.nav.down
  help: Go to next flow
```

--------------------------------

### map_local example: mapping with flow filter for GET requests

Source: https://docs.mitmproxy.org/stable/overview/features/

Example pattern that replaces `example.com/static/foo/bar.css` with `~/static/foo/bar.css` but only for GET requests, using the flow filter `~m GET`.

```plaintext
|~m GET|example.com/static|~/static
```

--------------------------------

### map_local example: mapping example.com/static/foo

Source: https://docs.mitmproxy.org/stable/overview/features/

Example pattern that replaces `example.com/static/foo/bar.css` with `~/static/bar.css`.

```plaintext
|example.com/static/foo|~/static
```

--------------------------------

### map_local example: mapping example.com/static directory

Source: https://docs.mitmproxy.org/stable/overview/features/

Example pattern that replaces `example.com/static/foo/bar.css` with `~/static/foo/bar.css`.

```plaintext
|example.com/static|~/static
```

--------------------------------

### map_local example: mapping example.com/main.js

Source: https://docs.mitmproxy.org/stable/overview/features/

Example pattern that replaces `example.com/main.js` with `~/main-local.js`.

```plaintext
|example.com/main.js|~/main-local.js
```

--------------------------------

### Install mitmproxy on macOS with Homebrew

Source: https://docs.mitmproxy.org/stable/overview/installation/

Recommended installation method for macOS using Homebrew. Installs the mitmproxy cask.

```bash
brew install --cask mitmproxy
```

--------------------------------

### Configure RemoteAccess service to start on demand

Source: https://docs.mitmproxy.org/stable/howto/transparent/

Sets the RemoteAccess service to start manually. Replace 'demand' with 'auto' to start on boot.

```batch
sc config RemoteAccess start= demand
```

--------------------------------

### Re-route GET requests from example.org to mitmproxy.org

Source: https://docs.mitmproxy.org/stable/overview/features/

Example map_remote pattern using a flow filter '~m GET' to match GET requests and replace '//example.org/' with '//mitmproxy.org/'.

```text
|~m GET|//example.org/|//mitmproxy.org/
```

--------------------------------

### Install mitmproxy with additional Python packages using uv

Source: https://docs.mitmproxy.org/stable/overview/installation/

Installs mitmproxy along with additional Python packages using uv's --with option.

```bash
uv tool install --with <your-package-name> mitmproxy
```

--------------------------------

### Create mitmproxy user and install mitmproxy

Source: https://docs.mitmproxy.org/stable/howto/transparent/

Creates a dedicated user 'mitmproxyuser' and installs mitmproxy for that user. This is part of the workaround for redirecting traffic originating from the machine itself.

```bash
sudo useradd --create-home mitmproxyuser
sudo -u mitmproxyuser -H bash -c 'cd ~ && pip install --user mitmproxy'
```

--------------------------------

### Install dnsmasq

Source: https://docs.mitmproxy.org/stable/howto/transparent-vms/

Installs the dnsmasq package, which provides DHCP and DNS services for the internal network.

```bash
sudo apt-get install dnsmasq
```

--------------------------------

### Start RemoteAccess service

Source: https://docs.mitmproxy.org/stable/howto/transparent/

Starts the RemoteAccess service, enabling IP routing on Windows.

```batch
sc start RemoteAccess
```

--------------------------------

### Start mitmweb in WireGuard mode

Source: https://docs.mitmproxy.org/stable/concepts/modes/

Starts mitmproxy's web interface in WireGuard mode, which runs a WireGuard VPN server in userspace without requiring administrative privileges.

```bash
mitmweb --mode wireguard
```

--------------------------------

### ProxyMode.parse examples

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/proxy/mode_specs.html

Examples of parsing proxy mode specifications using ProxyMode.parse and RegularMode.parse. The first example shows a successful parse with a listen port, the second shows a ValueError for an invalid port, and the third shows that RegularMode.parse rejects a different mode.

```python
mode = ProxyMode.parse("regular@1234")
assert mode.listen_port == 1234
assert isinstance(mode, RegularMode)

ProxyMode.parse("reverse:example.com@invalid-port")  # ValueError

RegularMode.parse("regular")  # ok
RegularMode.parse("socks5")  # ValueError
```

--------------------------------

### Run a mitmdump script

Source: https://docs.mitmproxy.org/stable/

Runs the add_header.py example script, which adds a new header to all responses.

```bash
mitmdump -s examples/simple/add_header.py
```

--------------------------------

### Start mitmproxy with the addon

Source: https://docs.mitmproxy.org/stable/addons/commands/

Loads the addon into mitmproxy so the command is available. Run this before sending traffic to have flows to work with.

```bash
> mitmproxy -s ./examples/addons/commands-flows.py
```

--------------------------------

### Run the addon in mitmproxy console

Source: https://docs.mitmproxy.org/stable/addons/options/

Starts mitmproxy console with the options-simple.py addon loaded. This is the first step to test the addon.

```bash
> mitmproxy -s ./examples/addons/options-simple.py
```

--------------------------------

### Message.http_version

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/http.html

Gets or sets the HTTP version string, for example 'HTTP/1.1'. The getter returns a string, and the setter accepts a string or bytes.

```APIDOC
## Message.http_version

### Description
HTTP version string, for example `HTTP/1.1`. This property can be read and set.

### Type
`str` (getter), `str | bytes` (setter)

### Getter
Returns the HTTP version as a string.

### Setter
Accepts a string or bytes and sets the HTTP version.
```

--------------------------------

### Request.path

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/http.html

Gets the HTTP request path, including query string. Usually starts with a slash, except for OPTIONS requests which may be just "*".

```APIDOC
## Request.path

### Description
HTTP request path, e.g. "/index.html" or "/index.html?a=b". Usually starts with a slash, except for OPTIONS requests, which may just be "*". This attribute includes both path and query parts of the target URI (see Sections 3.3 and 3.4 of RFC3986).

### Property
`path` (str)

### Access
Read-only
```

--------------------------------

### Replace foo with file content using mitmdump

Source: https://docs.mitmproxy.org/stable/overview/features/

Example command using mitmdump with the --modify-body option to replace 'foo' with the data read from '~/xss-exploit'. The replacement starts with '@' to indicate a file path.

```bash
mitmdump --modify-body :~q:foo:@~/xss-exploit
```

--------------------------------

### quic_start_server(data)

Source: https://docs.mitmproxy.org/stable/api/events.html

Called when TLS negotiation between mitmproxy and a server over QUIC is about to start. An addon is expected to initialize data.settings.

```APIDOC
## quic_start_server(data)

### Description
Called when TLS negotiation between mitmproxy and a server over QUIC is about to start. An addon is expected to initialize data.settings. (by default, this is done by `mitmproxy.addons.tlsconfig`)

### Signature
```python
def quic_start_server(data: mitmproxy.proxy.layers.quic._hooks.QuicTlsData)
```

### Parameters
- **data** (QuicTlsData) - The data object containing settings for the TLS negotiation.

```

--------------------------------

### Run mitmproxy console with addon

Source: https://docs.mitmproxy.org/stable/addons/commands/

Starts mitmproxy console with the simple command addon loaded. Use this to test the custom command.

```bash
> mitmproxy -s ./examples/addons/commands-simple.py

```

--------------------------------

### Create Headers with keyword arguments

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/http.html

Shows how to instantiate a Headers object using keyword arguments, e.g., host and content_type.

```python
>>> h = Headers(host="example.com", content_type="application/xml")
```

--------------------------------

### Configure pf with the rules

Source: https://docs.mitmproxy.org/stable/howto/transparent/

Run this command to load the pf rules from the pf.conf file.

```bash
sudo pfctl -f pf.conf
```

--------------------------------

### Configure pf with the rules

Source: https://docs.mitmproxy.org/stable/howto/transparent/

Load the pf rules from /etc/pf.conf using pfctl.

```bash
doas pfctl -f /etc/pf.conf
```

--------------------------------

### Start mitmproxy in transparent mode

Source: https://docs.mitmproxy.org/stable/howto/transparent/

Run mitmproxy with transparent mode and showhost. The --mode transparent option enables transparent mode, and --showhost uses the Host header for URL display.

```bash
mitmproxy --mode transparent --listen-host 127.0.0.1 --showhost
```

--------------------------------

### quic_start_client(data)

Source: https://docs.mitmproxy.org/stable/api/events.html

Called when TLS negotiation between mitmproxy and a client over QUIC is about to start. An addon is expected to initialize data.settings.

```APIDOC
## quic_start_client(data)

### Description
Called when TLS negotiation between mitmproxy and a client over QUIC is about to start. An addon is expected to initialize data.settings. (by default, this is done by `mitmproxy.addons.tlsconfig`)

### Signature
```python
def quic_start_client(data: mitmproxy.proxy.layers.quic._hooks.QuicTlsData)
```

### Parameters
- **data** (QuicTlsData) - The data object containing settings for the TLS negotiation.

```

--------------------------------

### Reverse proxy with custom listen ports

Source: https://docs.mitmproxy.org/stable/concepts/modes/

Runs two reverse proxy servers to example.com on ports 80 and 443 by appending @portnumber to the mode and passing --mode repeatedly.

```text
mitmdump --mode reverse:https://example.com@80 --mode reverse:https://example.com@443
```

--------------------------------

### Filter: Replace entire GET string in a request

Source: https://docs.mitmproxy.org/stable/concepts/filters/

Replaces the entire GET string in a request. Quotes are required to make it work.

```plaintext
":~q ~m GET:.*:/replacement.html"
```

--------------------------------

### tls_start_server(data: mitmproxy.tls.TlsData)

Source: https://docs.mitmproxy.org/stable/api/events.html

Called when TLS negotiation between mitmproxy and a server is about to start. An addon is expected to initialize data.ssl_conn.

```APIDOC
## tls_start_server(data: mitmproxy.tls.TlsData)

### Description
TLS negotiation between mitmproxy and a server is about to start. An addon is expected to initialize data.ssl_conn. (by default, this is done by `mitmproxy.addons.tlsconfig`)

### Parameters
- **data** (mitmproxy.tls.TlsData) - Required - The TLS data object.

```

--------------------------------

### Launch mitmproxy in transparent mode

Source: https://docs.mitmproxy.org/stable/howto/transparent/

Starts mitmproxy in transparent mode with the --showhost flag to display the Host header in the URL. This is the standard command for transparent proxying.

```bash
mitmproxy --mode transparent --showhost
```

--------------------------------

### tls_start_client(data: mitmproxy.tls.TlsData)

Source: https://docs.mitmproxy.org/stable/api/events.html

Called when TLS negotiation between mitmproxy and a client is about to start. An addon is expected to initialize data.ssl_conn.

```APIDOC
## tls_start_client(data: mitmproxy.tls.TlsData)

### Description
TLS negotiation between mitmproxy and a client is about to start. An addon is expected to initialize data.ssl_conn. (by default, this is done by `mitmproxy.addons.tlsconfig`)

### Parameters
- **data** (mitmproxy.tls.TlsData) - Required - The TLS data object.

```

--------------------------------

### running()

Source: https://docs.mitmproxy.org/stable/api/events.html

Called when the proxy is completely up and running. At this point, all addons are loaded and all options are set.

```APIDOC
## running()

### Description
Called when the proxy is completely up and running. At this point, you can expect all addons to be loaded and all options to be set.

### Method
running

### Parameters
None.
```

--------------------------------

### Client.__init__

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/connection.html

Constructor for the Client class. Initializes a new client connection with the given parameters.

```APIDOC
## Client.__init__

### Description
Constructor for the Client class. Initializes a new client connection with the given parameters.

### Method
Constructor

### Parameters
- **peername** (tuple[str, int]) - Required - The client's address.
- **sockname** (tuple[str, int]) - Required - The local address we received this connection on.
- **state** (ConnectionState) - Optional - The connection state. Defaults to ConnectionState.CLOSED.
- **id** (str) - Optional - The connection ID. Defaults to a generated value.
- **transport_protocol** (Literal['tcp', 'udp']) - Optional - The transport protocol. Defaults to 'tcp'.
- **error** (str | None) - Optional - An error message, if any.
- **tls** (bool) - Optional - Whether TLS is enabled. Defaults to False.
- **certificate_list** (Sequence[mitmproxy.certs.Cert]) - Optional - List of certificates. Defaults to ().
- **alpn** (bytes | None) - Optional - ALPN protocol. Defaults to None.
- **alpn_offers** (Sequence[bytes]) - Optional - ALPN offers. Defaults to ().
- **cipher** (str | None) - Optional - Cipher suite. Defaults to None.
- **cipher_list** (Sequence[str]) - Optional - List of ciphers. Defaults to ().
- **tls_version** (Literal['SSLv3', 'TLSv1', 'TLSv1.1', 'TLSv1.2', 'TLSv1.3', 'DTLSv0.9', 'DTLSv1', 'DTLSv1.2', 'QUICv1'] | None) - Optional - TLS version. Defaults to None.
- **sni** (str | None) - Optional - Server Name Indication. Defaults to None.
- **timestamp_start** (float) - Optional - Timestamp when TCP SYN was received. Defaults to a generated value.
- **timestamp_end** (float | None) - Optional - Timestamp when connection ended. Defaults to None.
- **timestamp_tls_setup** (float | None) - Optional - Timestamp when TLS was set up. Defaults to None.
- **mitmcert** (mitmproxy.certs.Cert | None) - Optional - The certificate used by mitmproxy to establish TLS with the client. Defaults to None.
- **proxy_mode** (mitmproxy.proxy.mode_specs.ProxyMode) - Optional - The proxy server type this client has been connecting to. Defaults to ProxyMode.parse('regular').

### Response
No return value.
```

--------------------------------

### block_list examples: google-analytics, example.com, allow-only

Source: https://docs.mitmproxy.org/stable/overview/features/

Three example block_list patterns: block google-analytics.com with 404, block example.com with 444 (no response), and allow only example.com with 403. The third pattern is not secure against active adversaries.

```text
:~d google-analytics.com:404
```

```text
:~d example.com$:444
```

```text
:!~d ^example\.com$:403
```

--------------------------------

### Request.port

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/http.html

Gets the target port of the request.

```APIDOC
## Request.port

### Description
Target port.

### Property
`port` (int)

### Access
Read-only
```

--------------------------------

### Explicit HTTP proxy GET request

Source: https://docs.mitmproxy.org/stable/concepts/how-mitmproxy-works/

Shows the format of a proxy GET request sent by a client to mitmproxy in explicit HTTP proxying. The request includes the full URL with scheme and host, which mitmproxy uses to connect to the upstream server.

```http
GET http://example.com/index.html HTTP/1.1
```

--------------------------------

### Run mitmproxy with custom certificate for specific domains

Source: https://docs.mitmproxy.org/stable/concepts/certificates/

Command to run mitmproxy with a custom certificate for specific subdomains using the --certs option with a domain pattern. The pattern *.example.com matches all subdomains, while www.example.com matches a particular subdomain.

```bash
mitmproxy --certs *.example.com=cert.pem
```

--------------------------------

### udp_start(flow)

Source: https://docs.mitmproxy.org/stable/api/events.html

Called when a UDP connection has started.

```APIDOC
## udp_start(flow)

### Description
Called when a UDP connection has started.

### Signature
```python
def udp_start(flow: mitmproxy.udp.UDPFlow)
```

### Parameters
- **flow** (UDPFlow) - The UDP flow that started.

```

--------------------------------

### tcp_start(flow)

Source: https://docs.mitmproxy.org/stable/api/events.html

Called when a TCP connection has started.

```APIDOC
## tcp_start(flow)

### Description
Called when a TCP connection has started.

### Signature
```python
def tcp_start(flow: mitmproxy.tcp.TCPFlow)
```

### Parameters
- **flow** (TCPFlow) - The TCP flow that started.

```

--------------------------------

### Cert.altnames

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/certs.html

Property to get all SubjectAlternativeName DNS altnames.

```APIDOC
## Cert.altnames

### Description
Property to get all SubjectAlternativeName DNS altnames.

### Property
`altnames`

### Returns
- **x509.GeneralNames** - The SAN entries.

```

--------------------------------

### Enable pf

Source: https://docs.mitmproxy.org/stable/howto/transparent/

Enable the pf firewall after loading the rules.

```bash
doas pfctl -e
```

--------------------------------

### Cert.serial

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/certs.html

Property to get the serial number of the certificate.

```APIDOC
## Cert.serial

### Description
Property to get the serial number of the certificate.

### Property
`serial`

### Returns
- **int** - The serial number.

```

--------------------------------

### Cert.fingerprint

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/certs.html

Method to get the SHA256 fingerprint of the certificate.

```APIDOC
## Cert.fingerprint

### Description
Method to get the SHA256 fingerprint of the certificate.

### Method
instance method

### Signature
`fingerprint(self) -> bytes`

### Returns
- **bytes** - The SHA256 fingerprint.

```

--------------------------------

### Compile and run mitmproxy_shim wrapper

Source: https://docs.mitmproxy.org/stable/howto/transparent/

Commands to compile the mitmproxy_shim.c wrapper, set its setuid bit, and run mitmproxy with transparent mode and spoof-source-address. Requires root privileges for the first three commands.

```bash
gcc examples/complex/full_transparency_shim.c -o mitmproxy_shim -lcap
sudo chown root:root mitmproxy_shim
sudo chmod u+s mitmproxy_shim
./mitmproxy_shim $(which mitmproxy) --mode transparent --set spoof-source-address
```

--------------------------------

### Cert.public_key

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/certs.html

Method to get the public key of the certificate.

```APIDOC
## Cert.public_key

### Description
Method to get the public key of the certificate.

### Method
instance method

### Signature
`public_key(self) -> CertificatePublicKeyTypes`

### Returns
- **CertificatePublicKeyTypes** - The public key.

```

--------------------------------

### ClientHello.__init__

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/tls.html

Creates a TLS ClientHello object from raw bytes.

```APIDOC
## ClientHello.__init__

### Description
Creates a TLS ClientHello object from raw bytes.

### Method
Constructor

### Parameters
- **raw_client_hello** (bytes) - Required - The raw ClientHello bytes.
- **dtls** (bool) - Optional - Whether the ClientHello is for DTLS. Defaults to False.

### Request Example
```python
client_hello = ClientHello(raw_client_hello, dtls=False)
```
```

--------------------------------

### Flow.timestamp_start

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/flow.html

Read-only property returning the start time of the flow.

```APIDOC
## Flow.timestamp_start

### Description
*Read-only:* Start time of the flow. Depending on the flow type, this property is an alias for `mitmproxy.connection.Client.timestamp_start` or `mitmproxy.http.Request.timestamp_start`.

### Type
float

### Access
Read-only

### Example
```python
start_time = flow.timestamp_start
```
```

--------------------------------

### Message.timestamp_start

Source: https://docs.mitmproxy.org/stable/api/mitmproxy/http.html

Property to get or set the timestamp when headers were received.

```APIDOC
## Property: timestamp_start

### Description
Gets or sets the timestamp when headers were received.

### Signature
```python
@property
def timestamp_start(self) -> float

@timestamp_start.setter
def timestamp_start(self, timestamp_start: float) -> None
```

### Parameters
- **timestamp_start** (float) - Required - The timestamp to set.

### Returns
- **float** - The timestamp.

### Example
```python
message.timestamp_start = 1234567890.0
ts = message.timestamp_start
```
```

--------------------------------

### Ignore patterns for various use cases

Source: https://docs.mitmproxy.org/stable/howto/ignore-domains/

A set of example ignore patterns for different scenarios: iOS App Store, example.com with and without subdomains, and transparent mode with IP addresses.

```bash
# Exempt traffic from the iOS App Store (the regex is lax, but usually just works):
--ignore-hosts apple.com:443
# "Correct" version without false-positives:
--ignore-hosts '^(.+\.)?apple\.com:443$'

# Ignore example.com, but not its subdomains:
--ignore-hosts '^example.com:'

# Transparent mode:
--ignore-hosts 17\.178\.96\.59:443
# IP address range:
--ignore-hosts 17\.178\.\d+\.\d+:443
```
Tokens:
Raw