Edit on GitHub

#  Options

The mitmproxy tools share a common YAML configuration file located at ~/.mitmproxy/config.yaml. This file controls options - typed values that determine the behaviour of mitmproxy. The options mechanism is very comprehensive - in fact, options control all of mitmproxy’s runtime behaviour. Most command-line flags are simply aliases for underlying options, and interactive settings changes made in mitmproxy and mitmweb just change values in our runtime options store. This means that almost any facet of mitmproxy’s behaviour can be controlled through options.

The canonical reference for options is the --options flag, which is exposed by each of the mitmproxy tools. Passing this flag will dump an annotated YAML configuration to console, which includes all options and their default values.

The options mechanism is extensible - third-party addons can define options that are treated exactly like mitmproxy’s own. This means that addons can also be configured through the central configuration file, and their options will appear in the options editors in interactive tools.

#  Tools

Both mitmproxy and mitmweb have built-in editors that let you view and manipulate the complete configuration state of mitmproxy. Values you change interactively have immediate effect in the running instance, and can be made persistent by saving the settings out to a YAML configuration file (please see the specific tool’s interactive help for details on how to do this).

For all tools, options can be set directly by name using the --set command-line option. Please see the command-line help (--help) for usage.

#  Available Options

This list might not reflect what is actually available in your current mitmproxy environment. For an up-to-date list please use the --options flag for each of the mitmproxy tools.

Name Type Description
add_upstream_certs_to_client_chain
mitmproxy mitmdump mitmweb
bool Add all certificates of the upstream server to the certificate chain that will be served to the proxy client, as extras.
Default: False
anticache
mitmproxy mitmdump mitmweb
bool Strip out request headers that might cause the server to return 304-not-modified.
Default: False
anticomp
mitmproxy mitmdump mitmweb
bool Try to convince servers to send us un-compressed data.
Default: False
block_global
mitmproxy mitmdump mitmweb
bool Block connections from globally reachable networks, as defined in the IANA special purpose registries.
Default: True
block_private
mitmproxy mitmdump mitmweb
bool Block connections from private networks, as defined in the IANA special purpose registries. This option does not affect loopback addresses.
Default: False
body_size_limit
mitmproxy mitmdump mitmweb
optional str Byte size limit of HTTP request and response bodies. Understands k/m/g suffixes, i.e. 3m for 3 megabytes.
Default: None
certs
mitmproxy mitmdump mitmweb
sequence of str SSL certificates of the form "[domain=]path". The domain may include a wildcard, and is equal to "*" if not specified. The file at path is a certificate in PEM format. If a private key is included in the PEM, it is used, else the default key in the conf dir is used. The PEM file should contain the full certificate chain, with the leaf certificate as the first entry.
Default: []
ciphers_client
mitmproxy mitmdump mitmweb
optional str Set supported ciphers for client connections using OpenSSL syntax.
Default: None
ciphers_server
mitmproxy mitmdump mitmweb
optional str Set supported ciphers for server connections using OpenSSL syntax.
Default: None
client_certs
mitmproxy mitmdump mitmweb
optional str Client certificate file or directory.
Default: None
client_replay
mitmproxy mitmdump mitmweb
sequence of str Replay client requests from a saved file.
Default: []
confdir
mitmproxy mitmdump mitmweb
str Location of the default mitmproxy configuration files.
Default: ~/.mitmproxy
console_default_contentview
mitmproxy
str The default content view mode.
Default: auto
Choices: auto, raw, hex, json, xml/html, wbxml, javascript, css, url-encoded, multipart form, image, query, protocol buffer
console_eventlog_verbosity
mitmproxy
str EventLog verbosity.
Default: info
Choices: error, warn, info, alert, debug
console_focus_follow
mitmproxy mitmweb
bool Focus follows new flows.
Default: False
console_layout
mitmproxy
str Console layout.
Default: single
Choices: horizontal, single, vertical
console_layout_headers
mitmproxy
bool Show layout component headers
Default: True
console_mouse
mitmproxy
bool Console mouse interaction.
Default: True
console_palette
mitmproxy
str Color palette.
Default: solarized_dark
Choices: dark, light, lowdark, lowlight, solarized_dark, solarized_light
console_palette_transparent
mitmproxy
bool Set transparent background for palette.
Default: False
dumper_default_contentview
mitmdump
str The default content view mode.
Default: auto
Choices: auto, raw, hex, json, xml/html, wbxml, javascript, css, url-encoded, multipart form, image, query, protocol buffer
dumper_filter
mitmdump
optional str Limit which flows are dumped.
Default: None
flow_detail
mitmdump
int The display detail level for flows in mitmdump: 0 (almost quiet) to 3 (very verbose). 0: shortened request URL, response status code, WebSocket and TCP message notifications. 1: full request URL with response status code 2: 1 + HTTP headers 3: 2 + full response content, content of WebSocket and TCP messages.
Default: 1
http2
mitmproxy mitmdump mitmweb
bool Enable/disable HTTP/2 support. HTTP/2 support is enabled by default.
Default: True
http2_priority
mitmproxy mitmdump mitmweb
bool PRIORITY forwarding for HTTP/2 connections. Disabled by default to ensure compatibility with misbehaving servers.
Default: False
ignore_hosts
mitmproxy mitmdump mitmweb
sequence of str Ignore host and forward all traffic without processing it. In transparent mode, it is recommended to use an IP address (range), not the hostname. In regular mode, only SSL traffic is ignored and the hostname should be used. The supplied value is interpreted as a regular expression and matched on the ip or the hostname.
Default: []
intercept
mitmproxy mitmweb
optional str Intercept filter expression.
Default: None
intercept_active
mitmproxy mitmweb
bool Intercept toggle
Default: False
keep_host_header
mitmproxy mitmdump mitmweb
bool Reverse Proxy: Keep the original host header instead of rewriting it to the reverse proxy target.
Default: False
keepserving
mitmdump
bool Continue serving after client playback, server playback or file read. This option is ignored by interactive tools, which always keep serving.
Default: False
listen_host
mitmproxy mitmdump mitmweb
str Address to bind proxy to.
Default:
listen_port
mitmproxy mitmdump mitmweb
int Proxy service port.
Default: 8080
mode
mitmproxy mitmdump mitmweb
str Mode can be "regular", "transparent", "socks5", "reverse:SPEC", or "upstream:SPEC". For reverse and upstream proxy modes, SPEC is host specification in the form of "http[s]://host[:port]".
Default: regular
onboarding
mitmproxy mitmdump mitmweb
bool Toggle the mitmproxy onboarding app.
Default: True
onboarding_host
mitmproxy mitmdump mitmweb
str Onboarding app domain. For transparent mode, use an IP when a DNS entry for the app domain is not present.
Default: mitm.it
onboarding_port
mitmproxy mitmdump mitmweb
int Port to serve the onboarding app from.
Default: 80
proxyauth
mitmproxy mitmdump mitmweb
optional str Require proxy authentication. Format: "username:pass", "any" to accept any user/pass combination, "@path" to use an Apache htpasswd file, or "ldap[s]:url_server_ldap:dn_auth:password:dn_subtree" for LDAP authentication.
Default: None
rawtcp
mitmproxy mitmdump mitmweb
bool Enable/disable experimental raw TCP support. TCP connections starting with non-ascii bytes are treated as if they would match tcp_hosts. The heuristic is very rough, use with caution. Disabled by default.
Default: False
readfile_filter
mitmproxy mitmdump mitmweb
optional str Read only matching flows.
Default: None
replacements
mitmproxy mitmdump mitmweb
sequence of str Replacement patterns of the form "/pattern/regex/replacement", where the separator can be any character.
Default: []
rfile
mitmproxy mitmdump mitmweb
optional str Read flows from file.
Default: None
save_stream_file
mitmproxy mitmdump mitmweb
optional str Stream flows to file as they arrive. Prefix path with + to append.
Default: None
save_stream_filter
mitmproxy mitmdump mitmweb
optional str Filter which flows are written to file.
Default: None
scripts
mitmproxy mitmdump mitmweb
sequence of str Execute a script.
Default: []
server
mitmproxy mitmdump mitmweb
bool Start a proxy server. Enabled by default.
Default: True
server_replay
mitmproxy mitmdump mitmweb
sequence of str Replay server responses from a saved file.
Default: []
server_replay_ignore_content
mitmproxy mitmdump mitmweb
bool Ignore request's content while searching for a saved flow to replay.
Default: False
server_replay_ignore_host
mitmproxy mitmdump mitmweb
bool Ignore request's destination host while searching for a saved flow to replay.
Default: False
server_replay_ignore_params
mitmproxy mitmdump mitmweb
sequence of str Request's parameters to be ignored while searching for a saved flow to replay.
Default: []
server_replay_ignore_payload_params
mitmproxy mitmdump mitmweb
sequence of str Request's payload parameters (application/x-www-form-urlencoded or multipart/form-data) to be ignored while searching for a saved flow to replay.
Default: []
server_replay_kill_extra
mitmproxy mitmdump mitmweb
bool Kill extra requests during replay.
Default: False
server_replay_nopop
mitmproxy mitmdump mitmweb
bool Don't remove flows from server replay state after use. This makes it possible to replay same response multiple times.
Default: False
server_replay_refresh
mitmproxy mitmdump mitmweb
bool Refresh server replay responses by adjusting date, expires and last-modified headers, as well as adjusting cookie expiration.
Default: True
server_replay_use_headers
mitmproxy mitmdump mitmweb
sequence of str Request headers to be considered during replay.
Default: []
setheaders
mitmproxy mitmdump mitmweb
sequence of str Header set pattern of the form "/pattern/header/value", where the separator can be any character.
Default: []
showhost
mitmproxy mitmdump mitmweb
bool Use the Host header to construct URLs for display.
Default: False
spoof_source_address
mitmproxy mitmdump mitmweb
bool Use the client's IP for server-side connections. Combine with --upstream-bind-address to spoof a fixed source address.
Default: False
ssl_insecure
mitmproxy mitmdump mitmweb
bool Do not verify upstream server SSL/TLS certificates.
Default: False
ssl_verify_upstream_trusted_ca
mitmproxy mitmdump mitmweb
optional str Path to a PEM formatted trusted CA certificate.
Default: None
ssl_verify_upstream_trusted_confdir
mitmproxy mitmdump mitmweb
optional str Path to a directory of trusted CA certificates for upstream server verification prepared using the c_rehash tool.
Default: None
ssl_version_client
mitmproxy mitmdump mitmweb
str Set supported SSL/TLS versions for client connections. SSLv2, SSLv3 and 'all' are INSECURE. Defaults to secure, which is TLS1.0+.
Default: secure
Choices: all, secure, SSLv2, SSLv3, TLSv1, TLSv1_1, TLSv1_2
ssl_version_server
mitmproxy mitmdump mitmweb
str Set supported SSL/TLS versions for server connections. SSLv2, SSLv3 and 'all' are INSECURE. Defaults to secure, which is TLS1.0+.
Default: secure
Choices: all, secure, SSLv2, SSLv3, TLSv1, TLSv1_1, TLSv1_2
stickyauth
mitmproxy mitmdump mitmweb
optional str Set sticky auth filter. Matched against requests.
Default: None
stickycookie
mitmproxy mitmdump mitmweb
optional str Set sticky cookie filter. Matched against requests.
Default: None
stream_large_bodies
mitmproxy mitmdump mitmweb
optional str Stream data to the client if response body exceeds the given threshold. If streamed, the body will not be stored in any way. Understands k/m/g suffixes, i.e. 3m for 3 megabytes.
Default: None
stream_websockets
mitmproxy mitmdump mitmweb
bool Stream WebSocket messages between client and server. Messages are captured and cannot be modified.
Default: False
tcp_hosts
mitmproxy mitmdump mitmweb
sequence of str Generic TCP SSL proxy mode for all hosts that match the pattern. Similar to --ignore, but SSL connections are intercepted. The communication contents are printed to the log in verbose mode.
Default: []
termlog_verbosity
mitmdump mitmweb
str Log verbosity.
Default: info
Choices: error, warn, info, alert, debug
upstream_auth
mitmproxy mitmdump mitmweb
optional str Add HTTP Basic authentication to upstream proxy and reverse proxy requests. Format: username:password.
Default: None
upstream_bind_address
mitmproxy mitmdump mitmweb
str Address to bind upstream requests to.
Default:
upstream_cert
mitmproxy mitmdump mitmweb
bool Connect to upstream server to look up certificate details.
Default: True
view_filter
mitmproxy mitmweb
optional str Limit the view to matching flows.
Default: None
view_order
mitmproxy mitmweb
str Flow sort order.
Default: time
Choices: time, method, url, size
view_order_reversed
mitmproxy mitmweb
bool Reverse the sorting order.
Default: False
web_debug
mitmweb
bool Enable mitmweb debugging.
Default: False
web_iface
mitmweb
str Web UI interface.
Default: 127.0.0.1
web_open_browser
mitmweb
bool Start a browser.
Default: True
web_port
mitmweb
int Web UI port.
Default: 8081
web_static_viewer
mitmweb
optional str The path to output a static viewer.
Default:
websocket
mitmproxy mitmdump mitmweb
bool Enable/disable WebSocket support. WebSocket support is enabled by default.
Default: True